Tiramemsu

Recall, review, recheck

Tiramemsu articles · 3 October 2026

A memory is only half the job. The other half is using it well: finding the right thing when you only half remember it, noticing when two things you remember cannot both be true, and knowing when an answer you worked out last week is no longer safe to repeat. People do this without thinking. An agent has to be told.

Tiramemsu 0.3 adds one tool for each step. Text recall finds statements by words. Conflict review shows where memory disagrees with itself. Saved answers say when a stored answer has gone stale. None of them changes a fact on its own. They report, and the agent decides.

One small memory

Two agents have written about Alice. Agent 7 says she has worked at Acme since 2020, with a confidence of 0.9. Agent 9 says she worked at Initech from January to June 2024, with a confidence of 0.6. Each also left a note. The examples are Python; Rust and Node.js have the same calls, shown in What’s new in 0.3.

from tiramemsu import Database, Iri

V = "urn:tiramemsu:v:"
SYS_AUTHOR = Iri("urn:tiramemsu:sys:author")
alice, works_at, note, confidence, acme, initech, agent7, agent9 = (
    Iri(V + n) for n in ("alice", "worksAt", "note", "confidence", "acme", "initech", "agent7", "agent9"))

db = Database("memory.db", text_index=True)

with db.transact() as tx:
    tx.meta(SYS_AUTHOR, agent7)                      # who wrote this transaction
    job = tx.assert_(alice, works_at, acme, valid_from="2020-01-01")
    tx.assert_(job, confidence, 0.9)
    tx.assert_(alice, note, "met Alice at the Lisbon offsite, she leads the Acme data team")

with db.transact() as tx:
    tx.meta(SYS_AUTHOR, agent9)
    other = tx.assert_(alice, works_at, initech, valid_from="2024-01-01", valid_to="2024-06-01")
    tx.assert_(other, confidence, 0.6)
    tx.assert_(alice, note, "Alice mentioned Lisbon when we talked about Initech")

Recall: find it by words

The user says “what do we know about Alice and Lisbon?”. There is no graph pattern in that sentence, only words. text_search takes the words and returns statements.

for hit in db.now().text_search("alice lisbon", limit=5):
    print(hit.rank, hit.text, hit.evidence.authors)
# 1 Alice mentioned Lisbon when we talked about Initech 1
# 2 met Alice at the Lisbon offsite, she leads the Acme data team 1

Each hit is a whole statement, with its id, subject, predicate and object, so the agent can follow it into the graph. It also carries evidence: the stated confidence (None when the statement has no confidence layer, never a guess), how many times it was confirmed, how many distinct authors wrote or confirmed it, and when it was added.

The ranking is a fixed order, not a blended score. First the lexical score (FTS5’s bm25, so rarer words and shorter texts count more). Ties are broken by confidence, with absent confidence last, then confirmations, then authors, then the newer statement, then the id. The rule has a name, tiramemsu-text-rank/1, so if it ever changes, the name changes with it.

Recall respects time like every other read. db.as_of(tx=1).text_search("lisbon") returns only the first note, because the second did not exist yet. A retracted statement drops out of now() but can still be recalled as of before the retraction.

The same recall works inside queries. In SPARQL, tm:textMatch binds the statement id, and ~ joins it back to its triple:

SELECT ?s ?o ?score WHERE {
  ?e tm:textMatch "lisbon" ; tm:textScore ?score ; tm:textLimit 10 .
  ?s ?p ?o ~ ?e
}

In Cypher it is a procedure: CALL tiramemsu.text.search('lisbon', {limit: 10}) YIELD statement, score RETURN statement, score.

What recall is not. It matches words, case and accent insensitive, with all, any or phrase modes and a trailing * for a prefix. It does not know that “Lisboa” is “Lisbon”. Recall by meaning is a separate operation: vector recall now exists, over embeddings you supply, and hybrid recall fuses it with this text search. The index is derived: build it with text_index=True, and every write keeps it current. It needs SQLite with FTS5.

Review: see where memory disagrees

Both agents wrote about Alice’s employer, and for five months of 2024 they cannot both be right, unless she had two jobs. conflicts finds such places: same subject, same predicate, different objects, overlapping valid time.

for c in db.now().conflicts(p=works_at):
    print(c.overlaps)                           # [(1704067200000, 1717200000000)]: Jan to Jun 2024
    for val in c.values:
        for e in val.statements:
            print(val.o, e.eid, e.confidence, e.authors)
# acme     2  0.9  [agent7]
# initech  6  0.6  [agent9]

For each value the agent gets every statement that supports it and that statement’s evidence: valid time, the transaction that added it, the stated confidence, the transactions that confirmed it, and the authors and sources of those transactions. Two statements with the same object are support for one value, not a conflict. A predicate declared sys:many (several values are normal) is flagged with declared_many rather than reported as a problem.

What it does not do is choose. There is no majority vote and no “highest confidence wins”. Those are policies, and the right one depends on the agent. Here the agent might ask the user, or trust agent 7 because it has been right before. Whatever it decides, it writes it down with an ordinary verb: retract the wrong statement, supersede it with a corrected valid time, or confirm the one it believes. The history keeps both sides, so the decision can be reviewed later.

Preview before you import

The same caution applies to memories from outside. A bundle carries a fact with its layers and evidence from one database to another. preview_bundle runs the import as a dry run on the writer and reports what it would do: which statements are new, which already exist and would be reused, what a cardinality-one predicate would retract, and whether it would fail a schema check.

bundle = db.now().bundle(job)
preview = other_db.preview_bundle(bundle)    # nothing is committed
if preview.would_commit:
    with other_db.transact() as tx:
        tx.import_bundle(bundle)             # checked again on the real write

A schema failure comes back as preview.failure instead of an exception, so the agent can read it. The preview burns the ids it allocated, which are never reused, and reserves nothing: if the database changes between the preview and the import, the import checks everything again.

Recheck: know when an answer is stale

Agents keep answers around: in a plan, a summary, a system prompt. “Alice works at Acme and Initech” was true of the memory an hour ago. Is it still? save_answer runs a query and stores the result together with the statements it cited.

db.save_answer("employer", "SELECT ?org WHERE { v:alice v:worksAt ?org }")
db.saved_answer("employer").coverage        # ['mutableView']

Now the agent settles the conflict and retracts agent 9’s statement. Later, it asks what changed:

with db.transact() as tx:
    tx.retract(6)

for m in db.check_saved_answers():
    print(m.name, m.status, m.cause, m.event)
# employer stale supportRetracted {'eid': 6, 'kind': 'explicit', 'op': 'retract', 't': 3}

db.refresh_answer("employer").status       # 'fresh', and the result is now only acme

There are three states, and the rules are short:

Each invalidation is reported once, with the event that caused it, so an agent can poll check_saved_answers after every turn without seeing the same news twice.

Why “conservative”

Citations can prove that an answer is wrong: a cited fact is gone. They cannot prove that it is right. A new fact might add a row. A NOT EXISTS might stop being true. A path query does not cite the statements along the path. So every saved answer lists why its citations are not enough, in coverage:

ReasonMeans
mutableViewIt reads the current state, so new writes can change it
noProvenanceThe query cites nothing: Cypher, or ASK
negativePattern, existsPatternIt depends on something being absent, or on a nested test
recursivePathA + or * path, whose steps are not cited
virtualPredicate, volatileIt reads bookkeeping or the volatile table, which have no statement ids
clockIt uses NOW(), so it changes when the clock moves

An answer saved on a fixed past, for example view=db.as_of(tx=1), stays fresh forever: the past does not change. That is a useful trick. If an agent wants to quote what it knew at a decision point, it saves the answer as of that transaction, and the quote never goes stale.

No magic. Nothing runs in the background. The agent calls check and refresh when it wants to. Saved answers are derived records in their own tables (storage format 3): saving, checking and refreshing never take a transaction number or touch the history of facts.

The loop

Put together, the three steps make a loop an agent can run every turn:

  1. Recall by words, and look at the evidence on each hit before using it.
  2. Review the conflicts on what it is about to say, and before importing someone else’s memory, preview it.
  3. Decide with an ordinary write: retract, supersede or confirm. The history records who decided what.
  4. Recheck its saved answers, and refresh the stale ones before repeating them.

All of this is also available to an agent over MCP, as the tools text_search, conflicts, preview_bundle, save_answer, check_answers and refresh_answer. That is the subject of the next article.

Next: give your agent a memory over MCP →