Tiramemsu

Give your agent a memory over MCP

Tiramemsu articles · 3 October 2026

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

FlagMeaningDefault
--db <path>The database file. The only file the server opens.required
--read-onlyHide and refuse the tools that writeoff
--timeout-msDeadline of one tool call30 000
--reader-timeout-msHow long to wait for a free read connectionno limit
--max-rowsRows one call may decode10 000
--max-bytesBytes one call may produce8 MiB
--text-indexBuild the text index at open, for text_searchoff

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.

ToolWhat it does
assertAdd a fact, with optional valid time and graph. Repeating a fact returns the existing id with new: false
confirmRecord that another source agrees with a fact
supersedeCorrect a fact; its layers move to the new one and the old one stays in history
import_bundleImport a fact with its layers from another memory
queryRun a SPARQL or Cypher read, in any view, with provenance
text_searchRecall statements by words, with evidence per hit
conflictsList disagreeing values with their evidence
preview_bundleDry-run an import and report what it would do
dependentsWhat retracting a fact would take with it
export_bundleA fact with its layers and evidence, to hand to another memory
save_answer, saved_answers, check_answers, refresh_answerKeep 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

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.

Next: journeys that respect time →