Brain serves 19 tools over one MCP endpoint. Your agent picks them on its own — this page is for the human who wants to know what it just did, or what it could do. Terse agent-facing wording lives in [/brain.md](/brain.md); the machine-readable definition is [mcp.json](/brain/mcp.json). Endpoint: `https://brain.levirge.com/mcp` · Protocol: MCP over Streamable HTTP · Auth: OAuth on connect, bearer token as fallback. ## The vocabulary first Six words do most of the work. The tools are much easier to read once these are clear. **Vault** — the unit of scoping and access. One per project, product or client. Knowledge, skills, todos and reminders all belong to a Vault, searches are scoped to it, and permission is granted on it. A team shares a Vault; personal Vaults stay private to their owner and fail closed. **Document** — a captured piece of knowledge as it arrived: a note, a decision, an incident write-up, a session learning. Identical content deduplicates, so re-running an ingest is safe. **Atom** — a single extracted statement — a rule, a procedure, a fact — pulled out of documents so it can be retrieved on its own rather than buried in a longer page. **Entity** — a noun the knowledge base tracks: a system, a file, a person, a concept, a subject. Entities are canonical and kebab-case (`levirge-search`), and each carries a consolidated summary distilled from every document that mentions it, with citations back to those sources. Entities are tracked per Vault, so counts and summaries never mix across projects. **Provenance** — where a statement came from and when. Every retrieved item carries its source and timestamps, which is what lets a session judge whether a two-year-old learning still binds. **Skill** — a stored procedure for a recurring task, versioned and served to every connected agent as a tool. Update it once; connected agents pick it up. --- ## Finding things ### `search_knowledge` Semantic search across the corpus, ranked by meaning rather than keywords. Returns evidence with a confidence signal and provenance on every hit. Narrow with `vault`, `entity`, `tag` or `source`; use `kind` to get only rules, procedures or facts. `include_content` and `max_total_chars` control how much text comes back, so a broad question doesn't blow a context budget. Worth knowing: search has no time dimension. For "what changed since", use `list_documents` below. ### `list_documents` Browsing rather than asking — a topic-level view of what a Vault or tag actually holds, and the right tool when a search comes back low-confidence. Supports deterministic time windows: `updated_after`, `updated_before` and `sort=updated_asc`, with `as_of` and `revision` on the response so paging through a window stays stable while the corpus moves underneath. That is what makes "everything that landed this week" a reliable question. ### `get_document` The full text behind a search snippet, by id. Batch up to 20 at once. Pass `lineage: true` to see the fact graph around it — what updates it, what it extends, what was derived from it — which is how you check whether something has since been superseded. ### `get_entity` One entity's consolidated summary, its evidence, and the documents that mention it. The fastest way to answer "what do we know about this system". ### `list_entities` The set of nouns the knowledge base tracks, with mention counts. Filter by `kind` or `min_mentions`. Useful as a map when you don't yet know what to search for. ### `knowledge_graph` A bounded graph around one Vault, entity, document or query — nodes plus typed edges (`contains`, `mentions`, `updates`, `extends`, `derives`, `retrieved`, `source`). Vault roots come pre-clustered into communities. Node caps keep the result small enough to reason about. ### `get_context_pack` One compact bootstrap instead of a dozen exploratory calls: profile, relevant search results, lineage and graph for a Vault, entity, document or query. Returns JSON for machines or Markdown for a handoff. This is the "start warm" call — what an agent reads before it begins work in an area. ### `kb_overview` Corpus inventory: how many documents, which Vaults, which tags and entities exist. Read-only and cheap, which makes it the standard connection check. ### `get_vault_profile` The same idea narrowed to one Vault: document count, top entities, tag distribution. Always fresh, no model call involved. --- ## Adding and correcting ### `add_knowledge` Capture a fact, decision or gotcha as Markdown — one, or up to 50 in a batch. Identical content deduplicates on a content hash, so retries are safe. `checked_against` records what a fact was verified against (`forgejo@12.0.4`), so a later reader can judge whether it has gone stale. ### `mutate_knowledge` Corrections, four kinds. `link` records a typed edge between documents — `updates` supersedes, `extends` adds detail, `derives` records an inference. `reassign_vault` moves a misfiled document. `delete` is a recoverable soft-delete. `demote` halves a document's ranking without hiding it, for the noisy-but-worth-keeping. All queued and idempotent. ### `feedback` Closes the loop on a search. `helpful` gives a bounded ranking lift; `dead_end` down-ranks a plausible-but-wrong hit and feeds gap analysis. This is how the corpus learns what was worth keeping. ### `self_improvement` Memory hygiene. `report` is read-only: stale entity summaries, entities never consolidated, coverage gaps, recommended next actions. `apply` performs a single confidence-gated write from that report, and every attempt is logged. --- ## Working, not just remembering These are the tools that make Brain a work-continuity system rather than a store. They are the reason an agent that starts cold can recover what was happening. ### `work_session` Brackets a piece of work. `start` adopts a role and returns the overview, that role's open handoffs, readable open todos, your personal Vault profile and an optional context pack — the deliberate first call of a session. `finish` captures durable learnings, search feedback and outbound handoffs in one close-out. ### `todo` Vault-scoped "do later" records that surface at session start. Add, list, update, complete, delete, with priority and optional links to related documents. Writes need write access to the record's Vault, and a list never returns a todo from a Vault you cannot read. ### `reminder` A dated fact that stays out of the way until its date arrives — a certificate expiry, a renewal, a decision to revisit, a deliberately deferred cleanup. `due` is required and is canonicalised on the way in; an unparseable date is refused rather than stored, because a reminder that silently never fires is worse than none. `list` returns what is overdue or due now, `within_days=30` looks ahead, and `links` point the reminder at the documents whose claim expires, so what surfaces is the knowledge and not just a nudge. The distinction from `todo` is the point: a todo is work owed *now*; a reminder is owed *later* and is structurally invisible until then — not by a filter someone has to remember, but because the surfaces that list todos cannot return reminders at all. One honest limit: **Brain answers what is due; it does not notify.** Nothing here emails, pushes or wakes anything. A reminder becomes due and waits to be asked about. That is deliberate — the consumer is a scheduled task you define, which queries and then decides what to do, so "tell me what's due this week" and "if the certificate expires within 30 days, open the renewal PR" are the same query with different judgement attached. ### `handoff` Durable agent-to-agent messaging, 30-day retention. `send` and `reply` between role identities (`reviewer@brain`, with an optional `:instance` suffix for parallel copies), `inbox` to check mail, `wait` to long-poll. Handoffs that arrive while a watcher is down are delivered on its next wait, so gaps are safe. ### `skill` `list` to browse stored skills, `get` to load one's full instructions, `read_file` to pull a bundled asset it references. Skills are versioned; the agents connected to your workspace pick up an update without redeploying anything. ### `create_api_token` Mints a bearer token for your user, for processes that reach Brain over HTTP rather than through an MCP session — a CI job, a cron task, a script on another machine. Shown once, unrecoverable; list and revoke them in Settings. Only the hash is stored. --- ## Getting connected Add the endpoint to your client, authenticate with OAuth, then call `kb_overview` to confirm the connection — it is read-only and returns your workspace's summary. ```json { "mcpServers": { "brain": { "type": "streamable-http", "url": "https://brain.levirge.com/mcp" } } } ``` Per-client instructions, including Claude Code, Claude Desktop, Codex and Obsidian, are on the [Brain page](/brain#install). Access is granted per workspace — [request access](/contact). One caveat worth knowing when a tool looks like it is missing an option: **MCP clients cache the tool list from connection setup.** If Brain ships a new parameter while your session is open, your client will keep showing the old schema until it reconnects. Restart the connection before concluding a capability isn't there.