Expand description
Hand-rolled Model Context Protocol (MCP) stdio server for MNemo.
Exposes a .mnemo file as an MCP server so any MCP-compatible agent
(Claude Desktop, Cursor, mcp-server, custom clients) can drive it as a
tool. Framed as JSON-RPC 2.0 with newline-delimited JSON over
stdin/stdout, per the MCP spec. Stderr is used for human-readable
diagnostics only — never for protocol traffic.
§Why hand-rolled
The official rmcp SDK declares
edition = "2024" on its workspace, which requires Rust 1.85+; our
MSRV is 1.75 and locked (transitive deps pin us). rmcp also brings
in tokio + async, a big architectural shift for a sync-only core.
Hand-rolling stdio JSON-RPC is ~250 LoC and adds zero dependencies
beyond serde_json (already a dep). See CHANGELOG’s Phase 4 entry
for the decision record.
§Protocol version
We advertise MCP protocol 2025-06-18 on initialize. If a client
requests a different version we echo their version back — the standard
compatibility dance. The seven tools we expose are stable across
recent protocol revisions.
§Tools
about— read-only briefing (manifest + onboarding memories)remember— insert a memory (BYO vector; embedder integration deferred to Phase 3)recall— vector recall (BYO query vector)forget— delete by ULIDlist— enumerate live memoriessnapshot_list— enumerate PITR snapshotsstats— database statistics
Every mutation calls Mnemo::flush() before returning success — MCP
clients treat tool calls as atomic and expect on-disk durability.
§Passphrase
Read from the MNEMO_PASSPHRASE environment variable only.
serve_stdio refuses to start without it. There is no CLI-flag
fallback here — that would leave the passphrase in shell history
and process listings.
Functions§
- serve_
stdio - Run the MCP stdio server over the provided
.mnemofile. - serve_
stdio_ with_ embedder - Variant that optionally registers an
crate::EmbedCmdembedder on the handle at server start (Phase 3 PR 10b). The MCPremember,recall,cache_put_semanticandcache_get_semantictools then accept atextparam as an alternative to the explicit vector — the embedder runs once per request against the persistent child process. PassNonefor the pre-Phase-3 vector-only behavior. - serve_
stdio_ with_ options serve_stdio_with_embedder, and withsharedset, in shared mode (12.4,mnemo serve --mcp --shared): the server holds no lock between tool calls, and each call is one read or one write window on the file, so other servers, the CLI and Python can use the brain meanwhile. The options’ deadline is how long one call waits for the lock.- serve_
with_ streams - Run the MCP loop against explicit reader/writer streams. Extracted so
integration tests can pipe scripted input without touching the real
stdin/stdout.
embed_specis as inserve_stdio_with_embedder. - serve_
with_ streams_ opts serve_with_streams, in shared mode whensharedis set (seeserve_stdio_with_options).