Give your agent a memory over MCP
Until now, using tiramemsu from an agent meant writing code: a Rust program, or a Python or Node.js script, that turns the agent’s intentions into calls. That is fine when you build the agent. It is a lot of work when you just want Claude Code to remember things between sessions.
tiramemsu-mcp closes that gap. It is a small binary that serves one memory file over the Model Context Protocol (MCP). Any MCP client that speaks stdio can use it: Claude Code, Claude Desktop, or your own. The agent sees typed tools such as assert, query and text_search, and the memory keeps all of its rules.
Install
The server is a separate crate, so the database crates carry no protocol code. Install it from crates.io. SQLite is compiled in, and the binary has no other dependencies.
cargo install tiramemsu-mcp
tiramemsu-mcp --help
Register it
Claude Code
# a memory for this project, with text recall
claude mcp add tiramemsu -- tiramemsu-mcp --db ./memory.db --text-index
# the same file, read-only, for an agent that should only look
claude mcp add tiramemsu-ro -- tiramemsu-mcp --db ./memory.db --read-only --text-index
Everything after -- is the command Claude Code starts. The file is created if it does not exist.
Claude Desktop
Add the server to claude_desktop_config.json. Use an absolute path: the working directory of a desktop app is not yours.
{
"mcpServers": {
"tiramemsu": {
"command": "tiramemsu-mcp",
"args": ["--db", "/Users/me/memory.db", "--text-index"]
}
}
}
Options
| Flag | Meaning | Default |
|---|---|---|
--db <path> | The database file. The only file the server opens. | required |
--read-only | Hide and refuse the tools that write | off |
--timeout-ms | Deadline of one tool call | 30 000 |
--reader-timeout-ms | How long to wait for a free read connection | no limit |
--max-rows | Rows one call may decode | 10 000 |
--max-bytes | Bytes one call may produce | 8 MiB |
--text-index | Build the text index at open, for text_search | off |
0 turns a bound off.
The tools
There are fourteen. Arguments use the JSON forms of the bindings: a plain string is a string literal, {"iri": "urn:tiramemsu:v:alice"} is an IRI (which queries write v:alice), and {"stmt": 7} is a statement id. A view is {"kind": "now" | "asOf" | "history", "tx": n, "validAt": time} and defaults to now. Every read echoes the view it used, so the agent always knows when it was looking.
| Tool | What it does |
|---|---|
assert | Add a fact, with optional valid time and graph. Repeating a fact returns the existing id with new: false |
confirm | Record that another source agrees with a fact |
supersede | Correct a fact; its layers move to the new one and the old one stays in history |
import_bundle | Import a fact with its layers from another memory |
query | Run a SPARQL or Cypher read, in any view, with provenance |
text_search | Recall statements by words, with evidence per hit |
conflicts | List disagreeing values with their evidence |
preview_bundle | Dry-run an import and report what it would do |
dependents | What retracting a fact would take with it |
export_bundle | A fact with its layers and evidence, to hand to another memory |
save_answer, saved_answers, check_answers, refresh_answer | Keep answers and learn when they go stale (see Recall, review, recheck) |
There is no retract tool. To change its mind, an agent supersedes a fact with a correction. Forgetting on purpose stays a decision for code you write, not for a tool call.
A sample session
These are real responses from the server (the structuredContent of each tool result), trimmed only where marked. The agent starts with an empty file.
It learns where Alice works, and makes a note:
→ assert {"s": {"iri": "urn:tiramemsu:v:alice"}, "p": {"iri": "urn:tiramemsu:v:worksAt"},
"o": {"iri": "urn:tiramemsu:v:acme"}, "validFrom": "2020-01-01"}
← {"eid": 1, "new": true, "t": 1}
→ assert {"s": {"iri": "urn:tiramemsu:v:alice"}, "p": {"iri": "urn:tiramemsu:v:note"},
"o": "met at the Lisbon offsite"}
← {"eid": 2, "new": true, "t": 2}
Later, it asks, and the answer says which statement backs it:
→ query {"language": "sparql", "text": "SELECT ?o WHERE { v:alice v:worksAt ?o }"}
← {"language": "sparql", "view": {"kind": "now"},
"result": {"kind": "select", "vars": ["o"],
"rows": [{"o": {"iri": "urn:tiramemsu:v:acme"}}],
"provenance": [[{"stmt": 1}]]},
"provenance": {"coverage": "complete", "gaps": []}}
It remembers a word, not a pattern:
→ text_search {"text": "lisbon", "limit": 5}
← {"view": {"kind": "now"},
"hits": [{"eid": 2, "rank": 1, "text": "met at the Lisbon offsite",
"s": {"iri": "urn:tiramemsu:v:alice"}, "p": {"iri": "urn:tiramemsu:v:note"},
"evidence": {"confidence": null, "confirmations": 0, "authors": 0, "tAdd": 2, …}, …}]}
It saves the employer answer, then learns that it was wrong and corrects it:
→ save_answer {"name": "employer", "language": "sparql", "text": "SELECT ?o WHERE { v:alice v:worksAt ?o }"}
← {"answer": {"name": "employer", "status": "fresh", "dependencies": [1], "coverage": ["mutableView"], …}}
→ supersede {"eid": 1, "patch": {"o": {"iri": "urn:tiramemsu:v:globex"}}}
← {"old": 1, "eid": 3, "t": 3, "retracted": [{"eid": 1, "kind": "supersede"}]}
→ check_answers {}
← {"invalidations": [{"name": "employer", "status": "stale", "cause": "supportRetracted", "t": 3,
"event": {"eid": 1, "kind": "supersede", "op": "retract", "t": 3}}]}
→ refresh_answer {"name": "employer"}
← {"answer": {"status": "fresh", "dependencies": [3],
"result": {"rows": [{"o": {"iri": "urn:tiramemsu:v:globex"}}], …}, …}}
And it can still say what it believed before the correction:
→ query {"language": "sparql", "text": "SELECT ?o WHERE { v:alice v:worksAt ?o }",
"view": {"kind": "asOf", "tx": 1}}
← {"view": {"kind": "asOf", "tx": 1},
"result": {"rows": [{"o": {"iri": "urn:tiramemsu:v:acme"}}], …},
"provenance": {"coverage": "complete", "gaps": []}}
The rules it keeps
Queries only read
The query tool refuses a SPARQL update or a Cypher write clause before anything runs. There is no raw SQL. Writes go through the typed verbs, so every write is a plain transaction with a number and a place in history.
→ query {"language": "sparql", "text": "INSERT DATA { v:a v:b v:c }"}
← isError: {"code": "Unsupported", "message": "unsupported: update in a query-only call"}
One file, no other
The server opens only the file it was started with. An argument such as path, db or database is refused, and so is any argument a tool does not declare.
← isError: {"code": "PathNotAllowed",
"message": "argument \"path\" would select a database; this server only serves the file it was started with"}
Read-only mode
With --read-only, the server lists seven tools: query, dependents, export_bundle, conflicts, preview_bundle, text_search and saved_answers. The write verbs are hidden, and calling one anyway fails with ReadOnly. The tools that save, check and refresh answers are hidden too, because they write answer records, even though they never write facts. preview_bundle stays: its dry run leaves the graph and history unchanged.
Every call has a budget
The flags above become one QueryBudget per tool call. A call past a bound fails with a structured error, commits nothing, and the server goes on serving. A result over the row limit is an error, never a quietly cut list, so the agent knows to ask a narrower question.
tiramemsu-mcp --db ./memory.db --max-rows 1
→ query {"language": "sparql", "text": "SELECT * WHERE { ?s ?p ?o }"}
← isError: {"code": "ResultLimitExceeded", "message": "result exceeds the limit of 1 rows"}
Provenance coverage
A SPARQL SELECT lists, for each row, the statements behind it. The response also says how far to trust that list. complete means every row is fully cited. incomplete comes with the gaps. A + path, for example, cites nothing for the steps along the way:
→ query {"language": "sparql", "text": "SELECT ?x WHERE { v:alice v:worksAt+ ?x }"}
← {"provenance": {"coverage": "incomplete", "gaps": ["recursivePath"],
"reason": "the query has a recursive path, whose statements are not cited"},
"result": {"rows": [{"x": {"iri": "urn:tiramemsu:v:acme"}}], "provenance": [[]]}, …}
unavailable means nothing was cited: a Cypher query, an ASK or a CONSTRUCT, or provenance turned off. An agent that quotes its sources should treat only complete as a full citation.
What it does not do
- It is local and stdio only. There is no HTTP transport, no users and no remote server.
- It does not extract facts from text and does not compute embeddings. The agent decides what to remember and how to phrase it.
- It serves one file per process. Two memories are two servers.
A note on vocabulary
The server’s instructions tell the agent the basics: facts have ids, layers are facts about facts, nothing is deleted, and v:alice is urn:tiramemsu:v:alice. Agents do better with a little more. A line in your project’s CLAUDE.md, such as “store people as v:firstname, use v:worksAt, v:livesIn and v:note, and put a v:confidence on facts you are not sure of”, keeps the memory consistent across sessions.