The Shelf / Workshop / Agent Memory Server
Agent Memory Server
Stop re-explaining your project every session — and catch the ten ways a memory lies.
The job: make your coding agent remember your project between sessions, and be able to tell whether that memory is actually working.
The first half is easy. The second half is where people lose months.
Start by not buying anything
Your agent probably already has a memory, turned on, that you have never looked at. This package opens by telling you how to find it, how to make it good, and — plainly — when to stop there. A small project living in one repo on one machine does not need what comes after page one, and the fastest way to end up with a memory you cannot trust is to build a second one you did not need.
Then it names the three walls where the built-in one runs out, because those are the only honest reasons to keep reading: it stays on one machine, it cannot search the detail behind an entry, and only the first slice of its index is loaded into each session.
Why the naive version fails
Set up a store, tell the agent to use it, done. That works for about a month.
What breaks it is that a broken memory does not throw errors — it answers. It keeps returning something, so every check stays green while the agent works from a fact that is stale, wrong, or was never saved at all. A write reports success and stores nothing, because a quiet command hid the rejection. A reply shows the field you set, because it was built from your request rather than read back from the database. A search comes back empty and you assume storage is broken, when the words simply did not line up. A search comes back full and you assume the topic is covered, when one short word happened to match.
Ten of those are written up here, each with the check that catches it. They came from running memory systems in anger, and one of them came from the demo run on this page.
What's on the tag
A memory your agent can use today — one plain Python file, no install, no account, no server, no monthly bill. A self-test where two of the five checks have to come back negative, so you can watch the checking work instead of trusting it. The editorial policy that keeps a store worth searching: the six moments worth storing, the four things never to store, and why anything still in progress belongs in a file instead of a memory. A ten-minute monthly audit for what rots first. And, for when one machine stops being enough, the shared-server setup — the database shape, how meaning-based search actually works, and the two problems that only appear once two people are writing.
Why not a free directory download
The free guides are real and some are good. Almost all of them start by telling you to install something, which is the one step you should not take first.
This one is written the other way round: what you already have, when to leave it alone, and — the part nobody writes down — how to know whether any of it is working. Every claim in it was run. An earlier draft went to a mid-tier model with a real project and came back with four defects, including one place the package overstated what its own search could do. Those were fixed before this shipped, and the field report on this page is the run that came after, kept whole, including the search that returned a false positive. Field-tested, documented, issued as-is.
FIELD REPORT real output, not a promise
Setup: a mid-tier model, given only this package and a small project — three months of plain working notes for an invoicing side-project (anonymised) — and told to set up a memory, load what belonged in it, and prove recall works when questions are asked in different words than the notes used. Output below is what the run actually produced.
The store, and its selftest. Two of the five checks have to come back negative, which is the point — a check that has never failed has not been shown able to fail.
$ python3 memory.py selftest
stored #1 [note] selftest canary alpha
[1] stored entry is findable by a phrase from its BODY: PASS
[2] a query for absent text returns nothing: PASS
[3] an EDIT reindexes (new text findable): PASS
[4] ...and the old text stops matching: PASS
stored #2 [note] selftest canary beta
superseded #1 -> #2
old entry still searchable: no (correct)
[5] a superseded entry drops out of search: PASS
ALL CHECKS PASS
What it loaded from three months of notes — summaries written as the question each one answers, which is what the retrieval actually matches on:
$ python3 memory.py rules
[rule] #3 Why can a Lantern deploy pass every check and still leave the old code running on the live site?
[rule] #7 Should invoice totals ever be formatted for display in the browser instead of on the server?
[rule] #8 Where does the Lantern staging database connection string live, and is it ever OK to drop it into a chat message?
[fact] #4 Why did Lantern's refund emails silently stop going out with no errors anywhere?
[fact] #5 Why is Lantern's data stored in Postgres instead of a single local file like SQLite?
[fact] #6 Does Lantern sell a yearly subscription, or only month-to-month?
Note the secret: it stored where the staging credential lives and that it must never be pasted into chat — never the value. That is the package's rule, applied without being asked.
Recall, asked in words the notes never used. The run confirmed with grep that its
anchor words appear nowhere in the source notes before searching:
| Question asked | Top result | Right one? |
|---|---|---|
| "why does production still serve a stale version even though monitoring reports everything healthy" | #3, the deploy-rebuild rule | yes, ranked first |
| "why would a vendor integration silently go quiet with zero errors logged anywhere" | #4, the refund-webhook fact | yes, ranked first |
| "if this project ever goes back to just one laptop and one developer, is this decision worth reconsidering" | #5, the Postgres choice | yes, ranked first |
| "who is allowed to decide how money looks on an invoice, the frontend or the backend" | #7, the currency rule | yes, ranked first |
The part that did not go perfectly, kept in. Asked to prove an empty result was still possible, the first attempt matched something anyway:
$ python3 memory.py search "should we migrate the API to GraphQL and run it on Kubernetes"
#3 [rule] Why can a Lantern deploy pass every check and still leave the old code running on the live site?
Nothing about Kubernetes was ever stored. run is a prefix of running in that entry, so the
search stretched to reach it. A genuinely unrelated query then returned nothing:
$ python3 memory.py search "GraphQL Kubernetes autoscaling helm chart"
no matches — try a distinctive phrase from the entry itself before concluding it was never stored
That false positive is now failure #10 in the package — a result came back, so the topic must be covered. It was found by this run and written up rather than trimmed out, because it is exactly the genre of quiet wrongness the package exists to catch.
The judgement call it made unprompted. One note read Status: v2 listing submitted, waiting on review. It refused to store it:
This is the exact anti-pattern the skill names twice: point-in-time status, and pending work. It's a month-plus old now with three more entries after it, so nobody can tell from the note alone whether it's still true — which is precisely the skill's argument for why status doesn't belong in memory at all. It belongs in a file that names the current state, not in a store that answers questions by association.
The audit:
$ python3 memory.py audit
live entries: 6
fact 3
rule 3
auto-loaded summary bytes: 535 (keep well under your agent's context budget)
no expired entries still live
standing rules: 3 — this tier is a BUDGET; status does not belong in it
What this run changed in the package. An earlier run against an earlier draft found four real defects, all fixed before this one: the search demanded every word of a question be present, so a full sentence returned nothing; a claim that the local store fixes meaning-based search, which it does not and now says so plainly; an id-reuse hazard that could point a correction at an unrelated memory; and install instructions that assumed a home-directory setup. The package you get is the one that survived both runs.
SERVICE RECORD living gear — updated as the factory learns
v1.0.0 — 2026-08-27
First issue. Ported from an internal memory system that has run daily across many projects, generalized so the buyer owns everything and nothing points at someone else's server.
Two things were checked rather than assumed before shipping. The vendor's current documentation was read to confirm what coding agents now give you for free — they ship default-on memory, so the package opens by telling you to use that first and naming the three points where it runs out, instead of selling you a replacement you may not need.
And the package was run end to end by a mid-tier model against a real project twice. The first run found four defects: search demanded every word of a question be present, so full sentences returned nothing; a claim that the local store fixes meaning-based search, which it does not; an id-reuse hazard that could point a correction at an unrelated memory; and install steps that assumed a home directory. All four fixed. The second run found a tenth failure mode — a search that returns a false positive because one short word prefix-matched — which is now documented rather than trimmed out of the field report.
Every update ships free to owners — your locker always serves the latest version.
QUESTIONS
My agent already has memory. Do I need this?›
Maybe not, and the package says so on its first page. Claude Code turns on a memory of its own by default, and for a small project on one machine that is the right answer — the package shows you how to check what you already have and how to make it good, for free. It tells you the three exact points where the built-in one runs out: it stays on one machine, it cannot search the detail behind an entry, and only the first part of its index gets loaded. Buy this if you have hit one of those or want to stop guessing whether your memory works.
Does it cost anything to run?›
The memory in this package costs nothing. It is ordinary Python and a database file that ships with your computer — no account, no key, no server, no monthly bill. The shared-across-machines setup at the end does cost whatever a small server and an embedding service charge, which is why the package tells you not to build it until you actually need it.
Will it work with something other than Claude Code?›
The method and the checks are plain markdown and work anywhere. The memory tool is a Python script your agent runs, so it needs an agent that can run commands on your machine — Claude Code or Codex. On claude.ai you get the method, the editorial policy and the failure catalogue, but not the store.
What makes this different from the free guides?›
Most of them tell you to install something. This starts by telling you what you already have and when to leave it alone. Then it covers the part nobody writes down: how to tell whether your memory is actually working. A memory that breaks does not throw an error — it keeps answering, which is why people trust a broken one for months. The ten failures in here are each written up with the check that catches them, and the package's own tool ships a self-test whose checks have to fail on purpose before you trust them.