Cambium

cambium

_Part of the xylem stack._

The knowledge-lifecycle MCP that turns work your agents already did into compound, org-wide knowledge. cambium bridges two substrates that already exist — agentsync (what happened: claims, finishes, notes, changed files) and context-keeper (why: decisions, constraints) — and adds the three things neither has:

1. `distill()` — turn events into memory *automatically* (passive capture)
2. `recall()` — one federated read endpoint for every agent type (coding agent, Slack KB bot, SRE bot — same store, same call)
3. `promote()` — graduate knowledge local → team → org as it earns trust

Named for the cambium layer of a tree: the thin living tissue where all growth happens.

Why a third MCP (and not a database)

Knowledge layers fail because they're a *side system* nobody calls. cambium's bet: capture and recall must be native tools in the agent's loop, and state must live in the substrate the work already lives in — git — not a separate service. Storage is an implementation detail behind recall():

Team writes use the agentsync pattern: a private worktree under .git/ and git push as compare-and-swap, so concurrent agents never clobber each other.

Install

pip install -r requirements.txt      # just `mcp`

gh (GitHub CLI) is only needed for pull-request-mode org promotion.

Configure

Point an MCP client at the server — no env required to start:

{

"mcpServers": { "cambium": { "command": "python3", "args": ["/abs/path/to/cambium_server.py"] } } }

First contact is helpful, not cold. MCP servers can't start a conversation, so cambium teaches you through its own responses. Call `status()` (or any tool) before it's configured and instead of a bare env error you get structured guidance — what's set, what's missing, what each gap costs in plain terms, and the exact setup() call that fixes it:

{

"configured": false, "gaps": [ {"setting": "CAMBIUM_REPO", "cost": "no project repo → cambium has no substrate; every tool is unavailable", "fix": "setup(project_repo=\"/abs/path/to/your/clone\", agent_id=\"your-id\")"}, {"setting": "CAMBIUM_ORG_REPO", "cost": "org scope off → promotions stop at team; org-wide recall unavailable", "fix": "setup(project_repo=…, agent_id=…, org_repo=\"owner/knowledge or /abs/path/to/clone\")"} ], "next_step": "setup(project_repo=\"/abs/path/to/your/clone\", agent_id=\"your-id\")" }

`setup(project_repo, agent_id, org_repo?, org_pr?, team_branch?)` finishes the job: it validates the paths, scaffolds .cambium/ (and adds it to the repo's .gitignore), and writes a fallback config at ~/.cambium/config.json that the server reads when env vars are absent. It takes effect immediately — no restart. No secrets are written: the file holds only paths, ids, and flags, and lives outside any repo. If org_repo is a GitHub owner/name you haven't cloned locally, setup offers the exact `gh`/`git` commands to stand it up and leaves org scope off — it never creates or pushes a repo for you.

Env still wins. Any of the variables below, set in the MCP client config, overrides the config file per-key — the table is the full reference layer:

Where the agentsync board lives (board addressing)

\* distill() reads finished agentsync claims off a coordination board. That board is a shared, long-lived team artifact — not a property of whichever project this session happens to be in — so cambium resolves its address independently of the session, using exactly the order agentsync itself uses:

1. `AGENTSYNC_BOARD_REPO` — the explicit board address (env, or the same key in ~/.cambium/config.json). One setting configures both servers.
2. `AGENTSYNC_REPO` — agentsync's legacy explicit pin.
3. `CAMBIUM_REPO` — but *only if that repo actually holds the coordination branch* (real ref lookup: local head → remote-tracking ref → ls-remote).
4. Otherwise: no board, reported loudly (next section) — never silently.

Why. Before this, cambium looked for the coordination branch in CAMBIUM_REPO while agentsync (unpinned) followed ~/.xylem/active_project.json. The two could point at different repos, and whenever the current project had never been provisioned neither found anything. distill() reported that as the bland string "no coordination branch found", callers treated it as normal, and the result was that distill imported zero agentsync claims across its entire lifetime — a three-legged design silently running on two legs.

A skipped source does not look like a completed one

distill()'s return now makes a miss impossible to read as a success:

• top-level status becomes "distilled_with_warnings" (not "distilled");
• top-level warnings carries a plain-language line per skipped substrate;
• sources.agentsync is an object — {status, board_repo, board_source, branch, claims_seen, done_claims, imported, reason, fix} — so "there is no board", "the board is here and nobody has finished anything", and "imported 3" are three visibly different results rather than one empty number.

status() reports the same under substrates.agentsync_board.

Org setup: create one (private) repo, e.g. github.com/you/knowledge, with an empty {"items": []} in knowledge.json; everyone who should read org knowledge clones it and points CAMBIUM_ORG_REPO (or setup(org_repo=…)) at their clone. cambium manages that clone (it hard-syncs it) — dedicate it, don't work in it.

Tools

`capture(content, type, kind, why, tags, valid_while)` — save a knowledge item to local scope (types: memory | need | skill). Manual path. valid_while optionally names the premise the item depends on, so a dead assumption is spottable later (see *Machine-maintained documentation entropy*).

`record_need(content, why, tags)` — first-class needs ("we're missing X"), promotable like anything else so recurring wants surface at team/org level.

`distill()` — the automatic path. Reads agentsync's coordination branch (every *currently done* claim: task + note + changed files → an outcome memory) and context-keeper's .context/ (active decisions & constraints, rationale and dec-NNN provenance preserved). Idempotent — wire it to a session-end or post-commit hook and capture becomes passive.

Release-time capture (opt-in, `CAMBIUM_RELEASE_CAPTURE=1`). agentsync keys claims by agent id and deletes a claim from live state the instant it is released or re-claimed — it exposes no hook or event, only the rewritten claims.json on the branch. So a claim that completes and then churns before a full distill runs against it is silently lost. With the flag on, each distill also remembers the last-seen claim per agent and captures any that has *churned away* since the previous run — reconstructing it from that snapshot, through the same dedupe watermark, so a claim captured at release time and again in a later full distill never double-imports. Fire distill() on completion events (a post-commit / session-end hook) and completed work is captured at its transition instead of only when a distill happens to catch it live.

What this is not: it is passive capture *at the moments distill runs*, not exhaustive reconstruction. The guarantee is precise — *if a distill sweep observes a claim while it is done (or carries a note), that knowledge is captured even if the claim later churns.* The residual gap: a done state that is created and churned away entirely between two sweeps (e.g. cambium wasn't running) is never observed, and only agentsync's git log still holds it. Walking that log to reconstruct such claims exhaustively is a possible follow-up (the history survives — agentsync's history() reads it), deliberately left out of this change.

`import_memory(source, path)` — ingest an external memory export into cambium as local-scope, provenance-tagged knowledge items (see Import below). Read-only against the source; imported items are not auto-promoted.

`recall(query, scope, limit)` — federated search across local+team+org. Every hit increments the item's recall counter (the trust signal promotion feeds on) and records cross-project use. Abstains honestly: below the relevance floor it returns no_confident_match: true instead of confident-looking noise. Each result carries endorsed_as — the item's endorsement notes surfaced as first-class context, since for a promoted item that is where its cross-project meaning was written.

`endorse(item_id, note)` — vouch for an item. Fast-tracks local→team; required for team→org.

`promote(item_id, to_scope, force, org_content)` — no args: scan-and-promote all eligible local items to team. With to_scope="org": push to the org repo, or open a PR when CAMBIUM_ORG_PR=1 (the team copy stays, annotated, until the PR merges). Promotion stamps last_verified — promotion *is* a verification. Generalization gate: org scope is read by every project, so a body that reads project-specific (names a file, a test_* id, a dec-/con-NNN ref, or its own origin project) is refused at the org boundary — restate it as the cross-project rule via org_content= (the concrete body is kept as example) or force=True to override. The refusal hands back the endorsement note as a ready draft. Mirrors the endorsement gate; the safe path is the easy path.

`generalize(item_id, org_content, note)` — the remediation counterpart of the gate: restate an already-promoted item's body as the cross-project rule *in place*, keeping the concrete version as example. For items that reached org before the gate (or were forced past it) — the ones review_promotions() lists under org_needs_generalization. Omit org_content to fall back to the item's latest endorsement note. Writes through the org CAS path (direct, or a single shared cambium/generalize PR branch when CAMBIUM_ORG_PR=1, so repeated calls batch into one reviewable PR); idempotent.

`verify_entry(item_id, note)` — confirm an entr