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 (阶段 0-9) + docs/update10.0.md (知识质量阶段 P0/P1) + docs/update11.0.md (双层 API + Knowledge Transaction + 分层知识模型)

• docs/update12.0.md (架构收敛:工具可见性 profile + 三层对象边界 + 软知识过期 + 任务路由 + Benchmark 骨架). Design references: docs/CPB Knowledge State Design.md, docs/CPB Continuous Evolution Design.md, docs/CPB Project Bootstrap Design.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 阶段 9.

Related MCP server: project-context-map-mcp

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.) 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 §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.

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.

• 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 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.

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.

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

# 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. Architecture tour: 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 for install steps.

# 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.