What’s new in 0.3
Version 0.2 could remember facts with layers and two clocks, and answer questions in SPARQL and Cypher. The work since then is about what an agent does with that memory every day: find things by words, notice when sources disagree, know when an old answer has gone stale, follow chains of events in time order, stay within a time limit, load a lot of data, and talk to the store over MCP.
There are ten features. Eight are opt-in: if you do not ask for them, the store behaves as it did before. The ninth changes how the Rust crate is built, and needs one line of attention if you turned default features off. The tenth runs the whole engine in a browser. All of it ships in 0.3.0. This page shows each one with short examples. The longer stories are in four articles, linked as we go.
v("alice") (Rust, Node) and Iri(V + "alice") (Python) make the IRI urn:tiramemsu:v:alice, which queries write v:alice. Names like alice, works_at and acme are such IRIs. Setup lines are trimmed.- Text recall with evidence ranking
- Conflict review and import previews
- Saved answers that know when they are stale
- Journeys in SPARQL and Cypher
- Query budgets and cancellation
- Bulk import
- A join operator for cyclic patterns
- An MCP server for agents
- Optional query front ends
- The engine in the browser
1. Text recall with evidence ranking
What it is. Search the string values of statements by words, in any view. Each hit is a statement, with its rank, a lexical score and the evidence the store holds about it: confidence, confirmations, how many authors, when it was added.
Why an agent wants it. People remember words, not graph patterns. “Something about Lisbon” is a fine place to start, as long as the answer also says how much to trust it.
db = Database("memory.db", text_index=True)
with db.transact() as tx:
note = tx.assert_(alice, Iri(V + "note"), "met at the Lisbon offsite")
tx.assert_(note, confidence, 0.9)
for hit in db.now().text_search("lisbon offsite", limit=10):
print(hit.rank, hit.text, hit.evidence.confidence) # 1 met at the Lisbon offsite 0.9
const db = Database.open("memory.db", { textIndex: true });
db.transact((tx) => {
const note = tx.assert(alice, v("note"), "met at the Lisbon offsite");
tx.assert(note, confidence, 0.9);
});
for (const hit of db.now().textSearch("lisbon offsite", { limit: 10 })) {
console.log(hit.rank, hit.text, hit.evidence.confidence); // 1 met at the Lisbon offsite 0.9
}
let db = Db::open(path, OpenOptions { text_index: true, ..OpenOptions::default() })?;
db.transact(TxOptions::default(), |tx| {
let e = tx.assert(v("alice"), v("note"), Value::str("met at the Lisbon offsite"), Valid::ALWAYS)?.eid();
tx.assert(e, v("confidence"), Value::Double(0.9), Valid::ALWAYS)?;
Ok(())
})?;
let q = TextQuery { limit: Some(10), ..TextQuery::new("lisbon offsite") };
for hit in db.now().text_search(&q)? {
println!("{} {} {:?}", hit.rank, hit.text, hit.evidence.confidence); // 1 met at the Lisbon offsite Some(0.9)
}
# SPARQL: tm:textMatch binds the statement id; join it back to its triple with ~
SELECT ?s ?o ?score WHERE {
?e tm:textMatch "lisbon" ; tm:textScore ?score ; tm:textLimit 10 .
?s ?p ?o ~ ?e
}
// Cypher: a procedure call
CALL tiramemsu.text.search('lisbon', {limit: 10}) YIELD statement, score
RETURN statement, score
Limits. It matches words, not meaning: there are no embeddings. Plain and language-tagged strings are indexed; typed literals are not. The index is built only when you ask (text_index, or rebuild_text_index() on an open file), and it needs SQLite with FTS5; without it, recall fails with MissingCapability and everything else works. Ranking is in a fixed order (lexical score, then confidence, confirmations, authors, recency, then id). There is no single blended score.
2. Conflict review and import previews
What it is. conflicts lists the places where one subject and predicate have different values at overlapping valid times, with every statement’s evidence: valid time, when it was added, confidence, confirmations, authors and sources. preview_bundle runs an import as a dry run and reports what it would do. Neither one writes a fact.
Why an agent wants it. Two sources disagree about where Alice worked in the spring of 2024. The agent should see both sides and decide, not have the store pick one quietly. And before it takes memories from another agent, it should see what they would change.
with db.transact() as tx:
tx.assert_(alice, works_at, acme, valid_from="2020-01-01")
tx.assert_(alice, works_at, initech, valid_from="2024-01-01", valid_to="2024-06-01")
for c in db.now().conflicts(p=works_at):
print(c.overlaps) # [(1704067200000, 1717200000000)]: January to June 2024
for val in c.values:
print(val.o, [(e.eid, e.confidence, e.authors) for e in val.statements])
bundle = db.now().bundle(eid) # a fact with its layers, for another database
preview = other.preview_bundle(bundle) # a dry run: nothing is committed
if preview.would_commit:
with other.transact() as tx:
tx.import_bundle(bundle) # checked again on the real write
db.transact((tx) => {
tx.assert(alice, worksAt, acme, { validFrom: "2020-01-01" });
tx.assert(alice, worksAt, initech, { validFrom: "2024-01-01", validTo: "2024-06-01" });
});
const [c] = db.now().conflicts({ p: worksAt });
c.overlaps; // [{ validFrom: 1704067200000, validTo: 1717200000000 }]
c.values.map((x) => [x.o, x.statements.map((e) => [e.eid, e.confidence, e.authors])]);
const preview = other.previewBundle(bundle); // dry run
if (preview.wouldCommit) other.transact((tx) => { tx.importBundle(bundle); });
db.transact(TxOptions::default(), |tx| {
tx.assert(v("alice"), v("worksAt"), v("acme"), Valid::from(0))?;
tx.assert(v("alice"), v("worksAt"), v("initech"), Valid::between(10, 20))?;
Ok(())
})?;
let view = db.now();
let works_at = view.encode(&v("worksAt"))?.unwrap();
let cs = view.conflicts(&ConflictQuery { predicate: Some(works_at), ..Default::default() })?;
assert_eq!(cs[0].overlaps, vec![Valid::between(10, 20)]); // when both were true
let preview = other.preview_bundle(&bundle)?; // dry run
if preview.would_commit() {
other.transact(TxOptions::default(), |tx| tx.import_bundle(&bundle).map(|_| ()))?;
}
Limits. It reports, it does not resolve: no majority vote and no automatic belief. Statements with the same object count as support for one value, not as a conflict. A predicate declared sys:many is flagged, not treated as a violation. The history view is refused. A preview burns the ids it allocated (they are never reused) but reserves nothing, so the real import checks everything again.
3. Saved answers that know when they are stale
What it is. Save a query with its result and the statements it cited. Later, check_saved_answers reads what changed since and marks the answer: stale when a cited statement was retracted or superseded, recheck when some other write might have changed it. Only a successful refresh makes it fresh again.
Why an agent wants it. Agents cache answers in prompts, notes and plans. The cache is only useful if the agent knows when to stop trusting it.
q = "SELECT ?o WHERE { v:alice v:worksAt ?o }"
db.save_answer("employer", q)
db.save_answer("then", q, view=db.as_of(tx=1)) # a fixed past: stays fresh
with db.transact() as tx:
tx.supersede(job, o=globex) # the cited fact is corrected
for m in db.check_saved_answers(): # each mark is reported once
print(m.name, m.status, m.cause) # employer stale supportRetracted
db.refresh_answer("employer").status # 'fresh', now with globex
const text = "SELECT ?o WHERE { v:alice v:worksAt ?o }";
db.saveAnswer("employer", { text });
db.saveAnswer("then", { text, view: db.asOf({ tx: 1 }) }); // stays fresh
db.transact((tx) => { tx.supersede(job, { o: globex }); });
for (const m of db.checkSavedAnswers()) console.log(m.name, m.status, m.cause);
// employer stale supportRetracted
db.refreshAnswer("employer").status; // "fresh"
let q = SavedQuery::sparql("SELECT ?o WHERE { v:alice v:worksAt ?o }");
db.save_answer("employer", &q)?;
db.save_answer("then", &q.clone().on(ViewSpec::as_of(TimeRef::Tx(1))))?;
db.now().sparql("DELETE DATA { v:alice v:worksAt v:acme }")?;
for m in db.check_saved_answers()? {
println!("{} {:?} {:?}", m.name, m.status, m.cause); // employer Stale SupportRetracted
}
let fresh = db.refresh_answer("employer")?; // AnswerStatus::Fresh
Limits. It is conservative on purpose. Under a current view, any later write marks the answer recheck, because a new row could change it. Each answer lists why its citations cannot prove it fresh: mutableView, noProvenance (Cypher, ASK), negativePattern, existsPattern, recursivePath, virtualPredicate, volatile, clock. Nothing re-runs in the background: you call check and refresh. Saved answers live in tables added by storage format 3. Opening an older file migrates it forward, and 0.2 cannot open the migrated file.
More in Recall, review, recheck.
4. Journeys in SPARQL and Cypher
What it is. A time-respecting path never goes back in valid time: each hop must still hold when the walk reaches it. The path engine could already do this from Rust. Now both query languages can ask for it, and get the earliest arrival at each end. Every path query can also report whether it was complete.
Why an agent wants it. “Who could have heard this from Ana after the first of March?” is a question about the order of events. A plain path ignores order and gives wrong answers.
# SPARQL: every property path in the group is a journey
SELECT ?who ?t WHERE {
SERVICE <urn:tiramemsu:tm:timeRespecting/2026-03-01> {
v:ana v:met+ ?who .
?who tm:arrival ?t
}
} ORDER BY ?t
// Cypher: a MATCH modifier
MATCH TIME RESPECTING AFTER date('2026-03-01') ARRIVAL AS t
(a {`@id`: 'v:ana'})-[:met*]->(who)
RETURN who, min(t) AS arrived ORDER BY arrived
q = """SELECT ?who ?t WHERE {
SERVICE <urn:tiramemsu:tm:timeRespecting/$since> { v:ana v:met+ ?who . ?who tm:arrival ?t }
} ORDER BY ?t"""
r = db.now().sparql(q, params={"since": "2026-03-01"}, path_completeness=True)
[(row["who"], row["t"]) for row in r] # ben at 2026-03-02, cara at 2026-03-05 (epoch ms)
r.path_completeness # PathCompleteness(kind='exhaustive', max_hops=None, complete=True)
const q = "SELECT ?who ?t WHERE { SERVICE <urn:tiramemsu:tm:timeRespecting/$since> " +
"{ v:ana v:met+ ?who . ?who tm:arrival ?t } } ORDER BY ?t";
const r = db.now().sparql(q, { params: { since: "2026-03-01" }, pathCompleteness: true });
r.rows; // ben at 1772409600000 (2026-03-02), cara at 1772668800000 (2026-03-05)
r.pathCompleteness; // { kind: "exhaustive", maxHops: null, complete: true }
const rep = db.now().pathReport(v("ana"), "met+", { maxHops: 1 });
rep.completeness; // { kind: "bound", maxHops: 1, complete: true }
// here the valid times are small integers (epoch ms), as in the crate README
let q = "SELECT ?who ?t WHERE { SERVICE <urn:tiramemsu:tm:timeRespecting/$since> \
{ v:a v:met+ ?who . ?who tm:arrival ?t } } ORDER BY ?t";
let opts = SparqlOptions { params: ir::params([("since", Value::Int(2))]), ..Default::default() };
let r = view.sparql_with(q, &opts)?;
let s = r.solutions().unwrap();
s.path_completeness; // Some(PathCompleteness::Exhaustive)
Limits. The start of a journey must be bound, because it runs forward. In SPARQL only real path expressions (*, +, ?, ^, |) are journeys; a plain a/b is turned into triple patterns. Arrivals are epoch milliseconds. A Cypher * is cut at path_max_hops (15 by default), and the report then says cap: longer journeys may exist.
More in Journeys that respect time.
5. Query budgets and cancellation
What it is. A QueryBudget bounds one call: a deadline, a cancel handle, how long to wait for a free reader, and how many rows and bytes the result may hold. A call past a bound fails with a typed error: DeadlineExceeded, Cancelled, PoolTimeout or ResultLimitExceeded.
Why an agent wants it. An agent loop has a time limit. One unlucky query should not eat it, and a huge result should not fill the context window.
from tiramemsu import QueryBudget, TiramemsuError
view = db.now().with_budget(QueryBudget(timeout_ms=500, max_rows=10_000))
view.sparql("SELECT ?o WHERE { v:alice v:worksAt ?o }")
with db.transact(budget=QueryBudget(timeout_ms=1_000)) as tx:
tx.assert_(alice, works_at, acme)
db.cancel("job-42") # from another thread: stops the call that uses cancel_key="job-42"
const view = db.now().withBudget({ timeoutMs: 500, maxRows: 10_000 });
view.sparql("SELECT ?o WHERE { v:alice v:worksAt ?o }");
db.transact((tx) => { tx.assert(alice, worksAt, acme); }, { budget: { timeoutMs: 1_000 } });
try {
db.now().withBudget({ maxRows: 1 }).sparql("SELECT ?s WHERE { ?s v:worksAt ?o }");
} catch (e) {
e.code; // "ResultLimitExceeded" when there are two or more rows: never a silent prefix
}
let budget = QueryBudget {
timeout: Some(Duration::from_millis(500)),
max_rows: Some(10_000),
..Default::default()
};
let rows = db.now().with_budget(&budget).sparql("SELECT ?o WHERE { v:alice v:worksAt ?o }")?;
let token = CancelToken::new(); // clone it into another thread and call cancel()
let stopped = QueryBudget { cancel: Some(token.clone()), ..Default::default() };
token.cancel();
let r = db.transact_budgeted(TxOptions::default(), &stopped, |tx| { /* … */ Ok(()) });
assert!(matches!(r, Err(Error::Cancelled))); // and nothing was committed
Limits. Calls are unbounded unless you set a budget. A result over a limit is an error, not a truncated list, so ask for less with LIMIT when you want a prefix. The Node and Python APIs are synchronous: db.cancel(key) from the same thread only stops a call that starts later, so cancel from another thread (Python) or use a deadline.
More in Bounded queries and bulk loads.
6. Bulk import
What it is. A session for large loads. Each chunk is one ordinary atomic transaction. Chunks skip the planner statistics refresh, and finish runs it once at the end. While the session is open, other writes are refused with ImportInProgress, and reads see the last committed chunk.
Why an agent wants it. Loading a chat archive or a document set should neither hold the writer for minutes in one transaction nor re-analyse the whole file after every batch.
with db.bulk_import() as imp: # finishes on a clean exit, cancels if the block raises
for batch in batches:
with imp.chunk() as tx:
for s, p, o in batch:
tx.assert_(s, p, o)
print(imp.summary.progress.chunks, imp.summary.analyzed) # 4 True
const imp = db.bulkImport();
try {
for (const batch of batches) {
imp.chunk((tx) => { for (const [s, p, o] of batch) tx.assert(s, p, o); });
}
} finally {
const summary = imp.finish(); // { progress, analyzed, statisticsDue, maintenanceError }
}
let mut import = db.bulk_import()?;
for batch in 0..4 {
import.chunk(|tx| {
for i in 0..250 {
tx.assert(v(&format!("doc{batch}-{i}")), v("mentions"), v("acme"), Valid::ALWAYS)?;
}
Ok(())
})?;
}
let summary = import.finish(); // one ANALYZE; summary.analyzed == true
Limits. It is not one atomic import. A failing chunk rolls back alone and earlier chunks stay committed. Cancelling, or dropping the session in Rust, keeps the committed chunks and skips the analysis. A failed final analysis is reported in maintenance_error, never a rollback. There is no new file-format parser: you still turn your data into statements.
7. A join operator for cyclic patterns
What it is. A native leapfrog triejoin for pure cyclic patterns, such as triangles a→b→c→a. It runs inside SQLite as a table function and is off by default. When on, the planner routes a cyclic pattern to it only if the pattern is large enough, and explain tells you which route it took and why.
Why an agent wants it. Questions like “which of my contacts know each other?” are cycles. On skewed graphs SQLite’s nested loops can get very slow there.
db = Database("memory.db", lftj=True, lftj_min_rows=0) # 0: route even small patterns
q = "SELECT * WHERE { ?a v:knows ?b . ?b v:knows ?c . ?c v:knows ?a }"
plan = db.now().explain_sparql(q)
[(r["kind"], r["note"]) for r in plan["regions"]]
# [('sql', 'none'), ('nativeLftj', 'lftjNative')]
const db = Database.open("memory.db", { lftj: true, lftjMinRows: 0 });
const plan = db.now().explainSparql(q);
plan.regions.map((r) => [r.kind, r.note]); // [["sql", "none"], ["nativeLftj", "lftjNative"]]
// with lftj off: [["sql", "cyclicLftjDisabled"]]
let opts = OpenOptions {
planner: PlannerOptions { lftj: LftjConfig { enabled: true, min_rows_estimate: 0 } },
..OpenOptions::default()
};
let db = Db::open(path, opts)?;
let plan = db.now().explain_sparql(q)?;
for r in &plan.regions { println!("{:?} {:?}", r.kind, r.note); }
// Sql None
// NativeLftj LftjNative
Limits. Only pure cyclic basic graph patterns (up to 32 variables) go to the operator. Everything else, and anything below min_rows_estimate (100 000 statements by default), stays in SQL, and explain says why: cyclicLftjDisabled, lftjUnavailable, lftjUnsupportedShape or lftjBelowEstimate. Results are the same on both routes, and budgets still apply. The operator builds all its output rows in memory before SQLite reads them, so very large outputs cost memory. The speed-ups so far are from a small benchmark, described in Bounded queries and bulk loads.
8. An MCP server for agents
What it is. tiramemsu-mcp is a separate binary that serves one memory file to an MCP client, such as Claude Code or Claude Desktop, over stdio. It has fourteen typed tools: write verbs (assert, confirm, supersede, import_bundle), read tools (query, text_search, conflicts, preview_bundle, dependents, export_bundle) and the saved-answer tools.
Why an agent wants it. The agent gets a memory without anyone writing glue code, and the memory keeps its rules: queries only read, every call has a budget, and answers say which statements back them.
# install from crates.io
cargo install tiramemsu-mcp
# register it with Claude Code
claude mcp add tiramemsu -- tiramemsu-mcp --db ./memory.db --text-index
# or a read-only memory, with tighter bounds
claude mcp add tiramemsu-ro -- tiramemsu-mcp --db ./memory.db --read-only --timeout-ms 5000 --max-rows 500
Limits. Local stdio only: no HTTP transport, no users, no remote server. The server opens only the file it was started with; an argument such as path or db is refused with PathNotAllowed. There is no raw SQL and no update through query. It does not extract facts from text or compute embeddings; the agent decides what to remember.
More in Give your agent a memory over MCP.
9. Optional query front ends
What it is. The Rust crate tiramemsu now has Cargo features. exec is the shared query engine: the IR, the planner, the path engine and the cyclic-join operator. sparql and cypher are the two front ends, and each one brings in exec. The default build has both, as before. With default-features = false you get the core tier: transactions, speculation, the now, as_of and history views, triples, dependents, fact bundles, bundle previews, conflict review, text recall, bulk import and query budgets, with no parser at all.
Why an agent wants it. An agent that only writes facts and reads them back by pattern or by words does not need two query parsers in its binary. A smaller build compiles faster and has less code to audit.
# Cargo.toml: core only, no query engine and no parser
tiramemsu = { version = "0.4", default-features = false }
# SPARQL and paths, no Cypher parser
tiramemsu = { version = "0.4", default-features = false, features = ["sparql"] }
Limits. A disabled API is missing at compile time, not an error at run time. Saved answers need both front ends. Build OpenOptions with ..OpenOptions::default(), because its query-engine fields exist only with exec. The file format does not depend on the features: a file written by a core-only build opens in a full build, and the other way round. The JSON bridge, the MCP server and the Node and Python packages always use the full build.
default-features = false used to build both front ends anyway, and the sparql feature only switched on a test suite. Now it means the core tier. If you declared the dependency with default-features = false and use SPARQL, Cypher or paths, add features = ["sparql", "cypher"] (or the one you use). If you kept the defaults, nothing changes.10. The engine in the browser
What it is. A second SQLite host, tm-wasm, runs tiramemsu on SQLite compiled to WebAssembly. The database lives in memory or in the browser's Origin Private File System (OPFS), inside a Web Worker. SPARQL, Cypher, paths, the cyclic-join operator and text recall all work there. The file is the native format: export it from the browser and open it with Rust, Node.js or Python, or import a native file.
Why an agent wants it. A browser agent or a local-first app can keep its memory on the user's machine, with the same queries and the same history as the server-side agent, and hand the file over when needed.
// worker.js, loaded with new Worker("worker.js", { type: "module" })
import init, { Database } from "./pkg/tiramemsu_wasm.js";
await init();
const db = await Database.open(JSON.stringify({ storage: "opfs", path: "/memory.db", journal: "rollback" }));
const iri = (s) => ({ iri: `urn:tiramemsu:v:${s}` });
db.call("transact", JSON.stringify({ ops: [{ op: "assert", s: iri("alice"), p: iri("knows"), o: iri("bob") }] }));
db.call("sparql", JSON.stringify({ view: { kind: "now" }, text: "SELECT ?o WHERE { v:alice v:knows ?o }" }));
const bytes = db.exportFile(); // opens natively with tiramemsu
The calls are the JSON bridge that the Node.js and Python packages use, so the operations and error codes are the same. The binding README has the full worker and page code and the build steps.
Limits. The browser package is built from the repository; it is not on npm yet. The runtime has no WAL and no shared memory, so the host uses a rollback journal and one connection, and asking for WAL fails at open instead of quietly falling back. STAT4 is not compiled in, so opening a non-empty file runs a full ANALYZE. Query budgets and bulk import sessions are refused in the browser. The .wasm file is about 11 MB before wasm-opt.
Since 0.3: version 0.4.0
0.4.0 adds the integrity repairs described in the paper. Writes that point at a retracted or never-allocated statement are refused. A correction no longer replays the layers of memberships it drops. Triggers in the file check that every statement date names the transaction that is writing it. Those triggers are storage format 4. A file opened by 0.4.0 migrates to format 4 without rewriting any history, and 0.3.0 cannot open it afterwards. Nothing else in this page changes.
Still to come
The crates are on crates.io and the Python package is on PyPI. The Node.js package and the browser package are built and tested but not on npm yet. Vector search, crypto-shredding and a network server are on the roadmap.