Bob's Big Brain Registrar

Formerly qmd-team-intent-kb — the @qmd-team-intent-kb/* npm scope and the GHCR image name keep that name.

Bob's Big Brain Registrar is the memory keeper: it decides what's worth keeping — by deterministic rules you can read, not an AI's judgment call — stores it, retires what goes stale, and writes a tamper-evident receipt for what it admits.

Turn ephemeral Claude Code session insights into persistent, governed, team-wide memory. The Registrar captures institutional knowledge generated during AI-assisted development, applies deterministic governance policies, and makes curated knowledge searchable through qmd's local full-text indexing.

Part of the Bob's Big Brain stack — the Registrar is the govern layer. Upstream, Bob's Big Brain Compiler (compile) emits the spool it consumes; downstream, qmd (retrieve) serves the curated result with qmd:// citations. → Ecosystem overview

Positioning

This project has a clear separation of responsibilities:

• qmd is one of two local retrieval backends. It does one thing well: fast, offline full-text search.
• Bob's Big Brain Registrar provides everything around it: orchestration, governance, lifecycle management, deduplication, analytics, the team-shared memory model, and hybrid retrieval — the qmd binary fused with a native in-process FTS5 (BM25) backend via deterministic reciprocal-rank fusion, then reranked by freshness and category. Serving stays model-free and deterministic; a semantic (sqlite-vec) backend is deferred behind the retrieval eval gate.
• Enterprise-capable from day one. Tenant isolation, audit trails, and governance policies are architectural requirements, not afterthoughts.

Architecture Thesis

The system is built on a strict information flow with deliberate trust boundaries:

1. Claude Code proposes memory. During sessions, Claude Code generates memory candidates — insights, patterns, decisions, and lessons. These are proposals, not facts.

2. Deterministic code decides what becomes durable team memory. A policy engine evaluates every candidate against configurable governance rules. Secret filtering, deduplication scoring, relevance evaluation, and tenant isolation are all enforced programmatically. No LLM judgment is involved in promotion decisions.

3. qmd serves as the local retrieval and index edge engine. Curated, approved memories are synced to local qmd indexes for fast, offline search. The edge daemon handles replication and conflict resolution.

4. A canonical memory control plane owns truth, lifecycle, governance, deduplication, and analytics. The control plane API is the single source of truth for memory state. It manages the full lifecycle: inbox, review, promotion, archival, and supersession.

5. Git is a mirror, export, and distribution layer — not the canonical database. The git exporter publishes curated knowledge to git repositories in structured Markdown + frontmatter format. Git enables distribution and versioning, but it is downstream of the control plane.

6. Default search targets curated knowledge only. When a developer or Claude Code session queries memory, the default search scope is curated, policy-approved knowledge. This is a deliberate design constraint.

7. Inbox and archive content must not pollute default search. Raw candidates in the inbox and retired memories in the archive are excluded from default retrieval. Accessing them requires explicit, intentional queries. This prevents unvetted or stale content from contaminating team knowledge.

Monorepo Structure

bobs-big-brain-registrar/
├── apps/                    # Deployable applications
│   ├── api/                 # Control plane REST API (Fastify)
│   ├── curator/             # Memory promotion, dedupe, supersession
│   ├── edge-daemon/         # Local qmd sync daemon
│   ├── git-exporter/        # Git mirror/export
│   ├── mcp-server/          # MCP server — local + team brain tools
│   └── reporting/           # Analytics and lifecycle dashboards
├── packages/                # Shared libraries
│   ├── schema/              # Shared Zod schemas and domain types
│   ├── qmd-adapter/         # Fused qmd + native FTS5 retrieval, eval harness
│   ├── claude-runtime/      # Claude Code session capture
│   ├── policy-engine/       # Memory governance policy evaluation
│   ├── eval-surface/        # Govern-decision + provenance CI evals
│   ├── repo-resolver/       # Multi-repo context resolution
│   └── common/              # Shared utilities
├── kb-export/               # Git-exported curated knowledge output
├── 000-docs/                # Project documentation and RFCs
├── examples/                # Usage examples and templates
├── scripts/                 # Build and maintenance scripts
├── tests/                   # Integration tests (repo root)
└── .github/                 # CI/CD workflows and templates

Applications

Libraries

Status

v0.7.0 — Production-ready platform with full Intent Solutions Testing SOP enforced in CI.

v0.7.0 marquee: hybrid retrieval — the qmd binary fused with a native in-process FTS5 (BM25) backend via reciprocal-rank fusion (RRF, k=60), reranked by freshness + category, model-free · a stratified Recall@10/nDCG@10 eval harness that gates ranking changes in CI · MCP tool surface (teamkb_search / teamkb_status / teamkb_neighbors read; teamkb_propose / teamkb_transition write, admin-gated) with local and team-brain modes · hash-chained tamper-evident audit receipts with an external chain-head anchor.

All core subsystems functional. 1,900+ unit tests + a testcontainers-based L4 integration suite (postgres forward-compat) passing. The per-PR CI (ci.yml) enforces: format → lint → typecheck → architecture (dependency-cruiser) → complexity (CRAP) → policy-artifact hash pin (harness-pin --verify) → unit tests + coverage (80% line / 70% branch) → govern-decision & provenance-integrity evals → retrieval ratchet (stratified Recall@10) → L4 integration (testcontainers). Weekly/nightly workflows (security.yml, nightly.yml) add gitleaks, Semgrep, and npm audit. Policy artifacts are hash-pinned via scripts/harness-pin.sh so the testing SOP is self-defending against silent AI policy edits.

Highlights:

• Schema & Domain Model — Zod schemas, lifecycle state machine, 12 enum types (Phase 1)
• Claude Runtime Capture — Session capture, local JSONL spool, 11-pattern secret detection (Phase 2)
• qmd Adapter — CLI wrapper, curated-only default search, tenant-isolated indexes (Phase 3)
• Policy Engine — 8 deterministic rule evaluators with short-circuit pipeline (Phase 4A)
• SQLite Store — 5 repositories, WAL mode, in-memory test support (Phase 4B)
• Control Plane API — Fastify 5, candidate intake, memory lifecycle, policy CRUD, audit trail (Phase 4C)
• Curator Engine — Spool intake, dedup, Jaccard supersession detection, dry-run mode (Phase 5)
• Git Exporter — Incremental Markdown export, YAML frontmatter, category routing (Phase 6)
• Reporting — Lifecycle analytics, aggregators, formatters (Phase 7)
• Security Hardening — API middleware (rate-limiter, auth, input sanitizer), content classifier, export gating, path-safety (Phase 8)
• Repo Resolver — Multi-repo context resolution with monorepo detection, tenant derivation, and caching (Phase 9)
• OpenAPI Documentation — Generated OpenAPI 3.1 spec at /openapi.json and Swagger UI at /docs (Phase 10)
• Supply-Chain Security — Cosign keyless signing + SLSA Level 3 provenance for container images (Phase 10)
• Hybrid Retrieval — qmd binary fused with a native FTS5 (BM25) backend via reciprocal-rank fusion (RRF, k=60), freshness + category rerank, and a stratified Recall@10/nDCG@10 eval ratchet gating ranking changes in CI (semantic sqlite-vec path deferred behind the eval gate)
• MCP Server — local + team-brain tool surface for Claude Code; read tools always register, write tools are admin-gated, team mode proxies the remote brain over the tailnet
• Govern Hardening — write-time enum-membership backstop + CHECK constraints on curated memories, lifecycle state-graph enforcement, sensitivity persisted at promotion and enforced at read time (curated search never returns confidential/restricted memories), fail-closed export category mapping, spool schemaVersion validation, and an anti-dormancy policy-coverage gate

Getting Started

Prerequisites

• Node.js 20+
• pnpm 9.15+

Setup

# Clone the repository
git clone https://github.com/jeremylongshore/bobs-big-brain-registrar.git
cd bobs-big-brain-registrar

# Install dependencies
pnpm install

# Run the full validation suite (format, lint, typecheck, test)
pnpm validate

Available Scripts

Contributing

See CONTRIBUTING.md for branching model, commit conventions, PR expectations, and development workflow.

Security

See SECURITY.md for vulnerability reporting, threat model, and security practices.

License

Apache License 2.0 -- Copyright 2026 Jeremy Longshore