Skip to main content

Tiramemsu: a brain taking a bite out of a tiramisu whose layers are a graph

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.

Build from source instead

You need Python 3.9 or later and the Rust toolchain pinned by the repository (1.91.1).

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

If another rustc is first on your PATH (for example Homebrew's), put rustup's first: export PATH="$HOME/.cargo/bin:$PATH".

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.

You want Code
What we believe now db.now()
What we believed after transaction n db.as_of(tx=n)
What we believed at a wall-clock time db.as_of(instant="2026-09-01T12:00:00Z")
What was true on a date view.valid_at("2026-01-01")
Every statement ever, with retracted ones db.history()

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.

Method What it does
assert_(s, p, o, valid_from=, valid_to=, on_existing=) Adds a statement; idempotent when a live one with an overlapping valid time exists
create(s, p, o, ...) Always adds one, for parallel edges
retract(eid) Ends belief in a statement and every layer about it
retract_matching(s=, p=, o=) Retracts every live match
supersede(eid, o=, valid_from=, valid_to=) Corrects a statement and replays its layers on the new one. A bound you leave out is kept; None clears it
confirm(eid) Records that another source agrees
meta(p, o), upsert(p, o), new_node() Transaction metadata, unique upsert, an anonymous node
add_to_graph(eid, g), remove_from_graph, clear_graph, create_graph, drop_graph Named graphs as tags on statements. A statement (Stmt(eid) or a Ref) can name a graph, so an edge can hold a subgraph
import_bundle(bundle) Imports a bundle from view.bundle, possibly read from another database; returns a Ref to the imported root, and its entry in tx.report.results lists the imported statements
cypher(text, params=None) A Cypher query that may write, inside the same transaction

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

Method Returns
view.sparql(text, provenance=False) A select result (iterate it for rows of variable to term; .vars lists the variables, .provenance the statements behind each row), an ask, a graph, or an update result
view.cypher(text, params=None) A result with columns and rows
view.triples(s=, p=, o=) Statement values with eid, s, p, o, t_add, t_ret, valid_from, valid_to, ret_kind
view.path(start, expr, mode="reach", max_hops=None, graphs=None, time_respecting=False) Endpoints with hop counts and arrival. mode is "reach", "trail", "anyShortest" or "allShortest"
view.dependents(eid) The statements that stand on eid: what retracting it would cascade to
view.bundle(eid) The statement with its layers and evidence, as a tiramemsu-bundle/1 dict
view.events(since=0) The change log after a transaction
view.graphs(), view.graph_members(g), view.values(s, key) Named graphs and values

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.

With provenance=True a select result's .provenance holds, for each row, the Stmt values that produced it. graphs keeps every hop of a path inside the listed graphs. time_respecting=True (or a time to start after) makes each hop start no earlier than the previous one, and every row then carries its earliest arrival in epoch milliseconds.

Terms

Python Stored as
str, bool plain string, boolean
int xsd:integer, exact at any size
float xsd:double
datetime, date xsd:dateTime, xsd:date; they come back as the same Python types. A naive datetime is taken as UTC
Iri(s) IRI
Literal(lex, datatype=), Literal(lex, lang=) typed or language-tagged literal
Node(n), BNode(n), Stmt(eid), TxId(n) anonymous node, blank node, statement id, transaction

Errors

Every failure raises TiramemsuError with a .code:

Code Meaning
Parse SPARQL, Cypher or path text is invalid
InvalidArgument The call itself is malformed: an unknown operation, a missing field, a term of the wrong shape
NotLive The statement does not exist or was already retracted
Unsupported Valid but outside the supported subset, such as a Cypher write through a read view
UniqueViolation A sys:unique predicate already has a live holder of that value
ValueTypeMismatch The object does not match the predicate's sys:valueType
SubjectTypeMismatch The subject does not match the predicate's sys:subjectType, such as a layer predicate on a plain node
CascadeLimitExceeded A retraction would touch more than max_cascade statements
PathLimitExceeded A path search exceeded its state limit
InvalidPatch A supersede patch tried to change the subject or predicate
IdSpaceExhausted An id counter passed 2^48 − 1
Sqlite A SQLite failure, such as a locked or unreadable file

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.

Metadata

Release files for tiramemsu 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tiramemsu 0.2.0
File Size Uploaded Provenance Actions
tiramemsu-0.2.0.tar.gz 657.8 kB With provenance Details for tiramemsu-0.2.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for tiramemsu 0.2.0
File Actions
tiramemsu-0.2.0-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for tiramemsu-0.2.0-cp39-abi3-win_amd64.whl
tiramemsu-0.2.0-cp39-abi3-musllinux_1_2_x86_64.whl CPython 3.9 abi3 Linux musl 1.2+ x86-64 Details for tiramemsu-0.2.0-cp39-abi3-musllinux_1_2_x86_64.whl
tiramemsu-0.2.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.9 abi3 Linux glibc 2.17+ x86-64 Details for tiramemsu-0.2.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
tiramemsu-0.2.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for tiramemsu-0.2.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
tiramemsu-0.2.0-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for tiramemsu-0.2.0-cp39-abi3-macosx_11_0_arm64.whl
tiramemsu-0.2.0-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for tiramemsu-0.2.0-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 31.7 MB

Release files / tiramemsu-0.2.0.tar.gz

Download URL tiramemsu-0.2.0.tar.gz
Size 657.8 kB
Tags Source
SHA-256 checksum
How to use checksums
72d1c50d6f49dc3aa6bb98bf996b4cc9b784e0cfae79365c36e253e7724a9cdd
BLAKE2b-256 checksum
How to use checksums
52a83155f7dafc1347b75df867e61ee00f158aea1bf1d272cb8478fac700a1bd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

Release files / tiramemsu-0.2.0-cp39-abi3-win_amd64.whl

Download URL tiramemsu-0.2.0-cp39-abi3-win_amd64.whl
Size 4.9 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
830f4bfc0fe1e86cf4cfd55312f1764cb76c3b2d2ca8e5b162e44fa520fe7628
BLAKE2b-256 checksum
How to use checksums
2ac4cab0b752f03cca6601ebb3567c4602be8626f03e60229509c4f13d6d5b2d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

Release files / tiramemsu-0.2.0-cp39-abi3-musllinux_1_2_x86_64.whl

Download URL tiramemsu-0.2.0-cp39-abi3-musllinux_1_2_x86_64.whl
Size 5.7 MB
Tags CPython 3.9 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
bd866096beb02125407c474f37236cc6ad1b3ec32f1877af3213df0467e639c1
BLAKE2b-256 checksum
How to use checksums
36b0f7dfc0dcdf2d807ab26e475d3086a6dcd80fe022b000e93f2cc6dd63b10a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

Release files / tiramemsu-0.2.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL tiramemsu-0.2.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 5.4 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
68734259650bef8207b78f582c6da4c59f7e7ee9792e02351bb51ef53caa0de7
BLAKE2b-256 checksum
How to use checksums
138d818c8d16257ea53b7eaa5a329dedc7fe2a149b49c394f9de3c4f3f2d267a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

Release files / tiramemsu-0.2.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL tiramemsu-0.2.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 5.2 MB
Tags CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
77967db5eb726d3093bccc73f83748709fb1a38fb4e8fcbea3192f7853f0e979
BLAKE2b-256 checksum
How to use checksums
0ece72e4bee95240b66e704953b4b64984f728050aec2086d77975d05c8d3308
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

Release files / tiramemsu-0.2.0-cp39-abi3-macosx_11_0_arm64.whl

Download URL tiramemsu-0.2.0-cp39-abi3-macosx_11_0_arm64.whl
Size 4.8 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
d5c9878be50b823a6a0d43c1939c088a4737cfc3060a631e0513c76afbb6af5b
BLAKE2b-256 checksum
How to use checksums
1ddc7aa74a1ddc053e207cd961269c9eed88423bbf898a86ef8ffa5abccd01c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

Release files / tiramemsu-0.2.0-cp39-abi3-macosx_10_12_x86_64.whl

Download URL tiramemsu-0.2.0-cp39-abi3-macosx_10_12_x86_64.whl
Size 5.1 MB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
60eb871fca096475c61005eb8b6b4b4ea5cc7010c8a5dbc2203fcbab06e7bdd8
BLAKE2b-256 checksum
How to use checksums
0a4fe8857116c73525614d80cf8e386679d06067a7c8c5b839611419ce121360
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

Security for tiramemsu 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 7 files in this release have been uploaded with provenance metadata.

Select from 7 files

Attestation for tiramemsu-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page