\n
\nA queryable long-term memory for AI coding agents \u2014 the two-tier fix for the context-window wall.<\/p>\n
Companion essay: “Your AI’s Memory Breaks on Real Work. The Fix Is Fifty Years Old.”<\/p>\n
An AI coding agent’s default long-term memory is a stack of markdown files it loads into context at the start of every session. That works at ten files. It fails at a hundred and forty: everything competes for one finite context window, and past the edge the memory silently truncates \u2014 the agent quietly forgets, re-solves solved problems, contradicts last week’s decisions. You blame the model. The filing system is the problem.
\nIt’s an old problem. Loading a whole file and scanning it is the pre-relational habit that databases were invented, in 1970, to kill: store it structured, index it, fetch only the row you need.<\/p>\n
Tier 1 \u2014 an index, always loaded. One line per solved problem: a title and a pointer. Cheap to carry every session. It tells the agent what exists, never the detail. (INDEX.md, generated from tier 2 so it never drifts.)
\nTier 2 \u2014 a database, queried on demand. Every hard problem becomes a row in a plain SQLite file \u2014 problem, root cause, what worked, the gotcha, the artifacts. A thousand rows cost the agent nothing until it runs a query. When something smells familiar, it asks the table instead of rummaging through prose.
\nStop loading the library. Keep an index you can hold, and a database you can question.<\/p>\n
python3 memory.py init<\/p>\n
python3 memory.py add \\
\n –area db –title “SQLite can’t persist a view over an ATTACH-ed database” \\
\n –problem “CREATE VIEW over an attached db vanished on the next connection” \\
\n –root-cause “the view binds to the attach alias, not the file” \\
\n –solution “materialize into the main db, or re-ATTACH and re-create the view on open” \\
\n –gotcha “no error is raised \u2014 the view simply isn’t there next session” \\
\n –tags “sqlite,attach,view”<\/p>\n
python3 memory.py query “attach view disappears”
\npython3 memory.py get 1
\npython3 memory.py index # regenerate INDEX.md from the database
\nThe part that isn’t the database
\nThe tool alone is a trap. It earns its keep only with a habit and a little hygiene:<\/p>\n
Query before you rebuild. An agent’s reflex is to solve, not to look up. Make “search the memory first” a standing rule, or the database becomes dead weight.
\nKeep rows honest. Write them the day you solve the thing; delete them the day they turn out wrong. A stale row misleads worse than an empty table.
\nRetrieval has a ceiling. Full-text search (built in here, via FTS5) finds the words you match, not the row you meant. When you outgrow it, bolt semantic search \/ embeddings onto this same relational base \u2014 don’t start there.<\/p>\n
Point your agent’s project instructions at two rules:<\/p>\n
On a new hard problem, query first; act on a hit.
\nOn solving something novel, add a row, then index.<\/p>\n
The always-loaded INDEX.md primes the agent on what it already knows; the database holds the rest, for free.<\/p>\n
File
\nRole<\/p>\n
schema.sql
\nthe solutions table + an FTS5 full-text index kept in sync by triggers<\/p>\n
memory.py
\nstdlib-only CLI: init \/ add \/ query \/ get \/ list \/ index<\/p>\n
INDEX.md
\ntier-1 index, generated from the database (git-ignored)<\/p>\n
memory.db
\ntier-2 store \u2014 your data (git-ignored)<\/p>\n
No dependencies. Python 3 and its bundled sqlite3.<\/p>\n
Built in the open by Tom Adelstein. The pattern came out of a working session with Claude Code, Anthropic’s coding agent: I pitched the relational approach; the agent built, tested, and hardened this implementation. The human\u2013AI collaboration is the point \u2014 and, fittingly, the subject of the companion essay.<\/p>\n