xynthis-mcp is a stdio MCP server that gives any MCP client (Claude Code, Cursor, Codex) direct access to the brain. The client launches it as a child process; each tool call becomes one request over the brain’s unix socket at ~/.xynthis/brain.sock. No new editor, no separate daemon of its own, but the brain must be running, which the installer sets up at login.
Registration
The binary ships in~/.xynthis/bin/. For Claude Code:
.mcp.json in a project root for Claude Code; ~/.cursor/mcp.json for Cursor.) Use the full path if ~/.xynthis/bin is not on the PATH the client inherits. Tools appear under the mcp__xynthis__ prefix.
Every tool response is capped by a per-tool byte budget (60 KB default) before it reaches the client, so a fat recall can’t blow through the model’s context window. Truncated responses carry a [budget:...] footer.
Tools
Memory
| Tool | What it does |
|---|---|
remember | Store a perception (content, optional kind tag: user_msg, tool_use, file_edit, decision, insight). Consolidated into long-term storage on the next dream cycle |
recall | Layered retrieval: identity, working memory, knowledge graph, then binary rescore. Takes query and optional top_k (default 8 per layer); reports which layers fired |
brief | One-shot session brief: a compact markdown block with the user’s identity, top-ranked stored facts, and brain counters. Takes no arguments; call it first in every session |
kg_add | Add a temporal fact as a (subject, predicate, object) triple with optional valid_from/valid_until bounds and confidence |
kg_query | Query the graph by entity, predicate, and/or as_of_secs; all filters are optional, and entity matches subject or object |
brief is the recommended session opener. It fans out four brain ops concurrently: identity, profile, recall (top_k 40), and status. The facts block comes primarily from the server-side profile op, a grounded projection of remembered facts; recall supplies the recent working-memory ring and fills the facts block only when the profile projection is empty. Confirmed facts render with a signed marker.
Corpus and code
| Tool | What it does |
|---|---|
corpus_add | Index a folder as a named corpus (path, optional name, mask glob, chunk_strategy of auto/regex, watch default true). Returns immediately; indexing runs in the background, so poll corpus_list |
corpus_list | List indexed corpora with size, context, and watch state |
corpus_update | Re-index a collection (BLAKE3 dedup skips unchanged chunks); omit name for all |
corpus_context_set | Attach a description that travels with every recall hit from that collection |
code_scan | Structurally scan a repo (Rust / TypeScript / Python / Go / Swift, tree-sitter, respects .gitignore) into typed code:* triples. Query afterward with kg_query, e.g. kg_query(entity='code:<repo>::src/lib.rs') |
Watchers
| Tool | What it does |
|---|---|
watcher_create | Create a polled event watcher. Providers: files_changed (new/modified files under a root) and command_output (run a read-only command, fire when its stdout hash changes). Minimum interval 15 seconds. Events become watcher_event perceptions that recall surfaces |
watcher_list | List watchers with last-run / last-event timestamps |
watcher_delete | Delete a watcher by id |
Witnessed memory
| Tool | What it does |
|---|---|
confirm | Cryptographically attest a recalled fact is correct: signs it with the local Ed25519 identity and appends to the Merkle log at ~/.xynthis/bmc/witness.log. Takes fact_id from a prior recall hit |
why_witness | Full audit view for a confirmed fact: signed payload, signature, RFC-6962 inclusion proof, offline-verifiable against the public key alone |
Introspection and learning
| Tool | What it does |
|---|---|
identity | Snapshot of mood, interaction count, consolidation score, and the six-axis personality vector |
status | Brain state: uptime, perceptions, last dream, working-memory size, knowledge-graph size |
dream | Force a consolidation cycle now. Use sparingly; the gates fire automatically |
learner_status | The online rerank learner’s training step count, samples seen, last loss, and weights |
train_step | Force one training step on the rerank head. Debugging aid; the learner runs its own background loop |
skill_status | The per-user skill model: checkpoint state, score-call counts, training-row count |
skill_train | Run the skill-model trainer once and return its summary |
llm_status | The on-device model’s training state from ~/.xynthis/llm/state.json: cumulative steps, last loss, latest checkpoint. Reads the file directly, so it works even when the brain is down |
llm_train_set | Control the on-device training loop: enabled on/off, interval_secs (60-86400), force_tick to run one training pass now. Writes ~/.xynthis/llm/train_config.json, which the model server polls every 5 seconds |
Failure modes
If the brain is not running, tool calls fail with a JSON-RPC error (-32000) rather than hanging; there is no retry. xynthis health from a terminal confirms the stack is up. llm_status and llm_train_set are the exceptions: they are file-backed and work without the brain. ~/.xynthis/llm/state.json exists after the first xynthis-llm-serve start: the server writes an initial status snapshot at boot, before any training runs. To enable training, write train_config.json via llm_train_set or the app’s settings.