brain-save

Brain Save — write one local Registrar memory proposal

Propose one fact to the local Registrar spool or apply one supported lifecycle transition. Never claim that a queued proposal is already governed or searchable.

Overview

This is the full Registrar operator surface, not the read-only intent-brain marketplace runtime and not the unified governed-second-brain plugin. teamkb_propose, teamkb_transition, and teamkb_status operate on the local paths configured for apps/mcp-server, even when remote search is configured. Keep TEAMKB_API_URL unset when the search and write sides must address the same brain.

Prerequisites

• Build and configure apps/mcp-server from this repository.
• Set TEAMKB_TENANT_ID, TEAMKB_BASE_PATH, and TEAMKB_ROLE=admin.
• Protect the local base path with operating-system permissions; TEAMKB_ROLE=admin is a tool registration gate, not remote authentication.
• Read the runtime contract before operating mixed local/remote mode.

Instructions

Save a new fact

1. Search first with teamkb_search({ query: "KEY_TERMS", scope: "all" }). If existing governed content already covers the fact, stop instead of duplicating it.
2. Exclude ephemeral debugging, personal preferences, secrets, credentials, and facts already maintained in authoritative project documentation.
3. Choose decision, pattern, convention, architecture, troubleshooting, onboarding, or reference.
4. Call teamkb_propose with { title, content, category, filePaths? }.
5. Report the returned candidateId as queued to the local spool. Promotion happens only when the separate curator processes it; this skill does not run or prove that step.

Retire or restore a memory

1. Search for the memory and extract its UUID from a UUID-shaped citation filename such as qmd://kb-curated/9c2e42f1-7b60-4ed2-a9dd-648d6c786d43.md.
2. Call teamkb_transition with { memoryId, to, reason, actor }.
3. Use only transitions the current tool can complete safely: active to deprecated or archived, deprecated to active or archived, and superseded to archived.
4. Do not request active to superseded through this version of the MCP tool; its input surface cannot supply the required replacement-memory link.

Check local status

Call teamkb_status for local database counts and recent governance feedback. Status does not list spool proposals and cannot confirm that a newly queued candidate has been promoted.

Output

• Save: candidate UUID, local-spool disposition, and an explicit “not yet promoted” statement.
• Transition: memory UUID, old and new lifecycle states, and audit-event UUID.
• Status: counts by lifecycle/category/tenant and recent feedback, without printing dbPath unless the operator explicitly requests it.

Examples

teamkb_search({ query: "Apache license", scope: "all" })
teamkb_propose({
  title: "License: Apache-2.0 across public engines",
  content: "The public engines use Apache-2.0.",
  category: "decision"
})

Candidate 4f3a2e0e-0ee4-4f63-b63e-22306c45115a was queued locally. It is not governed memory until the
curator processes it.

teamkb_transition({
  memoryId: "9c2e42f1-7b60-4ed2-a9dd-648d6c786d43",
  to: "deprecated",
  reason: "Replaced by the current deployment runbook",
  actor: "registrar-operator"
})

Memory 9c2e42f1-7b60-4ed2-a9dd-648d6c786d43 moved from active to deprecated; audit event
83e1bc9a-0048-44e7-b70b-52bc7cf6e954 recorded the transition.

Error Handling

Situation	Response
Write tools are absent	The read-only plugin or member role is active; use the built local server with TEAMKB_ROLE=admin.
Spool write fails	Report the error; do not claim the candidate was queued.
Transition ID is not UUID-shaped	Stop and obtain an exact ID from a returned citation.
Transition is rejected	Report the state-machine reason; do not route around it.
Content may contain a secret	Strip it before calling teamkb_propose; policy scanning is not the only control.

Guardrails

• Never persist secrets, tokens, credentials, or private keys.
• Require a human-readable transition reason and a truthful actor identifier.
• Local filesystem access is the security boundary for writes; a bearer token does not authorize this tool path.
• Provenance proves capture origin, not factual truth.

Resources

• Bob's Big Brain Registrar — source, build instructions, and operator documentation.
• apps/mcp-server — the required full operator runtime.
• brain — read counterpart using the Registrar-native teamkb_search tool.