tiramemsu

Your agent's brain loves Tiramemsu.
Layered, never-forget memory for agents, for Python.

Website · Time travel explained · Layered graphs explained · GitHub

Tiramemsu is an embedded graph database on SQLite. Every fact has its own id, so a fact can carry a confidence, a source or a belief about it, layer on layer. Every change is kept, with when the database learned it and when it was true in the world. This package is the Python binding: a native module (PyO3, stable ABI) and a typed, synchronous API.

Status: new. Tiramemsu was designed and implemented in September 2026. This package has not been published to PyPI yet, so the install line below works after the first release. Until then, build it from source.

Install

pip install tiramemsu

Python 3.9 or later. Each platform gets one prebuilt wheel (Linux x86_64 and aarch64, musllinux x86_64, macOS x86_64 and arm64, Windows x64), and SQLite is compiled in, so nothing else is needed. The package is typed (py.typed) and checked with mypy --strict.

git clone https://github.com/Volland/tiramemsu
cd tiramemsu/bindings/python
python3 -m venv .venv && source .venv/bin/activate
pip install maturin pytest mypy
maturin develop        # or: maturin develop --release
pytest

Quick start

Alice joins Acme in 2020, with a confidence of 0.8. We later learn she left at the end of 2023, and then that she joined Globex in March 2024.

from tiramemsu import Database, Iri

V = "urn:tiramemsu:v:"  # written `v:` in queries
alice, works_at, acme, globex, confidence = (
    Iri(V + name) for name in ("alice", "worksAt", "acme", "globex", "confidence")
)

db = Database("memory.db")

# 1. A fact is a statement with its own id, so it can carry a layer.
with db.transact() as tx:
    job = tx.assert_(alice, works_at, acme, valid_from="2020-01-01")
    tx.assert_(job, confidence, 0.8)  # `job` is a Ref: the statement, before it has an id
first = tx.report.asserted[0]         # its eid, known once the transaction has committed

# 2. Correct it. The layer moves to the new statement; nothing is deleted.
with db.transact() as tx:
    tx.supersede(first, valid_to="2024-01-01")

# 3. A new fact.
with db.transact() as tx:
    tx.assert_(alice, works_at, globex, valid_from="2024-03-01")

# 4. Ask the same question at different times.
q = "SELECT ?org WHERE { v:alice v:worksAt ?org }"

def orgs(view):
    return [row["org"].value.rsplit(":", 1)[-1] for row in view.sparql(q)]

orgs(db.now())                                  # ['acme', 'globex']  both episodes are live
orgs(db.as_of(tx=1))                            # ['acme']            what we believed after tx 1
orgs(db.as_of(tx=1).valid_at("2026-01-01"))     # ['acme']            we thought she was still there
orgs(db.now().valid_at("2026-01-01"))           # ['globex']          what is true today
orgs(db.now().valid_at("2024-02-01"))           # []                  between the two jobs

The same store speaks Cypher, and a layer is a relationship property:

db.now().cypher("MATCH (a)-[r:worksAt]->(c) RETURN c, r.confidence AS conf")
# columns ['c', 'conf'], rows [[acme, 0.8], [globex, None]]  (Globex has no confidence layer)

Two clocks

A view chooses when you look and when the fact was true. Every read takes a view, and views are immutable.

valid_at combines with any of them. Valid time is off unless you ask for it. Time travel and bitemporality, explained has the full story.

Writing

db.transact() is a context manager. It records the operations of the block and commits them as one transaction when the block exits cleanly, and the report is on tx.report. If the block raises, nothing is committed. db.transact(ops) takes a list of operation dicts instead. assert_, create and supersede return a Ref that later calls in the same block accept as a statement id, a subject or an object.

Times accept a datetime, a date, epoch milliseconds or an RFC 3339 string. db.transact(dry_run=True) reports what would happen and commits nothing. db.speculate(ops, queries) applies changes hypothetically, runs queries on the result, and keeps nothing.

Reading

expr is SPARQL property-path syntax with the predeclared prefixes v:, sys:, tm:, rdf: and xsd:, for example v:knows+. SPARQL supports RDF 1.2 annotations: {| v:confidence ?c |} reads a layer.

Terms

Errors

Every failure raises TiramemsuError with a .code:

Options

Database(path, readers=, busy_timeout_ms=, term_cache_capacity=, optimize_every=, path_max_hops=, path_max_states=). It works as a context manager, and Python threads can query one Database in parallel, because the GIL is released during each call.

Good to know

• The API is synchronous, like the Rust core. Reads run in parallel on a small connection pool, and writes serialize on one writer.
• Nothing is ever deleted: the SQLite file rejects DELETE. Forgetting means retracting, and the past stays exact.
• Results cross the native boundary as JSON, which is fine for agent memory and not meant for million-row result sets.
• There is no MCP server, WASM build or network server yet.

License

MIT OR Apache-2.0, at your option. See LICENSE-MIT and LICENSE-APACHE.