Brain

Persistent knowledge that survives across conversations. The brain is an Obsidian vault at ~/.osdu-brain (configurable via $OSDU_BRAIN) that stores your goals, decisions, reports, and reference material. When initialized, the system searches the vault before making recommendations and writes back what it learns. The vault is optional; all skills still work without it, but without persistent knowledge.

Knowledge Flow

Knowledge moves through the system in a defined pipeline:

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#036A6E', 'primaryTextColor': '#fff', 'primaryBorderColor': '#034f52', 'lineColor': '#036A6E', 'secondaryColor': '#0a8f94', 'tertiaryColor': '#0a8f94'}}}%%
graph LR
    A[Discover] --> B[Fetch] --> C[Distill] --> D[Write] --> E[Index] --> F[Retrieve]

"Learn about the OSDU Partition service from the wiki"

1. learn skill fetches GitLab wiki pages for os-partition
2. learn skill distills: API endpoints, data model, dependencies
3. brain skill writes to 03-knowledge/osdu-partition.md
4. qmd embed re-indexes, note available for future searches
5. In a later session, the system retrieves that partition context automatically

How to Use the Vault

Reading: When the vault is initialized and indexed, the default assistant searches it automatically before making recommendations. You can also ask directly: "What did we decide about CNPG?" or "Show me the last dependency report for partition." Without the vault, recommendations are based on session context only.

Writing: Do not write to the vault files directly. Use the brain skill by asking: "Record this decision" or "Save what we learned today." Templates are applied automatically.

Maintaining: Run /consolidate monthly. Notes older than 90 days are flagged for review. Human-curated knowledge (source: human) never decays.

Session Digests

At the end of each meaningful session, if the vault exists, the system appends a structured digest to the current daily note (00-inbox/YYYY-MM-DD.md). This provides episodic memory so the next session can pick up context without re-explaining. Without the vault, session context is not persisted.

Digests are appended, never overwritten — multiple sessions per day stack. Only meaningful sessions get a digest; no digest is created for trivial exchanges like "hello" or "what time is it."

Vault Structure

~/.osdu-brain/         # Default location (override with $OSDU_BRAIN)
├── 00-inbox/          # Landing zone for daily briefings
├── 01-goals/          # Quarterly objectives with key results
├── 02-projects/       # Project monitoring configs
├── 03-knowledge/      # Durable reference material
├── 04-reports/        # Generated reports
├── attachments/       # Images, diagrams, embedded files
└── templates/         # Note templates (read-only)

Write Discipline

Not everything belongs in the vault. The brain skill enforces these boundaries:

Note Types and Templates

Templates live in skills/brain/scaffold/templates/ and define the structure for each note type:

Vault Search

The QMD MCP server provides hybrid search (BM25 + vector + cross-encoder reranking) over the vault. When the vault is initialized and indexed, agents use it to inform their work:

• The default assistant searches for goals and prior decisions before making recommendations
• @osdu searches for past QA reports before analyzing test results
• @cimpl searches for architecture decisions before suggesting infrastructure changes

If QMD is not configured or the vault does not exist, agents still work — they simply lack historical knowledge.

See Capabilities — Extensions and MCP Servers for QMD tool details and configuration.

Keeping the Brain Accurate

The vault is designed to be low-maintenance. Templates ship with the plugin, content stays local to each developer, and reindexing runs automatically on file changes. But knowledge has a lifecycle, and without periodic maintenance, stale notes degrade recommendations.

How Knowledge Enters

Learning: Ask "learn about the OSDU Partition service from the wiki" to acquire knowledge from external sources. The learn skill fetches, distills, and writes structured notes. It updates existing notes when sources change.

Decisions and digests: As you work, the brain accumulates context automatically. Key decisions are recorded to 03-knowledge/. Session digests capture what happened, what was decided, and what questions remain.

How Knowledge Ages

Running Consolidation

Run /consolidate monthly. The consolidate skill:

1. Scans all notes in 03-knowledge/ for last-verified age
2. Cross-references related notes for contradictions
3. Reports findings without deleting — you decide what to archive
4. Updates last-verified on notes confirmed as still accurate