ai-memory

Session memory for AI coding agents, as plain markdown at ~/.ai-memory/. One install per machine, works in every repo, and syncs across devices however you like.

Hit a token limit in Claude Code mid-refactor? Open Codex in the same repo, ask it to continue, and it picks up where Claude stopped. No database, no service, no vendor lock-in. Just cat-able files.

Quick start

npm install -g @anareyna/ai-memory
ai-memory init            # once per machine
cd ~/some/repo
ai-memory track           # start keeping memory here

That's it. Start a session and work normally. The agent reads the handoff when it starts and rewrites it as you go.

You can skip the last command: an agent that finds no memory for a project offers to start tracking it and carries on. It runs the same thing, you just say yes.

Requires Node 20+, and Claude Code (claude on PATH) for the automatic checkpoint.

Does my project need to be on GitHub?

No, but memory only follows you across machines if the repo has a remote:

| Project | Memory key | Follows you | | --- | --- | --- | | Git repo with a remote | github.com/you/thing | yes, whatever path it's cloned to | | Git repo, no remote | local/<folder-path> | no | | No git at all | local/<folder-path> | no |

Both work. The fallback keys on the folder path, so moving the folder loses the link. One thing to know: if you add a remote later, the key changes and the earlier memory is orphaned under the old local/ key. Move it by hand for now.

What goes where

Memory holds session state. Everything durable belongs in the repo, where it survives a fresh clone and other people can read it.

| Lives in memory (~/.ai-memory/) | Lives in the repo | | --- | --- | | handoff.md: what you're doing right now, and the next action | AGENTS.md / CLAUDE.md: project facts and conventions | | paused/*.md: topics you parked | CONTEXT.md: the domain glossary | | decisions.md: private reasoning you wouldn't commit | docs/adr/: durable decisions | | ~/.ai-memory/memory/: facts about you, across all projects | the issue tracker: what's still to do |

The test for a decision: would the repo's owner be fine reading this in a pull request? Yes, it's an ADR. No, it's decisions.md.

Full protocol for agents: rules/agent.md.

Commands

| Command | What it does | | --- | --- | | ai-memory init | Per-machine setup. Scaffolds ~/.ai-memory/, installs two Claude Code hooks, writes the pointer into your user-level agent files | | ai-memory track | Starts keeping memory for the current repo. Touches no repo file | | ai-memory path | Prints the memory dir for the current repo | | ai-memory resume | Prints the handoff. The SessionStart hook calls this | | ai-memory checkpoint | Rewrites handoff.md from the recent transcript. The Stop hook calls this | | ai-memory pause / unpause | Stops or resumes checkpointing this repo. Files stay readable either way | | ai-memory uninstall | Removes the hooks and the pointer blocks. Your data stays |

How it works

Keyed on the git remote. Memory lives at ~/.ai-memory/projects/<host>/<owner>/<repo>/memory/, so the same repo resolves to the same memory on every machine, whatever path it's cloned to. Agents run ai-memory path instead of computing slugs.

Two hooks, so continuity doesn't depend on the agent remembering. SessionStart runs ai-memory resume, which prints the handoff straight into the new session. Stop runs ai-memory checkpoint, which distills the recent transcript and rewrites handoff.md. Both no-op silently in repos that never ran track.

One pointer, in your files, not your repos. ai-memory init writes a short block into ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md, between <!-- ai-memory:start --> markers. That's how non-Claude tools find memory. No repo file is ever touched, so nothing collides with what your team or your skill packs write.

~/.ai-memory/
├── rules/agent.md                        # how agents use the memory
├── memory/                               # facts about you, all projects
└── projects/github.com/you/your-repo/
    └── memory/
        ├── handoff.md                    # live handoff
        ├── paused/                       # parked topics
        ├── decisions.md                  # private decisions
        └── project.md                    # foundation, if the repo has none

Everyday use

Paused topics. Say "let me check this PR" or "back to that auth idea" and the agent saves the current handoff.md to paused/<slug>.md, loads the other one, and confirms in a line. You never name or open a file.

Turning it off for one repo. ai-memory pause writes a .paused marker into that project's memory dir, so the Stop hook returns before reading any transcript. No LLM call, no cost. Your files stay readable and agents still use them; only the automatic refresh stops. ai-memory unpause reverses it. Since the marker lives in ~/.ai-memory/, it syncs with everything else instead of landing in a teammate's checkout.

Syncing across devices. ~/.ai-memory/ is a plain directory, so sync it however you already sync things: its own private git repo, your dotfiles, Dropbox, Syncthing, rsync. Nothing in the tool cares. The dotfiles version:

mv ~/.ai-memory ~/dotfiles/.ai-memory && ln -s ~/dotfiles/.ai-memory ~/.ai-memory

Uninstall

ai-memory uninstall                    # hooks and pointer blocks
npm uninstall -g @anareyna/ai-memory   # or `npm unlink -g` for a linked checkout

In that order: the hooks must go before the binary they fire. Everything outside the <!-- ai-memory:start --> markers is left alone, and ~/.ai-memory/ is never touched. Wipe it yourself with rm -rf ~/.ai-memory.

Versions before 0.2.0 also injected that block into repo files. Delete any leftovers by hand.

Upgrading from 0.1.x

0.2.0 is a clean break, with no automatic migration. Commands were renamed (bootstrap → track, disable/enable → pause/unpause), files were renamed (context.md → handoff.md, contexts/ → paused/, .disabled → .paused), and migrate is gone. Rename the files in ~/.ai-memory/projects/<key>/memory/ yourself, re-run ai-memory init, and delete by hand any blocks 0.1.x injected into repo files.

Known limitations

• Claude Code only for the hooks. Codex reads memory through the pointer block in ~/.codex/AGENTS.md, but gets no automatic checkpoint or handoff injection yet.
• Cursor and Aider need the pointer by hand. Neither keeps user-level instructions in a file init could write, so point them at ~/.ai-memory/rules/agent.md yourself (Cursor: Settings, then Rules).
• LLM transport. checkpoint shells out to claude -p --model haiku, reusing your Claude Code subscription. --model= overrides it. An SDK adapter is planned.
• "In flight" artifact. A checkpoint at the end of a completing turn can say "checkpoint in flight", because the LLM sees the transcript up to but not including its own reply. The next one corrects it.

Development

git clone https://github.com/anareyna/ai-memory.git
cd ai-memory && npm link      # puts `ai-memory` on your PATH from this checkout
npm test

This repo holds the pack template without the leading dot, so it's browsable. init and track copy from rules/, memory/ and blocks/.

bin/ai-memory.js         # CLI entrypoint
lib/
  project-key.js         # git remote → project key
  resume.js              # SessionStart driver: prints the handoff
  checkpoint.js          # Stop driver: rewrites handoff.md
  transcript.js          # transcript discovery + parsing
  user-blocks.js         # the pointer block in user-level files
  handoff.js             # handoff/paused paths, incl. 0.1.x renames
  init.js                # per-machine setup
  track.js               # per-repo seeding
  pause.js               # per-project on/off switch
  path.js                # resolve and print the memory dir
  uninstall.js           # remove hooks and blocks
  pack-paths.js          # locate shipped templates
  version.js             # version + git sha
rules/agent.md           # the protocol agents follow
memory/                  # seed templates for a project's memory dir
blocks/user-block.md     # the pointer `init` writes
docs/adr/                # decisions about this project