A transactional memory layer for agents

MemCommit keeps what agents did and learned as memories in one append-only log, with provenance, tiers, a declared structure, and an offline pass that turns finished sessions into notes.

$ git clone https://github.com/lamng3/memcommit.git && cd memcommit
$ pip install -e . && memcommit demo
Get started Concepts Playground

Time-travel a real memory log

replay of a real run

Try it: Click a memory, then Retract selected, and watch what was built on it go stale. Drag the slider to go back in time.

lsn0

Pick a memory, then retract it: everything derived from it goes stale, in one transaction. Drag the slider to see the state at any log position. The log and the cascade come from the library; this page only replays them.

What it does

One append-only log holds what agents did and what they learned. Everything else is a fold over it.

PlaygroundWrite memories into a log in the browser, retract a premise, and watch the cascade.Declare a structureKinds, scopes, and what must derive from what; every write is checked.Record sessionsEach turn, tool call, and result is its own memory, committed as it happens.Keep notesNotes at paths, a generated index, five tools a model can call.Consolidate offlineExtract, supersede, merge, split, and undo a whole pass.Invalidate by provenanceRetract a premise and everything built on it goes stale.Check the claimsA benchmark that says where the library helps and where it does not.

An agent that remembers needs two things. It needs the full record of what happened, so detail is never lost. It also needs short notes of what matters, so it can read what it knows in a few lines. MemCommit keeps both, in one log, and records where every note came from.

This manual describes how to install MemCommit, declare the structure of your memory, record sessions, keep and search notes, consolidate them offline, bound working memory, audit it, and run it from the command line. The last parts describe how it works inside and how the project is developed.

What MemCommit does today

  • Stores memories as immutable, content-addressed JSON values in an append-only log. Status (live, stale, retracted) and tier (short, mid, long, archive) come from replaying the log. See Concepts.
  • Checks every write against a memory structure you declare. See Declare a memory structure.
  • Records sessions as they happen: each turn, tool call, and result. See Sessions.
  • Keeps notes at paths, with a generated index and five tools a model can call. See Notes.
  • Consolidates sessions into notes offline, supersedes conflicting notes, merges duplicates, splits oversized ones, and can undo a pass. See Dreaming.
  • Marks stale everything built on a premise that stops holding, in one transaction. See Provenance.
  • Bounds working memory with a cache and replacement policies, and compacts both memories and the log. See Working memory and The database underneath.
Note

MemCommit is research software. Results so far are on synthetic workloads; see Benchmarks.

Quick start

git clone https://github.com/lamng3/memcommit.git
cd memcommit
pip install -e ".[dev]"
memcommit demo

The demo runs a scripted assistant, with no model and no network, through every part of the loop. See Install and run the demo.