Save a knowledge item to your LOCAL scope: a fact, design note, gotcha, or troubleshooting step worth remembering. This is the manual capture path; distill() is the automatic one.

type : memory | need | skill kind : freeform subtype (note, decision, constraint, runbook, ...) why : the rationale — makes the item far more useful at recall time tags : comma/space-separated keywords (boost recall matching) valid_while : optional premise this knowledge depends on, e.g. "while we're on NetSuite" — surfaced later so a dead assumption is spottable

Record a NEED — something missing, wanted, or blocking (a first-class citizen alongside memories: 'we need staging seeds', 'docs for X are missing'). Needs surface in recall like any knowledge and can be promoted so the team/org sees recurring wants.

Automatically turn work that already happened into knowledge. Reads two substrates natively — no export step, no copy-paste:

1. agentsync: every DONE claim on the coordination branch (task + partner note + changed files) becomes an 'outcome' memory. The note your partner left for reconciliation is exactly the knowledge worth keeping.

2. context-keeper: every active decision and constraint in .context/ becomes a memory with its rationale, preserving the dec-NNN/con-NNN provenance.

Idempotent — each source record imports at most once; re-run freely (e.g. from a session-end or post-commit hook for passive capture).

Release-time capture (opt-in, CAMBIUM_RELEASE_CAPTURE=1): agentsync erases a claim from live state the moment it is released or re-claimed, so a claim that completes and churns before the next full distill is lost. With the flag on, distill also remembers the last-seen claim per agent and captures any that has churned away since the previous run — from that snapshot, via the same watermark, so nothing double-imports. Wire distill to fire on completion events and captured-once-at-completion is the result. The residual gap: a done state that lives and dies entirely between two runs is never observed (only the agentsync git log holds it).

Ingest an external memory export into cambium as LOCAL-scope, provenance- tagged knowledge items — a source adapter alongside distill's substrate readers. Import/ingest only: it reads the source READ-ONLY and never writes back to it.

source : adapter name. 'json' = a generic JSON/JSONL export — a list of records (or an object wrapping one under memories/items/records), each with a text body (content/text/body/memory/note) plus optional title, why, kind, tags, id, timestamp. It's the extension point: new formats are new adapters, no core changes. path : local file path to read (no network, no external auth).

Every item is stamped with provenance (source.imported=True, the origin system, original id + timestamp) so imports never masquerade as native capture. Idempotent — re-importing the same records adds nothing (dedupe by source id, or content hash when no id). Imported items are NOT auto-promoted; they earn team/org the normal way, through recall usage and endorsement.

Returns a summary: imported / skipped / duplicates.

Search knowledge across scopes and return the best matches. THE read endpoint for every agent type — a coding agent, a Slack KB bot, an SRE bot — they all ask here, so knowledge captured once serves them all.

scope : auto (local+team+org, the default) | local | team | org limit : max results

Every returned item's recall counter is incremented (local directly, team best-effort via the shared branch) — usage is the trust signal promotion feeds on. If nothing clears the relevance floor the response says no_confident_match: true — don't present weak matches as established fact.

Vouch for an item — the strong trust signal. One endorsement fast-tracks local->team promotion and is REQUIRED for team->org (usage alone never reaches org; someone has to deliberately say 'this is right').

Confirm a knowledge entry still holds — stamp its last_verified to now. This is the event that keeps promoted knowledge honest: promotion's trust gate defends what comes IN, verification keeps an entry from silently going stale after. An optional note records what was confirmed. Absent/old last_verified is a signal (see stale_report), never an automatic downgrade. Works on local and team entries; find stale ones with stale_report().

Graduate knowledge up a scope as it earns trust — the compound-growth step. With no arguments, scans your local items and promotes every one that qualifies to team. With an item_id, promotes that item one level (local->team, or team->org with to_scope="org").

Thresholds: local->team needs recalls >= CAMBIUM_PROMOTE_RECALLS or one endorsement; team->org always needs an endorsement (force=True overrides, use deliberately). Org promotion lands as a direct push, or as a pull request when CAMBIUM_ORG_PR=1 — the PR review is the org trust gate.

org_content : the cross-project restatement of a body that is specific to one repo. Promotion to org changes the readership to everyone, so a project-local runbook ("append to dashboard.py REGIMES") must become the general rule ("annotate a regime boundary when a metric's computation changes"). If the body reads project-specific and no org_content is given, promotion is refused (with the tells and a suggested draft) unless force=True. When supplied, org_content becomes the org body and the original is preserved as example.

Restate an ALREADY-PROMOTED item's body as the cross-project rule, in place, keeping the concrete version as example. The remediation counterpart of the org generalization gate: items that reached org (or team) before the gate — or were forced past it — are listed by review_promotions() under org_needs_generalization; this rewrites one to its general form.

org_content : the cross-project rule to become the body. If omitted, the item's latest endorsement note is used (that is where the generalization was usually already written). note : optional note recorded as a verification stamp.

Writes through the org store's CAS path (direct push, or the shared cambium/generalize PR branch when CAMBIUM_ORG_PR=1 — repeated calls batch into one reviewable PR), re-rendering KNOWLEDGE.md alongside. Team-scope items are edited via the team CAS path.

What's ready to move up? Lists local items eligible for team, team items eligible for org (endorsed), and org PRs already opened. The human-readable checkpoint before running promote().

Which promoted knowledge might be going stale? Lists team + org entries (the ones that cleared the trust gate) sorted OLDEST-VERIFIED-FIRST, with never-reverified entries flagged at the top and each entry's valid_while premise surfaced so a reader can spot dead assumptions ("while we're on NetSuite" long after the NetSuite migration).

project : limit to one project's entries (default: all) older_than_days : only entries last verified more than N days ago (plus every never-verified one); 0 = no age filter.

Event-driven, not clock-driven: this reports absent/old verification events, it does NOT compute a decaying confidence score. Re-confirm with verify_entry(); promotion also counts as a verification.

Render knowledge to a human-readable KNOWLEDGE.md — grouped by scope then project, each item showing summary, kind, provenance (dec-NNN / claim origin), recall count and promoted date. cp1252 mojibake (em dashes, curly quotes) is normalized so the text is clean.

scope='org' (default): re-render the org knowledge repo's KNOWLEDGE.md from its knowledge.json and commit + push it beside the JSON, so the org repo's docs are always current. (This also runs automatically after any org promotion — direct-push commits both files together; PR mode puts both on the same PR branch.)

scope='local'|'team'|'all': render those scope(s) and RETURN the markdown without publishing — there is no repo to publish local/team docs to.

First thing to call — especially when cambium looks broken. Returns structured config state: what's set, what's missing, what each gap costs in plain terms, and the exact setup() call that fixes it. NEVER raises on missing config. When fully configured it also reports item counts per scope/type, distill watermarks, and which substrates are actually wired.

Finish cambium's setup in one call — the tool status() and every unconfigured error point you to. Validates paths, scaffolds .cambium/ (and gitignores it), and writes a local fallback config the server reads when env vars are absent (env still wins when set, and it takes effect immediately — no restart).

project_repo : absolute path to your project's git clone (required) agent_id : your unique agent id (required) org_repo : optional — a local clone path, OR a GitHub 'owner/name'. If a name isn'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. org_pr : optional — org promotion opens a pull request instead of a direct push. team_branch : optional — override the team-scope branch (default 'cambium').

No secrets are written anywhere; the config file holds only paths, ids, and flags, and lives outside any repo.