MCP integration

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:

claude mcp add xynthis -- ~/.xynthis/bin/xynthis-mcp

For Cursor, Codex, or any client that reads a JSON config, add the server block:

{
  "mcpServers": {
    "xynthis": {
      "command": "xynthis-mcp",
      "args": []
    }
  }
}

(.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.

Getting started

Core concepts

Guides

On-device model

Reference

MCP integration

Registration

Tools

Memory

Corpus and code

Watchers

Witnessed memory

Introspection and learning

Failure modes

​Registration

​Tools

​Memory

​Corpus and code

​Watchers

​Witnessed memory

​Introspection and learning

​Failure modes

Registration

Tools

Memory

Corpus and code

Watchers

Witnessed memory

Introspection and learning

Failure modes