A skill for Claude Code and Codex · v0.4.0
Your agent forgets. Its memory doesn't have to.
Long-Term Memory for AI gives coding agents a persistent memory that lives in a local SQLite file inside each project. A new chat window, with no context at all, starts from what was decided, what is pending and what happened, instead of rebuilding it from old conversations or scattered notes.
The problem
Agents are good inside one conversation and forgetful across them.
Every chat starts blank
Yesterday's decisions, the reasons behind them and the open questions are gone when you open a new window.
Compaction loses detail
Long sessions get summarized; the exact words, dates and who said what are the first casualties.
Markdown notes drift
Notes files grow, contradict themselves and cannot answer "how many", "since when" or "what changed".
Nobody can audit it
When an agent "remembers" something wrong, there is no source, no author and no history to check.
How it works
Three pieces: a skill that teaches the agent the protocol, a helper
(memory.py) that is the only way in and out, and one SQLite file per project in
.memory/.
Session starts
A hook injects the brief: owner, project, decisions in force, conventions, open questions, lessons, pending actions, latest records.
You work as usual
You talk to the agent in your language. When it needs history, it searches the memory instead of guessing.
The agent records
Decisions, answers, lessons, facts and events go in through the helper, with your literal words as evidence and the actor behind them.
Next session, any agent
Claude Code or Codex, today or in a year, start from the same memory, with every earlier state still readable.
A generic model, no domain tables
Everything is stored as entities (a person, a module, a case, a chapter), facts over time (valid from, valid to), events (a decision, a delivery, a work session) with attributes and links, and observations (readings from sensors or systems). The same structure has been exercised with a software project, a front desk with procedures that change while in operation, a hotel, lot sales, a supply chain and an author revising five books.
Nothing is ever lost
The memory is append-only, enforced by database triggers. A wrong fact is retracted with a reason, an outdated one is closed, a mistaken event is voided, a renamed thing keeps its old name, and a retired one keeps its history. You can ask what the memory looked like on any past date.
What it remembers
| Kind | Example |
|---|---|
| Decisions and their reasons | "Use one database per project — because memories must never leak between projects." |
| Conventions and preferences | "Internal text in English; answer in the user's language." |
| Open questions and answers | A question raised in March and the answer that closed it in May. |
| Lessons | "Run the tests on a clean interpreter: the default one hid a portability bug." |
| People, roles and actors | Who owns what, who holds a role since when, which system or sensor produced a record. |
| Pending actions and requests | A review waiting on the editor; a comment waiting on the author until it is resolved. |
| Facts over time | A status, an owner, a price — each with when it started and ended. |
| Processes and documents | Versioned workflows with roles and exceptions; texts versioned paragraph by paragraph. |
How it helps
Cold starts that work
A fresh window answers "what did we decide about X and why?" from stored records, not from a guess.
Accountable answers
Every record carries its source text and its actor. The agent separates retrieved facts, absences and its own inferences.
Questions without SQL
Totals, rankings and lists (aggregate, list), derived states, saved recipes, full-text recall and --as-of for any past date.
Same memory, two agents
Claude Code and Codex read and write the same file through the same helper.
Private by design
A local file, excluded from Git, no network, no service, no account. Nothing to sign up for.
Safe to upgrade
Schema changes ship as migrations: additive ones apply on open, transformative ones back up first, and every change is recorded.
Agents don't decide for you
Decisions, conventions, retractions and voids must come from a person. What the agent notices on its own is labeled as its observation.
Proven at scale
Tested with ~358,000 events, 1 million links and 1.3 million attributes in a 1.5 GB memory: selective queries in 70–190 ms, full aggregations in about 3 s.
Limitations
Version 0.4.0 is useful today, and these are its honest edges.
One machine, one project
The memory is a local file. There is no sync, no server and no sharing between teammates or computers. It does not reach claude.ai in the browser.
It is as good as what gets recorded
The agent decides what to store by following the skill. It can miss things or record them imperfectly; evidence and history make that visible and fixable, not impossible.
Nothing can be erased
Append-only means a sensitive value cannot be deleted through the helper; it can only be corrected or retracted. Do not store secrets or data you may be required to erase.
Not encrypted
Anyone who can read the project folder can read the memory file. Protect it like the rest of your source tree.
Keyword search, not semantic
recall uses SQLite full-text search (with singular/plural matching), not embeddings. Synonyms are found only if the words appear.
It costs some context
The brief is injected at every session start: the latest 8 items per section, typically a few thousand tokens. High-volume event types (imports, readings) are summarized in one line per type. A one-line reminder is added to each message.
Built for a few writers
SQLite handles a few agents writing at once (they wait for each other). It is not a multi-user database server.
Early version
Commands and the schema may still evolve. Upgrades migrate existing memories, and a newer memory opened by an older helper becomes read-only rather than damaged.
What adding the skill implies
Before you install it, here is exactly what changes on your machine and in your projects.
| What | Where | Details |
|---|---|---|
| The skill | ~/.claude/skills/project-memory/ or ~/.codex/skills/… | SKILL.md plus scripts/ (helper, package, migrations). Copied by the installer; reinstall to update. |
| The memory | <project>/.memory/memory.sqlite | Created on the first chat after you give your name and key. Comes with its own .gitignore. |
| Backups | .memory/backups/ or a folder you choose | Made by backup and before transformative migrations. Your responsibility to keep elsewhere too. |
| Hooks (Claude Code) | <project>/.claude/settings.json | Session start runs brief; each message runs reminder. Both always succeed and never block. |
| Instructions | CLAUDE.md or AGENTS.md | A short paragraph telling the agent to read the memory first and not to use Markdown files as memory. |
| Commands the agent runs | Your shell | python …/memory.py <command>. Your agent may ask permission for each; you can allow the helper command in its settings. |
| Network | None | The helper makes no network calls. It reads and writes one file. |
Your part
- Give the agent your name and a key once (it never invents them).
- Say when something is a decision, and why. The agent records it as yours.
- Back up the memory now and then (
backup); the brief shows the date of the last one. - Reinstall the skill when you update the repository.
Removing it
- Delete the skill folder, the hooks and the paragraph in
CLAUDE.md/AGENTS.md. - The memory file stays in
.memory/. It is yours: an ordinary SQLite database any tool can read.
Get started
Requirements: Python 3.9+ as python, and SQLite with FTS5 (included in the usual builds).
On Windows, named time zones need pip install tzdata; without it the system zone still works.
1 · Install the skill (once per machine)
git clone https://github.com/howware/long-term-memory-for-AI
cd long-term-memory-for-AI
python tools/install_skill.py --target ~/.claude/skills/project-memory
python tools/install_skill.py --target ~/.codex/skills/project-memory2 · Tell the project to use it
Add to the project's CLAUDE.md or AGENTS.md:
## Persistent memory
This project uses the `project-memory` skill. At the start of every
conversation run `brief` and follow the cold start before answering. The
SQLite memory is the source of truth: do not rebuild from the chat history
what can be looked up there, and do not use Markdown files as memory.3 · Add the hooks (Claude Code)
In <project>/.claude/settings.json, merged with what is there:
{
"hooks": {
"SessionStart": [{
"matcher": "startup|resume|clear|compact",
"hooks": [{"type": "command", "timeout": 30,
"command": "python ~/.claude/skills/project-memory/scripts/memory.py brief --format hook"}]
}],
"UserPromptSubmit": [{
"hooks": [{"type": "command", "timeout": 10,
"command": "python ~/.claude/skills/project-memory/scripts/memory.py reminder"}]
}]
}
}4 · Open a new chat
The agent notices there is no memory yet, asks for your name and a key such as person:ana, and creates it.
From then on every chat starts with the brief.
What it looks like
[project memory] Start-of-session brief: - Memory owner: Ana (person:ana) - Project: Billing service — invoices for the EU subsidiaries Decisions and agreements in force (3): · [decision:rounding] 2026-05-12 Round per line, not per invoice — why: the tax office checks line totals. Open questions (1): · [question:currency] 2026-06-02 Do credit notes keep the original exchange rate? Pending actions: 1 Last backup: 2026-06-20 you › why did we round per line? agent › From decision:rounding (May 12, by Ana): the tax office checks line totals. It is still in force; nothing has superseded it. you › credit notes keep the original rate. Remember that. agent › Recorded as your answer to question:currency, with your words as evidence. The question is now closed.
FAQ
Does any of my data leave my computer?
No. The helper has no network code. The agent itself still sends your conversation to its model provider as usual; the memory adds the brief and the results of the queries it runs to that conversation.
Can I edit or delete something?
You correct instead of deleting: close a fact that ended, retract one that was wrong (with a reason), void an event, rename or retire an entity. The history of every change stays readable.
Why SQLite and not Markdown or a vector store?
Because questions about a project are about facts, dates, owners, states and counts. SQLite answers them exactly, enforces append-only rules, needs no server and is a single portable file.
Can my team share one memory?
Not yet. The file is local and excluded from Git on purpose. Sharing would need sync and per-person access control, which this version does not provide.
Which agents does it work with?
Claude Code (with hooks) and Codex (through AGENTS.md). Any agent that can read a skill file and run shell commands can follow the same protocol.
What language does it use?
Everything stored is in English so any agent can read it; your literal words are kept as evidence in their original language, and the agent answers you in the language you are using.