--- title: "The Brain" description: "o8's queryable memory — a cited map of how your project actually works, built from your specs, PRs, and every agent session." canonical_url: https://o8.run/docs/the-brain md_url: https://o8.run/docs/the-brain.md last_updated: 2026-06-25 version: "0.1.431" stability: stable --- # The Brain > o8's queryable memory — a cited map of how your project actually works, built from your specs, PRs, and every agent session. Every coding-agent IDE is stateless: sessions start from zero, agents don't know what happened yesterday, and what your project knows lives in people's heads and scattered docs — never in the tool where the work happens. The Brain is o8's answer: a **queryable map of how your project actually works**, living on your machine, answering questions with cited sources. It's not file search, and it's not a vector index of raw code. It's a store of **distilled facts** — decisions, specs, processes, incidents, ownership, cross-repo invariants — each with a type, a confidence, and a source you can trace. ## What it solves When you (or a dispatched agent) ask "why is it built this way?", "who owns this?", or "what shipped last week?", the Brain answers from what your project has actually done — not a guess from whatever happens to be in context. Dispatched workers consult it instead of burning their context window searching files, and every answer comes back **cited**. It runs **local-first** — knowledge is stored in a database on your machine, and embeddings can run on a small model (local or hosted), so the Brain needs no cloud keys and your code never leaves the machine. It's free with your own CLI subscriptions. ## How it's built The Brain fills itself from the work you're already doing. An indexer reads your knowledge sources — merged PRs, your canonical specs (`CLAUDE.md`, `AGENTS.md`, `DESIGN.md`, `docs/`), review comments, and the outcome of every agent session — and **distills** them into durable facts. Each fact carries a **kind** (decision, spec, process, incident, ownership, cross-repo, directive) plus a confidence and the source it came from. Three guards keep the store honest: - **Verbatim provenance** — a fact's quoted excerpt must be a character-for-character substring of its source, or it's rejected. The Brain can't invent a name, number, or filename that isn't in the source. - **A confidence floor** — low-confidence extractions are dropped, not stored. - **Idempotent writes** — facts are fingerprinted, so re-indexing never duplicates. Not every source is equal. The Brain weights authority: your declared directives outrank merged PRs, which outrank closed session outcomes, which outrank conversational comments (opinions, not project rules). The longer o8 runs on your project, the deeper the Brain gets — written as much by your agents as by you. ## Two layers of memory The Brain holds two kinds of memory, doing different jobs: - **Explicit — directives.** The rules you *declare*: conventions, constraints, architecture decisions. You author and prioritize them in **Memory → Directives** (global or per-repo), and o8 injects the highest-priority ones into agents' prompts before they start — within a token budget, so the most important rules always make it in. Your canonical specs are ingested here automatically as high-authority directives. - **Implicit — the session ledger + distilled facts.** What the system *learns*: every agent run writes an outcome when it exits, and facts are distilled from PRs and docs as they land. This is the layer that answers "what shipped, and why." The explicit layer steers agents before they run; the implicit layer remembers what actually happened. ## How you ask it You query the Brain in plain language and get one cited answer. It's reachable from the **Brain card** on the canvas, the scratch chat ("Ask the Engineering Brain"), from a dispatched worker via `o8 ask` (which records that the worker consulted the Brain, with its sources), and from any external agent through the `cortex_ask` MCP tool. Under the hood, every question runs **classify → retrieve → compose**: - **Classify** — is this a lookup (who / when / where) or a reasoning question (why / how)? That decides how much it pulls. - **Retrieve** — several retrievers run in parallel — structured SQL, keyword (BM25) full-text, a knowledge graph, and the pre-extracted facts — and their results are fused, so keyword, semantic, and structured matches all get a vote. High-trust facts and freshly-ingested specs are pinned to the top. - **Compose** — a fast classifier routes the question, then an LLM composes the final answer from the retrieved facts and attaches its citations. Repeated and near-duplicate questions reuse a cached answer; any knowledge change clears the cache, so a re-ask after something lands reflects the new state. ## Staying current The Brain is built to not go stale: - **Incremental indexing** — new PRs, docs, and session outcomes are distilled as they arrive. - **A versioned store** — the database schema is versioned and migrates itself forward, so the Brain survives upgrades with no work from you. - **Confidence decay** — facts fade over time unless reinforced (an Ebbinghaus-style curve), so old knowledge doesn't masquerade as current. - **Memory Health** — a **Stale Queue** surfaces fading facts to reinforce or retire, and a **Conflicts Queue** surfaces contradictory facts so you can pick the winner. The Brain tells you when it's contradicting itself. > The compounding part: every session builds on every previous one. Every day you run o8, the memory gets deeper — and that's the part a competitor can't copy by shipping a feature.