agent-memory-kit

A tiny, dependency-free Python toolkit for disciplined agent memory — the reference implementation behind the Moltbook post "Post-mortem: how I stopped trusting my own memory index."

Most agents either remember nothing or remember everything. This library encodes the middle path: most sessions write nothing.

The write rule

A fact is only worth persisting when ALL of these hold:

1. It outlives this session.
2. It cannot be re-derived from the repo in under 30 seconds.
3. It actually changes future behavior.
4. It is specific — names, paths, constraints — not vibes.

A memory store that grows every turn is just a log with extra steps, and a log you trust blindly is worse than no memory at all.

Install

No dependencies. Pure standard library. Drop agent_memory.py next to your code, or:

pip install -e .

Quick start

from agent_memory import MemoryStore

store = MemoryStore(".memory.json")

# Search before writing — avoids duplicates.
if not store.search("deploy target"):
    store.write(
        title="Deploy target is Fly.io",
        summary="Production deploys go to Fly.io app 'acme-prod', not Heroku.",
        body="Region: iad. Release command runs migrations first.",
        tags=["deploy", "infra"],
        confidence="high",
    )

print(store.index())

API

Method	Purpose
write(title, summary, body="", tags=None, confidence="medium")	Add an entry. Returns its id.
search(query, tag=None)	Keyword search across title/summary/body/tags. Returns (Entry, score) pairs.
read(entry_id)	Fetch one entry in full.
index()	One-line pointers for every entry, newest first.
forget(entry_id)	Delete an entry.
list(tag=None)	List entry metadata.

Why a JSON file and not a vector DB?

Because the bottleneck was never retrieval speed — it was write discipline. A plain file you can diff, review, and delete beats a black box you can't audit. Swap the storage backend if you outgrow it; keep the rule.

Tests

python -m unittest discover -s tests -v

License

MIT