{"_id":"@anareyna/ai-memory","_rev":"2-d3c1be66e5cbf1f695e6dae8af7f5116","name":"@anareyna/ai-memory","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@anareyna/ai-memory","version":"0.1.0","keywords":["ai-memory","claude-code","cursor","copilot","codex","aider","agents-md","memory-bank","session-continuity"],"license":"MIT","_id":"@anareyna/ai-memory@0.1.0","maintainers":[{"name":"anareyna","email":"anareymej@gmail.com"}],"homepage":"https://github.com/anareyna/ai-memory#readme","bugs":{"url":"https://github.com/anareyna/ai-memory/issues"},"bin":{"ai-memory":"bin/ai-memory.js"},"dist":{"shasum":"3eeeb2afe08a984ccd6bc84861892b74f73afe3e","tarball":"https://registry.npmjs.org/@anareyna/ai-memory/-/ai-memory-0.1.0.tgz","fileCount":23,"integrity":"sha512-acI0IrpN9dNVaGRmRcZypCCBHqJ73HcSqt/KjW+9OxvR+VnbY2wGFT51t1/6PAE7SHcozvleGdbjgdSWIPp/yQ==","signatures":[{"sig":"MEQCIChA/NdjuuOMNL0+qhGBCdoepQZtpfHZeMlBZH4ZVak7AiB0wJaVFHCvL6mP37JcgirRIZFO3g6f41jU2ONhLLCN7w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":61274},"type":"module","engines":{"node":">=20"},"gitHead":"68dc4f1aad40c68ac75ee5087e0c03e416ee32a0","scripts":{"test":"node --test lib/*.test.js","ai-memory":"node bin/ai-memory.js"},"_npmUser":{"name":"anareyna","email":"anareymej@gmail.com"},"repository":{"url":"git+https://github.com/anareyna/ai-memory.git","type":"git"},"_npmVersion":"11.12.1","description":"Portable memory pack for AI coding agents: session continuity across Claude Code, Cursor, Copilot, Codex, Aider.","directories":{},"_nodeVersion":"25.9.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ai-memory_0.1.0_1784057622311_0.9897911132387716","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@anareyna/ai-memory","version":"0.2.0","publishConfig":{"access":"public"},"description":"Session memory for AI coding agents as plain markdown: one install per machine, works in every repo, follows you across tools.","type":"module","bin":{"ai-memory":"bin/ai-memory.js"},"engines":{"node":">=20"},"scripts":{"ai-memory":"node bin/ai-memory.js","test":"node --test lib/*.test.js"},"keywords":["ai-memory","claude-code","cursor","copilot","codex","aider","agents-md","memory-bank","session-continuity"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/anareyna/ai-memory.git"},"homepage":"https://github.com/anareyna/ai-memory#readme","bugs":{"url":"https://github.com/anareyna/ai-memory/issues"},"gitHead":"da95aa6b8a178653d0d6b085cbe5235cf6908ef6","_id":"@anareyna/ai-memory@0.2.0","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-+domZs5PeHQAqUUe6uAhKtZ2uDKXO527gldcz3OvYDJ3EJu8hVIPsndUO7oVFO/ileHfgqD4yCKegfiZTgFNbw==","shasum":"946d646d6277b72e6d40b745cd9415a9b258efac","tarball":"https://registry.npmjs.org/@anareyna/ai-memory/-/ai-memory-0.2.0.tgz","fileCount":23,"unpackedSize":61370,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEykShbX3EFLkKHCew1fKEP6z27HejOa0lfGd3vRpfIqAiBKM6nCwQL+3ZpMnnuabOUhu+XDuE8Zn5AgBd0oxHNa7w=="}]},"_npmUser":{"name":"anareyna","email":"anareymej@gmail.com"},"directories":{},"maintainers":[{"name":"anareyna","email":"anareymej@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-memory_0.2.0_1787321636793_0.3431683759643327"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-14T19:33:42.170Z","modified":"2026-08-21T14:13:57.100Z","0.1.0":"2026-07-14T19:33:42.471Z","0.2.0":"2026-08-21T14:13:56.963Z"},"bugs":{"url":"https://github.com/anareyna/ai-memory/issues"},"license":"MIT","homepage":"https://github.com/anareyna/ai-memory#readme","keywords":["ai-memory","claude-code","cursor","copilot","codex","aider","agents-md","memory-bank","session-continuity"],"repository":{"type":"git","url":"git+https://github.com/anareyna/ai-memory.git"},"description":"Session memory for AI coding agents as plain markdown: one install per machine, works in every repo, follows you across tools.","maintainers":[{"name":"anareyna","email":"anareymej@gmail.com"}],"readme":"# ai-memory\n\nSession 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.\n\nHit 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.\n\n## Quick start\n\n```bash\nnpm install -g @anareyna/ai-memory\nai-memory init            # once per machine\ncd ~/some/repo\nai-memory track           # start keeping memory here\n```\n\nThat's it. Start a session and work normally. The agent reads the handoff when it starts and rewrites it as you go.\n\nYou 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.\n\nRequires Node 20+, and Claude Code (`claude` on PATH) for the automatic checkpoint.\n\n### Does my project need to be on GitHub?\n\nNo, but memory only follows you across machines if the repo has a remote:\n\n| Project | Memory key | Follows you |\n| --- | --- | --- |\n| Git repo with a remote | `github.com/you/thing` | yes, whatever path it's cloned to |\n| Git repo, no remote | `local/<folder-path>` | no |\n| No git at all | `local/<folder-path>` | no |\n\nBoth 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.\n\n## What goes where\n\nMemory holds **session state**. Everything durable belongs in the repo, where it survives a fresh clone and other people can read it.\n\n| Lives in memory (`~/.ai-memory/`) | Lives in the repo |\n| --- | --- |\n| `handoff.md`: what you're doing right now, and the next action | `AGENTS.md` / `CLAUDE.md`: project facts and conventions |\n| `paused/*.md`: topics you parked | `CONTEXT.md`: the domain glossary |\n| `decisions.md`: private reasoning you wouldn't commit | `docs/adr/`: durable decisions |\n| `~/.ai-memory/memory/`: facts about you, across all projects | the issue tracker: what's still to do |\n\nThe 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`.\n\nFull protocol for agents: [`rules/agent.md`](./rules/agent.md).\n\n## Commands\n\n| Command | What it does |\n| --- | --- |\n| `ai-memory init` | Per-machine setup. Scaffolds `~/.ai-memory/`, installs two Claude Code hooks, writes the pointer into your user-level agent files |\n| `ai-memory track` | Starts keeping memory for the current repo. Touches no repo file |\n| `ai-memory path` | Prints the memory dir for the current repo |\n| `ai-memory resume` | Prints the handoff. The SessionStart hook calls this |\n| `ai-memory checkpoint` | Rewrites `handoff.md` from the recent transcript. The Stop hook calls this |\n| `ai-memory pause` / `unpause` | Stops or resumes checkpointing this repo. Files stay readable either way |\n| `ai-memory uninstall` | Removes the hooks and the pointer blocks. Your data stays |\n\n## How it works\n\n**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.\n\n**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`.\n\n**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.\n\n```text\n~/.ai-memory/\n├── rules/agent.md                        # how agents use the memory\n├── memory/                               # facts about you, all projects\n└── projects/github.com/you/your-repo/\n    └── memory/\n        ├── handoff.md                    # live handoff\n        ├── paused/                       # parked topics\n        ├── decisions.md                  # private decisions\n        └── project.md                    # foundation, if the repo has none\n```\n\n## Everyday use\n\n**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.\n\n**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.\n\n**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:\n\n```bash\nmv ~/.ai-memory ~/dotfiles/.ai-memory && ln -s ~/dotfiles/.ai-memory ~/.ai-memory\n```\n\n## Uninstall\n\n```bash\nai-memory uninstall                    # hooks and pointer blocks\nnpm uninstall -g @anareyna/ai-memory   # or `npm unlink -g` for a linked checkout\n```\n\nIn 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`.\n\nVersions before 0.2.0 also injected that block into repo files. Delete any leftovers by hand.\n\n## Upgrading from 0.1.x\n\n0.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.\n\n## Known limitations\n\n- **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.\n- **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).\n- **LLM transport.** `checkpoint` shells out to `claude -p --model haiku`, reusing your Claude Code subscription. `--model=` overrides it. An SDK adapter is planned.\n- **\"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.\n\n## Development\n\n```bash\ngit clone https://github.com/anareyna/ai-memory.git\ncd ai-memory && npm link      # puts `ai-memory` on your PATH from this checkout\nnpm test\n```\n\nThis repo holds the pack template without the leading dot, so it's browsable. `init` and `track` copy from `rules/`, `memory/` and `blocks/`.\n\n```text\nbin/ai-memory.js         # CLI entrypoint\nlib/\n  project-key.js         # git remote → project key\n  resume.js              # SessionStart driver: prints the handoff\n  checkpoint.js          # Stop driver: rewrites handoff.md\n  transcript.js          # transcript discovery + parsing\n  user-blocks.js         # the pointer block in user-level files\n  handoff.js             # handoff/paused paths, incl. 0.1.x renames\n  init.js                # per-machine setup\n  track.js               # per-repo seeding\n  pause.js               # per-project on/off switch\n  path.js                # resolve and print the memory dir\n  uninstall.js           # remove hooks and blocks\n  pack-paths.js          # locate shipped templates\n  version.js             # version + git sha\nrules/agent.md           # the protocol agents follow\nmemory/                  # seed templates for a project's memory dir\nblocks/user-block.md     # the pointer `init` writes\ndocs/adr/                # decisions about this project\n```\n","readmeFilename":"README.md"}