Skip to content

BRAIN.md

Latest commit

 

History

History
89 lines (73 loc) · 6.21 KB

BRAIN.md

File metadata and controls

89 lines (73 loc) · 6.21 KB
Raw

🧠 Professional Brain — memory + actions for the skills

Local-first memory for any AI agent. A plain-markdown brain your AI reads before it answers and writes to after — provenance-tagged, grep-able, auditable. No vector DB, no cloud. It ships inside this library, but the idea stands alone: give your agent a memory you can read and correct by hand.

Just want to use it? → 5-minute Quickstart (a folder + one file; MCP optional). This page is the architecture.

Status: Phase 2 (actions). The full loop is in: skills read the brain, write provenance-tagged records back (Phase 1), and now execute their recommendations — opening tickets, posting updates — via the action-runner skill: dry-run preview, per-action risk gate, approval-gated, then recorded back to the brain. A shared MCP "brain server" (one brain across n8n / Lovable / the playground) is the next step.

The skills library is great at producing a document. What it can't do yet is remember — every run starts cold, and the why behind past decisions evaporates. The Professional Brain adds the missing layer: a durable, local markdown memory that skills read before they answer and write to after.

Pair that memory with an action layer (skills that file the tickets / open the PRs they recommend) and the library stops being a document generator and becomes a teammate:

recall (brain) → run a skill (method) → produce the artifact → propose actions
   → approve → execute → record the decision + provenance back (brain) → weekly review

What's shipped (Phases 0–1)

  • professional-brain — the skill defining the brain schema, the provenance-tag convention, and five operations: init, ingest, recall, record, review.
  • scripts/brain_query.py — stdlib-only, grep-based recall that returns matches ranked by provenance strength (no vector DB).
  • scripts/brain_write.py — the write-back half: append-only, dry-run-by-default, approval-gated record-writing (Phase 1).
  • action-runner + action_preview.py — the action layer (Phase 2): turn a skill's recommendations into executed actions (tickets, messages) with a dry-run preview, per-action risk gate, approval, and auto-record back to the brain.
  • templates/brain/ — a copyable, filled-in scaffold (Obsidian-vault compatible) so the loop is tangible from minute one.
  • In-browser Brain — a zero-install version of the brain in the playground: edit the six sections on the 🧠 Brain page, toggle "use my brain in every run" and it's prepended (recall) to every skill, and hit 🧠 Save to Brain on any output to write a provenance-tagged fact back. Stored only in your browser (localStorage), and it round-trips with the on-disk brain/ folder via markdown import/export.
  • /brain slash command.
  • 18 skills made brain-aware — each carries a "Reads from / Writes to the Brain" contract (e.g. prd-template reads strategy/context & writes the feature entity; meeting-notes writes decisions; metrics-framework, incident-postmortem, user-research-synthesis, go-to-market, stakeholder-update, product-launch-checklist, and the new AI/growth skills, among others).
  • Action targets for action-runner: GitHub, Linear/Jira, Slack, Notion, Email, and Calendar — each with example ops and a default risk level (outbound messages are 🔴, approval-gated by default).

The brain schema

brain/
  context.md      knowledge/   decisions/   hypotheses/   stakeholders/   entities/   source/   predictions/

Every fact is provenance-tagged — [data] [interview] [external] [verbal] [hunch] (strongest → weakest) — so skills can downgrade confidence on weak evidence instead of treating a hunch as settled.

predictions/ is the outcome-tracking ledger: when a decision skill commits to a claim (a RICE impact, a forecast number, a launch metric), the outcome-tracker skill records it here as a falsifiable prediction with a check-by date — and later scores it against reality, so frameworks accumulate a real calibration record instead of a reputation.

The roadmap

Phase Scope Status
0 — Proof brain schema + provenance + recall helper + 2 brain-aware skills ✅ shipped
1 — Write-back record operation + brain_write.py (append-only, dry-run, approval-gated) + the "📥 Propose to the Brain" block, rolled across high-value skills ✅ shipped
2 — External actions the action-runner skill: a dry-run executor for external actions (open tickets, post updates) with action_preview.py risk-gating, approval per high-risk action, then auto-record back to the brain. Wired into product-launch-checklist, sprint-planning, incident-postmortem. ✅ shipped
3 — Shared brain & generalise an in-browser brain in the playground (recall + write-back, markdown round-trip with the files) ✅; next: an MCP "brain server" so n8n / Lovable / the playground share one brain; profession brains (CS, founder, legal); more action targets (Notion, Slack, calendar); a /brain review sweep and scenario eval suite in progress

Design principles

  • Local-first, plain markdown. Grep-able, human-editable, auditable. No embeddings hiding the reasoning.
  • Provenance over confidence theatre. A claim's strength is explicit and travels with it.
  • Append, don't overwrite. Decisions accrete history; the audit trail in source/ is never edited.
  • Actions are the scariest surface. Write-back is dry-run by default, scope-limited, approval-gated, and append-only — nothing is written without a yes. External actions (Phase 2) will hold to the same bar.