CéRebro

A structured Obsidian vault designed to give AI coding agents (opencode, Claude, Cursor) persistent memory, project context, and operational knowledge across sessions.

What is this?

Cérebro is a knowledge management system that bridges the gap between AI coding sessions. Instead of losing context between conversations, your vault retains:

• Project context — stack, architecture, decisions, current state
• Session logs — what was done, what's pending, what's next
• Technical decisions — ADRs with rationale and alternatives
• Patterns & lessons — failure patterns, prevention checklists, reusable knowledge
• Operational runbooks — deploy, debug, rollback procedures

Quick Start

# Clone this repo
git clone https://github.com/ricardopiresqa/cerebro.git

# Open in Obsidian
# File → Open Vault → select the cloned folder

# Set up environment
cp .env.example .env
# Edit .env with your paths

Vault Structure

Cérebro/
├── _templates/         ← Templates for projects, ADRs, runbooks, lessons
├── 0_inbox/            ← Drafts and uncategorized ideas
├── 1_projetos/         ← Active projects (CONTEXT.md + DECISIONS.md + CURRENT.md)
├── 2_knowledge/        ← Knowledge base (guides, studies, career)
├── 3_playbooks/        ← Reusable process playbooks
├── 4_runbooks/         ← Operational runbooks
├── 5_adrs/             ← Architecture Decision Records
├── 6_postmortems/      ← Incident postmortems
├── 7_research/         ← Research and proofs of concept
├── 8_patterns/         ← Code/architecture patterns and lessons
├── 9_standards/        ← Vault conventions
└── 10_glossary/        ← Technical glossary

How It Works

Project Files

Every project gets three mandatory files:

File	Purpose
CONTEXT.md	Stack, structure, repo URL, what it is
DECISIONS.md	Technical decisions (chronological)
CURRENT.md	Current state, blockers, next step

Session Lifecycle

START SESSION
  1. Read CONTEXT.md + DECISIONS.md + last session log
  2. Search RAG for relevant history
  3. Load applicable skill
  4. Work

END SESSION
  5. Log session in sessoes/
  6. Reindex RAG
  7. Update DECISIONS.md if new decisions made

Adding a Project

1. Create 1_projetos/<project-name>/
2. Add CONTEXT.md with stack, structure, and repo info
3. Add DECISIONS.md with initial decisions
4. Add CURRENT.md with current state
5. Optionally create a ClickUp card and link it

Templates

Template	Use Case
adr.md	Architecture Decision Record
CURRENT-template.md	Project current state
DECISIONS-template.md	Technical decisions log
sessao-template.md	Session log
LESSON-template.md	Learned lesson
runbook.md	Operational procedure
postmortem.md	Incident postmortem
onboarding.md	Project onboarding checklist
lefthook-default.yml	Git hooks config

Features

• Deterministic navigation — numbered folders (0-10) for predictable structure
• Fuzzy search — RAG-powered hybrid search (vector + BM25) across all markdown
• AI agent integration — steering files tell agents how to behave in your vault
• Session persistence — every coding session is logged with decisions and context
• Self-improvement — pattern mining, failure analysis, skill effectiveness tracking

Integrations

• opencode — reads vault context automatically
• Obsidian — renders markdown with Dataview for dashboards
• ClickUp — task management via API
• RAG — hybrid search with ChromaDB + BM25

Philosophy

Your AI agent should never start from zero. Every session builds on the last.

License

MIT