memtrail

Audit and time-travel for AI agent memory. A drop-in versioned backend with log, show, blame, diff, and revert — callable from inside the agent's reasoning loop.

Install

pip install memtrail

Quickstart

from memtrail import MemTrail

mt = MemTrail("my-agent")

# Commit a fact the agent learned
c1 = mt.commit(
    facts=[{"id": "user.tz", "content": "America/Los_Angeles"}],
    message="learned user timezone from greeting",
    author="agent",
)

# Later, investigate the memory
mt.blame("user.tz")        # → which commit introduced this fact?
mt.show(c1.hash)           # → full snapshot at that point
mt.log(limit=10)           # → recent history
mt.revert(c1.hash)         # → roll back to before a bad change

Use as agent tools

memtrail ships tool schemas in two shapes. The schemas describe the same six operations; pick whichever your model provider expects.

from memtrail import MemTrail
from memtrail.tools import anthropic_tools, openai_tools

mt = MemTrail("my-agent")

tools, dispatch = anthropic_tools(mt)   # input_schema shape
# or:
tools, dispatch = openai_tools(mt)      # function-tool shape

# When the model emits a tool call, route it:
result = dispatch(tool_name, tool_input)

The six tools exposed: memtrail_commit, memtrail_log, memtrail_show, memtrail_blame, memtrail_diff, memtrail_revert.

CLI

memtrail commit --repo my-agent --fact 'user.tz="PST"' -m "learned tz"
memtrail log    --repo my-agent
memtrail show   --repo my-agent <commit>
memtrail blame  --repo my-agent <fact_id>
memtrail diff   --repo my-agent <commit_a> <commit_b>
memtrail revert --repo my-agent <commit>
memtrail facts  --repo my-agent           # list facts at HEAD

Repo state lives at ~/.memtrail/<repo>.db by default. Override with --db /path/to.db or the MEMTRAIL_HOME environment variable.

Data model

• Fact: {id, content, metadata} — the atomic memory unit. Caller-provided ids enable targeted blame.
• Snapshot: a set of facts at a point in time, content-addressed by SHA-256 of canonical JSON.
• Commit: {hash, parent_hash, snapshot_hash, author, message, timestamp} — forms an append-only DAG.

commit(facts=...) upserts onto the parent snapshot (matched by id). Use commit(remove=[...]) to drop facts, or commit_snapshot(facts=...) for full replace.

Visual demo

A pure-stdlib walkthrough that animates the killer flow — learn → poison → blame → diff → revert — with a colored commit graph in your terminal:

python examples/visual_demo.py

Status

v0.1 — alpha. Zero runtime dependencies. Python ≥ 3.9.

License

MIT.