optimal-brain

optimal-brain

Give your coding agent a long-term memory: every research session becomes linked, sourced Obsidian notes it reads back next time.

optimal-brain is a skills stack for research and long-term knowledge work. It adds three layers on top of a solid engineering skill set:

1. Vault memory: an Obsidian vault becomes the agent's durable memory. Research is captured as sourced notes with confidence levels and supersession rules, and read back in later sessions.
2. Loops: goal-based agent loops (Plan → Act → Observe → Verify → Stop) with explicit, per-repo stop rules.
3. Architect: a system-architecture orchestrator that works across 10 competence roles and produces a session hub, ADRs, and a delivery handoff.

flowchart LR
  subgraph External[External Research Layer]
    D["davidondrej research-and-web\n(browser, YT, APIs, web)"]
  end
  subgraph Memory[Personal Memory / Vault]
    V["Obsidian Vault\n(PDFs, notes, sources)"]
    LRV["Vault Learning Records\n(wikilinked)"]
    KV["docs/agents/knowledge-vault.md"]
  end
  subgraph Synthesis["Synthesis & Capture"]
    RV["research-from-vault (model)"]
    T["/teach (user)"]
  end
  subgraph Execution["Engineering Execution + Loops"]
    AL["agent-loop + /until-done"]
    ENG["grill-with-docs, domain-modeling,\ntdd, implement, ..."]
    ASK["/ask-brain (router)"]
  end
  D -->|"pull fresh\nmaterial"| V
  V --> RV
  RV --> LRV
  T --> LRV
  AL -->|"knowledge gap"| RV
  ENG -->|"ground terms/decisions"| RV
  ASK --> T
  ASK --> RV
  ASK -->|"install + use davidondrej\nthen synthesize"| D

Layered architecture (details in docs/OPTIMAL-BRAIN.md).

Credits

optimal-brain is an MIT-licensed fork of mattpocock/skills by Matt Pocock. The engineering fundamentals (grilling, domain modeling, TDD, PRDs/issues, codebase design, teach, and the overall skill model) come from there. External research ingestion is designed to work with davidondrej/skills by David Ondrej (research-and-web). See LICENSE for both copyright notices.

What's new vs mattpocock/skills

Quick start (Lite: vault memory only)

1. Install:

   npx skills@latest add chidiokoene/optimal-brain
   

   Select at least setup-knowledge-vault and research-from-vault (add project-notes and vault-context-canvas if you like).

2. In your agent, run /setup-knowledge-vault and point it at your Obsidian vault.

3. Ask the agent to research something using your vault, e.g. "research X using my vault". research-from-vault writes linked, sourced notes back into the vault, and later sessions read them back.

Optional layers:

• Loops: install setup-agent-loops, agent-loop, until-done; run /setup-agent-loops once per repo, then /until-done <goal>.
• Architect: install system-architect, then /system-architect for discovery, as-is review, target design, or migration.
• Engineering base: run /setup-optimal-brain once per repo before to-prd, to-issues, triage.
• External research: npx skills@latest add davidondrej/skills and pick research-and-web to feed fresh material into the vault.
• Git: the setup skills gitignore your personal vault config (.agent/context/knowledge-vault.md, project-context.md, .scratch/) and tell you what to commit. Teams can share a knowledge-vault.example.md template. See AGENT-CONTEXT-PATH.md.
• Also using gstack? See docs/WITH-GSTACK.md.
• Not sure where to start? Use /ask-brain. For a full walkthrough see docs/PLAYBOOK.md.

Skill index

Vault memory layer

• setup-knowledge-vault (user): configure vault location, learning records, PDFs, context graph, and recipes for ingestion.
• seed-vault-from-repo (user): seed the vault from an existing repo: per-unit Findings, Decision Traces, Plans, and a Shared contracts layer, all citing paths and commit; re-sync updates only stale notes.
• research-from-vault (model): research and synthesize with the vault as the primary source; captures findings per RESEARCH-CAPTURE-FORMAT.md.
• project-notes (user): capture personal notes under {ProjectFolder}/Personal Notes/.
• vault-context-canvas (user): create or refresh an Obsidian JSON Canvas context graph.
• decision-mapping (user): turn a loose idea into a sequenced map of investigation tickets and drive them to resolution.
• teach (user): multi-session teaching workspace, bridged to the vault.
• write-from-vault (user): turn vault research into a sourced article (fragments → shape → beats) with a claim ledger; every claim traced to a note, superseded notes never cited.
• vault-sync (model): keep the vault current: diff git since the last sync, update or flag stale notes, capture missed decisions and review findings, append a session note.

Loops layer

• setup-agent-loops (user): verification commands, stop rules, scope, starter recipes. Run once per repo. Also has a design-a-custom-workflow path for specifying your own recurring workflows.
• agent-loop (model): Plan → Act → Observe → Verify → Stop discipline.
• until-done (user): run a goal-based loop until verification passes or a stop rule fires.
• implement (user): implement a PRD or issue using agent-loop discipline, gated by /two-axis-review.
• two-axis-review (model): two-axis review (Standards vs Spec) plus correctness, security, and tests; conventional-comments findings with severities and a PASS/FAIL verdict that loops use as a gate.

Architect layer

• system-architect (user): orchestrate architecture across up to 6 of 10 role briefs into a session hub, ADRs, and a /to-prd handoff.

Router and setup

• ask-brain (user + model): routes any task to the best skill or chain of skills across the whole pack.
• setup-optimal-brain (user): issue tracker, triage labels, domain doc layout.

Engineering base (from mattpocock/skills)

• User-invoked: grill-with-docs, triage, improve-codebase-architecture, to-issues, to-prd, prototype, grill-me, handoff, writing-great-skills
• Model-invoked: diagnosing-bugs, tdd, domain-modeling, codebase-design, resolving-merge-conflicts, grilling

Misc (not in the plugin manifest)

• git-guardrails-claude-code: Claude Code hooks that block dangerous git commands.
• setup-pre-commit: Husky + lint-staged pre-commit hooks.

User-invoked skills run when you type them (e.g. /until-done); model-invoked skills can also be picked up automatically by the agent when the task fits.

Agent compatibility

Skills are plain SKILL.md folders (the Agent Skills format), so any agent that reads that format should be able to load them. What the repo actually backs up:

Reports for untested agents are welcome via issues.

Local development

./scripts/list-skills.sh   # list every SKILL.md
./scripts/link-skills.sh   # symlink skills into ~/.claude/skills and ~/.agents/skills

Contributing

Agensi listing and zip build: docs/AGENSI.md. See CONTRIBUTING.md for how skills are organized and what a PR needs, and docs/ROADMAP.md for where the project is going. This project follows the Contributor Covenant.

License

MIT. See LICENSE.