# Code Project Brain (CPB)

> A project-level second brain that grows in sync with a code repository.
> A **Knowledge State** (SQLite, the truth) sits over **CodeGraph** (facts) and a
> **Development Guide** (context), with a **Wiki** regenerated as a rebuildable
> projection — compiled into task-specific context for Claude Code, with a
> governed **Change → Delta** loop and a **Continuous Evolution** reality loop
> that keeps knowledge correct without ever letting an AI silently rewrite it.

CPB is at **v12.0.0 / protocol 12**. Implementation record:
[`docs/update8.0.md`](docs/update8.0.md) (阶段 0-9) + [`docs/update10.0.md`](docs/update10.0.md)
(知识质量阶段 P0/P1) + [`docs/update11.0.md`](docs/update11.0.md) (双层 API + Knowledge Transaction + 分层知识模型)
+ [`docs/update12.0.md`](docs/update12.0.md) (架构收敛:工具可见性 profile + 三层对象边界 + 软知识过期 + 任务路由 + Benchmark 骨架).
Design references:
[`docs/CPB Knowledge State Design.md`](docs/CPB%20Knowledge%20State%20Design.md),
[`docs/CPB Continuous Evolution Design.md`](docs/CPB%20Continuous%20Evolution%20Design.md),
[`docs/CPB Project Bootstrap Design.md`](docs/CPB%20Project%20Bootstrap%20Design.md).

```
                     ┌──────────────┐
                     │ Claude Code  │  (any MCP client)
                     └──────┬───────┘
                            │ MCP (72 namespaced tools / 10 namespaces)
                            ▼
   ┌─────────────────────────────────────────────────────┐
   │              CPB MCP Adapter (双层 API)              │
   │  cpb.* intent layer (8): search/context/inspect/     │
   │    impact/propose/record/conflicts/history           │
   │  atomic layer (63, preserved): code/docs/kb/wiki/    │
   │    guide/concept/knowledge/project/evolution         │
   └──────────────────────┬──────────────────────────────┘
                          ▼
   ┌─────────────────────────────────────────────────────┐
   │                    CPB Engine                        │
   │  Knowledge State (ks_* tables) ── THE TRUTH          │
   │   concepts(+aliases) · entities(+scope) · claims     │
   │   · evidence · relations · deltas · intake_events    │
   │     ▲ mutation via Delta (§45.2 soft gate) /         │
   │       Knowledge Transaction (D2 dryRun/commit)       │
   │     │                                                │
   │  Concept Resolution (D1: Hybrid 5-arm fusion) +      │
   │  Retrieval (FTS+Graph+Vector → RRF) · Governance    │
   │  CodeGraph (facts)  ·  Development Guide (context)   │
   │  Wiki = rebuildable projection of KS (D1b)           │
   │  Context Compiler · Impact · Continuous Evolution    │
   └─────────────────────────────────────────────────────┘
                            ▼
   SQLite (KS + CodeGraph + indexes)  →  .project-brain/
```

## What changed in v8.0 (vs the old v5-v7 "Markdown IS the knowledge state")

v8.0 **reversed** v7.0/v7.1: the SQLite **Knowledge State** (`ks_*` tables) is
again the source of truth; the wiki is demoted to a **rebuildable projection**
that is regenerated from the KS (never authored directly — `wiki.write`/
`wiki.create` are gone). Five locked decisions govern this:

1. **Wiki projection defaults OFF** — old wiki files are preserved read-only
   until a project opts in via `wiki.generate`/`wiki regenerate`.
2. **Seed inputs = CodeGraph + Guide + repo docs, never wiki** — prevents the
   seed↔wiki drift loop (bootstrap design §18).
3. **No `wiki.write`** — wiki updates are regeneration (overwrite, not patch),
   so the file can never disagree with the KS.
4. **Engine is zero-LLM (§29)** — all semantic work (claim extraction, concept
   discovery) is Claude's, done through MCP; the engine only persists + state.
5. **Outputs live in `.project-brain/`** (no new `.cpb/` directory).

阶段 9 adds the **Continuous Evolution** reality loop: external reality (a user
statement / document / test result) enters as a typed intake event, is linked to
the Knowledge Delta that reconciles it, and derived views (wiki/guide) are
invalidated. See [`docs/update8.0.md`](docs/update8.0.md) 阶段 9.

## What changed in v10.0 (Knowledge Quality)

v10.0 shifts the focus from feature completion to **knowledge quality /
evolution optimization** — does CPB's knowledge actually get better the longer a
project runs? (See [`docs/update10.0.md`](docs/update10.0.md).) Two landed tracks:

- **P0 — Knowledge Quality Benchmark** (§3): a deterministic, zero-LLM harness
  (`project.benchmark` / `cpb benchmark`) that compiles context for a task and
  compares it against human-authored expected ground truth across 7 metrics
  (precision / recall / completeness / redundancy / tokenCost /
  conflictCoverage / impactAccuracy). A regression net for the recall engine.
- **P1 — Consolidation / Pattern + Knowledge Scoring** (§5-§8): the engine
  deterministically clusters recurring evidence (frequency ≥ 3) into candidate
  **Patterns** (`evolution.patterns` / `evolution.promote_pattern`) — the middle
  state of the learning loop (Event → Evidence → **Pattern** → Claim → Rule).
  Per the §29 boundary contract the engine only *detects* candidates; Claude
  *promotes* a Pattern to a Rule/Decision via a Knowledge Delta. Knowledge
  scoring splits semantic **importance** (Claude-set) from **activity**
  (`usage_count` / `last_accessed_at`, bumped on context compilation) and
  combines them into a weighted score + HOT/WARM/COLD tier (scoring only this
  version; physical tiering deferred).

## What changed in v11.0 (Double-Layer API + Knowledge Transaction + Layered Knowledge Model)

v11.0 lands all three decisions from [`update11.0.md`](docs/update11.0.md) §21 in one
iteration. The overarching theme (update11.0 §2): **a vector store is a recall arm,
not a knowledge system** — the correct architecture is
`Query → Concept Resolution + Retrieval (FTS+Graph+Vector) → Fusion → Ranking → Context Compiler`.

- **D1 — Alias/Vocabulary layer + Hybrid Concept Resolution (§2).** Concepts gain
  aliases (`ks_concept_aliases`, migration v20, case-insensitive + source provenance).
  `resolveConcepts` fuses **five arms** — exact (1.0) / alias (0.8) / fts (0.5) /
  graph (0.5) / vector (0.3) — by Σ weight, dedup + sort. The Context Compiler's
  concept classifier now augments exact/symbol matches with hybrid resolution.
  Without a vector provider it degrades to four arms — zero breakage. Tools
  `concept.resolve` / `concept.alias`; CLI `cpb resolve`.
- **D2 — Intent-level `cpb.*` MCP + Knowledge Transaction API (§7-§11).** The MCP
  surface gains **8 high-level `cpb.*` tools** (search/context/inspect_concept/
  impact/propose/record/conflicts/history) **on top of the 63 preserved atomic
  tools** — an MCP tool is an *Agent interface*, not an internal API interface.
  `cpb.propose` runs a two-phase **Knowledge Transaction**: `dryRun` previews the
  predicted validation tier + gate + affected concepts + known conflicts without
  writing; `commit` records a delta and applies it (auto tier) or holds it for
  approval (review/manual). Claude expresses *what should change*
  (`ChangeIntent[]`); CPB runs the deterministic governance
  (resolve → impact → conflict → validation → delta). New `create_claim`
  DeltaOpType. This addresses weak-model tool-calling instability: the LLM only
  expresses intent, CPB runs governance.
- **D3 — Layered Knowledge Model (§14-§18).** **Structured Core**
  (requirement/design/decision/rule/... — manual/review governance) +
  **Soft Knowledge** (preference/heuristic/practice/observation — auto tier, scoped,
  flows lighter) + **Open Vocabulary** + **Closed Governance**. "The vocabulary may
  open; the governance stays controlled." `ks_entities` gains a `scope` column
  (migration v21). `classifyValidationTier` now applies a governance tier floor: a
  Structured Core type never classifies below its floor; a soft type's semantic-shift
  op (modified/weakened/contradicted) skips the review escalation (the D3 relaxation);
  lifecycle ops (supersede/deprecate/dispute) still bind all types. Tool
  `knowledge.types`.

**§16 respected**: core Event/Delta/Schema/Ontology/Version contracts unchanged; the
63 atomic tools are all preserved; additions are incremental non-breaking. **§29
respected**: aliases are Claude-declared, governance rules are deterministic, the
engine calls no LLM/embedding. schema_version 19→21; tools 61→72 / 10 namespaces;
eg-test 410→447 + mcp-test 43→55.

P5 (external embedding models, ANN index, fusion into Context Compiler, plus
cpb.* further consolidation) remains deferred — see [`docs/TODO.md`](docs/TODO.md).

## What changed in v12.0 (Architecture Convergence)

v12.0 turns from "feature-complete" to "complexity-to-value". The engine does not
gain features; it converges so the complexity already there pays for itself, and
starts to *prove* it does. Design source: [`docs/update12.0.md`](docs/update12.0.md).

- **A1 Tool Visibility Profiles** — the 72 atomic tools (§16, all preserved) are
  filtered by *profile* at MCP registration. `default` exposes the 8 intent-layer
  `cpb.*` + a 6-tool read face (14 total); `advanced` exposes all 72. "Retaining 63
  tools is not the problem; letting the Agent see 63 tools is." Set via `CPB_TOOLS`
  env or `config.yaml` `tools.profile`. The contract is unchanged — only what a
  working session *sees* narrows.
- **A2 Three Object Layers** — KS objects are explicitly Knowledge (durable truth:
  entities/claims/…), Governance (lifecycle mechanisms — evidence/delta/conflict —
  *not* knowledge), and Runtime (incidental: intake events/patterns). Surfaced by
  `knowledge.types` so "everything is a KS first-class citizen" doesn't collapse
  long-term knowledge with the mechanisms that govern it.
- **A3 Soft Knowledge expiry** — soft knowledge (preference/heuristic/practice/
  observation) carries a review horizon (`review_after_days`, default 90; migration
  v22). The Context Compiler downgrades a due entity to `optional` + `[needs review]`
  and ranks KS entities by Knowledge Score. **Soft nudge, not a status flip** (§20
  terminal-state semantics untouched). Structured Core never expires.
- **A4 Task-dependent Context Routing** — `compileContext` classifies the task intent
  (bugfix/exploration/architecture/feature/default, deterministic §29) and the **wiki
  layer is opt-in (default OFF)** — it is a rebuildable projection, not a required
  context layer. Load it only when the task asks for docs/history. Semantic change →
  protocol bump 12.
- **B Agent Benchmark scaffold** — Level 2 (context quality: `missingCritical` /
  `wikiOverlap` / `routingCorrectness`) + Level 3 harness (`AgentTask`/`RunConfig`/
  `RunResult` + `compareRuns`). Level 3 is protocol-only this round (no LLM
  execution); see [`docs/DOGFOOD.md`](docs/DOGFOOD.md) for the live dogfood process.

**§16 respected**: 72 atomic tools retained (visibility only); core contracts
unchanged; additions incremental. **§29 respected**: profiles/freshness/router all
deterministic. schema_version 21→22; tools 72 (unchanged — profile is a visibility
dimension); eg-test 423→462 + mcp-test 47→55.

Frozen (update12.0 §23): Structural Candidate, physical HOT/WARM/COLD, standalone
Vector DB, auto Conversation Classification, auto Rule promotion, Context Cache,
external Embedding (await Benchmark proof). See [`docs/TODO.md`](docs/TODO.md).

## What changed in v10.1 (Retrieval Abstraction)

v10.1 lands **P2** from the update10.0 roadmap (§9/§10/§11): vector/embedding
as an **optional retrieval adapter, OFF by default**. The retrieval pipeline
becomes three arms — **FTS5 + Graph + Vector → RRF fusion → ranking**
(Reciprocal Rank Fusion, k=60; `score = Σ 1/(60+rank)`, dual-arm hits rank
highest; pure arithmetic, no cross-provider score calibration).

- **Pluggable `EmbeddingProvider`** (synchronous — the engine is fully sync):
  the built-in `local-bow` is a deterministic token-bag hash projection (256-dim,
  model-free, no network) that keeps the pipeline testable while preserving the
  **§29 zero-LLM** boundary. Real embedding models inject via `config.yaml`
  (async external providers are deferred to P5, since they'd break the sync
  facade).
- **Semantic objects only**: embeddings cover knowledge entities
  (requirement / design / decision / constraint / rule / observation,
  importance ≠ low); **code symbols stay FTS + Graph** (§11). A `text_hash`
  cache skips unchanged text. With no provider configured, `hybridSearch`
  degrades to pure FTS5 — zero breakage.
- Tools: `knowledge.search` gains a `semantic` flag; new
  `evolution.semantic_search` / `evolution.semantic_reindex`. CLI:
  `cpb ksearch --semantic` / `cpb index-semantic`.

P5 (external network embedding models, ANN index via sqlite-vec, fusion into
Context Compiler, plus Document Diff, Conversation Classification, Context
Cache, physical HOT/WARM/COLD, Structural Candidate) remains deferred — see
[`docs/TODO.md`](docs/TODO.md).

## The core assets

- **Knowledge State** (`ks_*` tables) — *Truth*. Entities (requirements /
  decisions / constraints / …), Claims (S+P+O triples), Evidence
  (supports / verifies / contradicts), Relations (controlled ontology), Deltas
  (the change protocol), intake events (reality loop). Revision-numbered,
  optimistic concurrency.
- **Development Guide** (`guide/`) — *Context*. An Agent Context Map:
  `index.md` is the project map that compiles to `index.compact.md` (L0
  briefing). Code Anchors keep it honest against CodeGraph.
- **CodeGraph** — *Facts*. tree-sitter-parsed symbols + call/reference edges.
  The ground truth that verifies Guide anchors and feeds impact analysis.
- **Wiki** (`.project-brain/wiki/`) — *Projection*. Regenerated from the KS on
  demand; never the truth. Typed pages (requirement / bug / decision / …).

The **Concept hub** (`ks_concepts`, with a `parent_id` hierarchy) is the stable
semantic coordinate that ties entities, code symbols, guide sections and wiki
pages together — so a code change traces `symbol → concept → guide section` and
flags the guide stale.

## The governed loop + continuous evolution

```
Code change → Impact → affected concepts → Knowledge Delta (draft)
            → validate → approve → apply → KS → invalidate wiki/guide
Reality (user/doc/test) → intake event → [Claude drafts] → Delta → apply → completed
```

A code change reaches a concept and creates a **draft delta** with empty
operations; Claude fills the semantic operations (`project.propose_delta`), then
the proposal is validated/approved/applied. Direct KS writes
(`knowledge.create` etc.) are allowed as a low-friction path but each records an
**implicit delta** (auditable) and triggers invalidation (§45.2 soft gate).

## Quick start

```bash
# inside a code repository
cpb init                 # create .project-brain/ + guide skeleton + bootstrap brief
cpb index                # build codegraph + guide + wiki + git indexes
cpb knowledge seed       # seed Knowledge State from guide + codegraph (deterministic)
cpb status               # summary: engine/protocol/guide/stale anchors/KS counts
cpb context CameraDevice # ContextPlan (Guide → KS → wiki → Code)
cpb knowledge concepts   # list registered concepts
cpb wiki generate camera/capture-pipeline   # regenerate a concept's wiki page from KS
cpb impact CameraDevice  # blast radius + affected concepts/guide
cpb sync                 # detect changes → draft proposals (with deltas)
cpb proposals            # list / validate / approve / apply / reject

# Continuous Evolution (阶段 9)
cpb talk "The encoder must never block capture"   # ingest a user statement → event
cpb ingest docs/spec.md                            # ingest a document → doc evidence
cpb events                                         # list intake events (the reality queue)

# Knowledge Quality (v10.0)
cpb consolidate          # scan recurring evidence → candidate Patterns
cpb patterns             # list Patterns (candidate / promoted)
cpb benchmark            # run the quality benchmark (7 metrics regression net)
```

> If `cpb` is not on PATH, use `node dist/bin/cpb.js …` (after `npm run build`)
> or `npx tsx bin/cpb.ts …`.

## MCP (the AI interface) — 72 namespaced tools / 10 namespaces

**Intent layer (v11.0 D2)** — high-level front door over the atomic tools; LLM
expresses intent, CPB runs governance:

- `cpb.*` — search / context / inspect_concept / impact / propose / record / conflicts / history

**Atomic layer (63, all preserved)**:

- `code.*` — search / symbol / callers / callees / dependencies / impact
- `docs.*` — get / search / constraints / validate / apply (wiki knowledge pages)
- `kb.*` — search / requirement / bug / decision (typed wiki records)
- `wiki.*` — read / search / index / related / generate / log / stale
- `guide.*` — index / compact / current / topic / navigation / section / stale / validate
- `concept.*` — register / overview / link / forSymbol / resolve (D1) / alias (D1)
- `knowledge.*` — create / claim / evidence / search / neighbors / relation / delta / history / types (D3)
- `project.*` — context / impact / changes / sync / proposals / propose_delta / status / benchmark
- `evolution.*` — ingest_user / ingest_document / ingest_test / events / event / patterns / promote_pattern / semantic_search / semantic_reindex


Full tool reference: [`docs/USAGE.md`](docs/USAGE.md).
Architecture tour: [`docs/OVERVIEW.md`](docs/OVERVIEW.md).

## As a Claude Code Plugin

CPB ships as a **Claude Code plugin** (`cpb-claude-plugin/`) — the adapter layer
over the Engine. The Engine (`cpb`/`cpb-mcp` CLI) stays a standalone runtime; the
plugin binds via MCP, so the Engine evolves independently. See
[`cpb-claude-plugin/README.md`](cpb-claude-plugin/README.md) for install steps.

```bash
# 1. Engine on PATH (once)
npm install -g @cpb/engine        # or: npm link  (from this repo)

# 2. In Claude Code
/plugin marketplace add /path/to/CPB
/plugin install cpb@cpb
```

Then `/cpb:status`, `/cpb:context`, `/cpb:sync`, … — or describe the task and
the skills auto-activate.

## The demo project

`demo-src/camera/` is a small C++ camera pipeline (`CameraDevice →
FrameQueue → VideoEncoder`) with a full Guide (`guide/`: overview + architecture
+ a constraint + an ADR). It is dogfood: CPB indexes, seeds the Knowledge State,
generates wiki, drift-checks, and runs the change→delta loop on it.

## Layout

```
src/
  core/        types + version (12.0.0 / protocol 12)
  db/          sqlite adapter + schema.sql + migrate.ts (v22 latest)
  engine/
    knowledge-state/  KS core: store/concept/query/delta/seed/ontology/internal/version
                      + alias (D1) / resolve (D1 Hybrid Concept Resolution) / freshness (A3 review-due) (truth, ks_* tables)
    evolution/        Continuous Evolution: event/intake/invalidation/conflict/health/consolidation (reality loop + conflict + health + Pattern learning)
    codegraph/        tree-sitter extractor, grammars, parser, orchestrator, queries, watcher
    guide/            Development Guide: indexer/anchor/query/validator/parser/compact
    wiki/             wiki projection (regenerate from KS) + indexer/query/store/log/freshness/model
    knowledge/        frontmatter / freshness (drift) / recall (doc search) / docupdate
    docs/             structured reads: constraints/decisions/requirements (read guide+wiki)
    context/          Context Compiler + explain + explore-view + router (A4 task intent routing)
    impact/           blast radius + affected concepts/guide (→ deltas) + scoring (knowledge quality score/HOT-WARM-COLD)
    quality/          knowledge quality benchmark (compileContext vs expected → 7 metrics, zero-LLM) + context-benchmark (A2/B Level 2) + agent-harness (B Level 3 scaffold)
    sync/             semantic-diff / changeset / proposal / pipeline (change→delta loop)
    retrieval/        v10.1 P2: embedding (Provider abstraction + local-bow) / index (semantic index) / fusion (RRF hybrid)
    bootstrap/        probe.ts (deterministic bootstrap brief, §29 zero-LLM)
    git/              commit index + ADR mining
    transaction.ts    v11.0 D2: Knowledge Transaction (dryRun/commit facade over applyDelta)
    api.ts            unified facade (CLI + MCP share this)
    staleness.ts      self-heal (ensureFresh) before queries
    app.ts / config.ts  openBrain / paths / findProjectRoot
  mcp/         72 tools / 10 namespaces (8 cpb.* intent + 64 atomic) + stdio server (profile-filtered since v12) + profiles.ts (A1 visibility)
bin/cpb.ts      CLI  ·  bin/cpb-mcp.ts  MCP server
cpb-claude-plugin/  the Claude Code adapter (skills + commands + MCP declaration)
demo-src/camera/    the dogfood demo (C++ pipeline + guide)
docs/               design docs + update8.0.md + update10.0.md (impl record) + OVERVIEW/USAGE + old/ (pre-8.0 history)
```

## Design boundaries (§19/§23/§25/§29)

Not built: auto-rewriting all docs, auto-generating all knowledge, a full IDE,
or an enterprise knowledge graph. Semantic/vector retrieval exists as an
**optional adapter, OFF by default** (v10.1 P2) — local-first SQLite+FTS5 is the
default, and the built-in `local-bow` provider is deterministic and model-free.
The engine never calls an LLM/embedding model (§29) — Claude thinks via MCP; the
engine holds facts and the state machine. Knowledge stays human-controlled; the
Guide is a governed asset — every edit goes through a Proposal/Delta. Code is the
highest source of truth (§9). Wiki is a disposable projection (§45.6).

## License

MIT.