@vib795/agent-memory 0.1.0

package/HOWTO.md

@@ -0,0 +1,368 @@
+# How to use agent-memory
+
+**A 10-minute read that will save you a lot of 10-minute re-explanations.**
+
+You do not need to be a developer to follow this. If you can copy a line of text and
+press Enter, you can do all of it.
+
+---
+
+## 1. The problem, in one scene
+
+You spend forty minutes with an AI assistant working out why the checkout page is slow.
+You try three things. Two are dead ends. The third works, and you learn *why* — some
+cache setting nobody documented.
+
+The next morning you open a new chat.
+
+It knows nothing. Not the dead ends, not the fix, not the reason. So you explain it
+again, from the top, and pay for the privilege — because those forty minutes cost real
+requests out of your monthly allowance, and you are about to spend them twice.
+
+Your assistant has no long-term memory. Every conversation starts at zero.
+
+**agent-memory gives it one.** A small set of notes, stored as plain text files on your
+own machine, that any AI assistant on that machine can read — tomorrow, next month, from
+a completely different project folder.
+
+---
+
+## 2. What you actually get
+
+Three commands you type into the chat box. That is the whole interface.
+
+| You type | What happens |
+|---|---|
+| `/remember` | "Keep this." It writes down what was decided and why. |
+| `/recall` | "What do we already know?" It answers from your notes instead of guessing. |
+| `/handoff` | "Save my place." It bottles up the current work so another window can continue it. |
+
+The most important one is `/recall`, and here is the trick: **you usually will not type
+it.** Your assistant reads a one-line summary of everything in your memory at the start
+of every conversation, so when you ask a question your notes can answer, it goes and
+looks on its own.
+
+You are not managing a database. You are leaving notes for your future self, and
+somebody else does the filing.
+
+---
+
+## 3. Install it (about 60 seconds)
+
+You will need **Node.js version 22.5 or newer**. To check, open a terminal —
+on Windows that's **PowerShell**, on a Mac it's **Terminal** — and type:
+
+```bash
+node --version
+```
+
+If that prints something like `v22.5.0` or higher, you are set. If it prints an error or
+a smaller number, install Node from [nodejs.org](https://nodejs.org) first.
+
+Now run these two lines:
+
+```bash
+npm install -g @vib795/agent-memory
+agent-memory setup
+```
+
+**Both lines matter.** The first downloads it. The second installs it into every AI tool
+you have. Modern npm refuses to let a package run its own setup automatically — a
+sensible security default — so the second line is you giving permission, by hand.
+
+> No access to the npm registry at work? This works too, and needs nothing but GitHub:
+> ```bash
+> npm install -g https://github.com/vib795/agent-memory.git
+> agent-memory setup
+> ```
+
+### What just happened
+
+`setup` looked around your machine for AI tools, and installed itself into each one it
+found — in whatever format that particular tool reads:
+
+| If you have | It installs | Where |
+|---|---|---|
+| Claude Code | a skill | `~/.claude/skills/` |
+| Codex CLI | a skill | `~/.codex/skills/` |
+| VS Code, Insiders, Cursor, Windsurf | a prompt file | the editor's `prompts` folder |
+| GitHub Copilot agent skills | a skill | `~/.agents/skills/` |
+
+It prints exactly what it did. If your editor is not in that list, it will say so rather
+than silently skipping it.
+
+You should see something like:
+
+```
+Installed for 4 agents:
+  Agent skills (shared convention)
+    [link] /Users/you/.agents/skills/handoff
+    ...
+Store ready at /Users/you/.agents/memory (0 notes).
+```
+
+Zero notes is correct. It is a new notebook. You have not written in it yet.
+
+---
+
+## 4. Prove it works
+
+```bash
+agent-memory doctor
+```
+
+This is your one diagnostic. It checks the Node version, finds your tools, verifies the
+files are where they should be, and tells you plainly if something is wrong. Run it any
+time something feels off — it is designed to be the first thing you try, not the last.
+
+---
+
+## 5. Your first five minutes
+
+Do this once. It takes longer to read than to do.
+
+**Step one — open any AI assistant and teach it something.** Have a normal conversation
+about a real project. Make a decision. Then type:
+
+```
+/remember
+```
+
+It will pull out what was actually decided, strip anything that looks like a password or
+a key, and save it. You will see which notes it wrote.
+
+**Step two — close that conversation entirely.** Open a fresh one. Ideally in a
+different project folder, to prove the point.
+
+**Step three — ask about the thing you just decided.** Not `/recall`. Just ask, the way
+you would ask a colleague:
+
+> Why did we go with the queue instead of a cron job?
+
+If it comes back with your reasoning — including what you rejected and why — it is
+working. That is the whole product. Everything else is plumbing.
+
+---
+
+## 6. The three commands, in more detail
+
+### `/remember` — for things that stay true
+
+Use it when something is settled and would be annoying to work out twice:
+
+- **A decision**, and critically, *what you rejected and why.* "We chose X" ages badly.
+  "We chose X over Y because Y needs a native build step our laptops can't run" is still
+  useful in a year.
+- **A constraint** you cannot see in the code. "The security team will not approve any
+  new background service." No amount of reading the codebase reveals that.
+- **A convention** your team follows that isn't written down anywhere.
+- **How a system actually works**, once you have finally understood it.
+
+You can also point it at something specific:
+
+```
+/remember the retry policy on the orders webhook
+```
+
+**Don't bother remembering** anything the code already says. If someone can find it by
+opening a file, it does not need a note. Notes are for what lives in people's heads.
+
+### `/handoff` — for moving work between windows
+
+This one is not a chat summary. Summaries read nicely and still leave the next
+conversation asking questions.
+
+`/handoff` captures **working state**: the decisions with their reasoning, the
+approaches you already tried that failed, what you were about to do next and what is
+blocking it, which files you touched, and the exact `file:line` spots that matter.
+
+Type `/handoff` and it hands you back a single line to paste elsewhere:
+
+```
+Read C:\Users\you\.agents\handoffs\fix-checkout-latency.md and continue this work.
+Follow the Next action.
+```
+
+Paste that into any other window, in any project, and it picks up where you stopped.
+
+Run `/handoff` again later on the same work and it updates the same file rather than
+creating a second one — it recognises the thread even if you have started calling it
+something slightly different. One previous version is kept, just in case.
+
+**Bonus:** `/handoff` also does `/remember`'s job in the same breath, at no extra cost.
+More on why that matters in a moment.
+
+### `/recall` — for getting the answer back
+
+Mostly automatic, as described above. Type it explicitly when you want to see
+everything the memory holds on a subject, or when you suspect it knows something and
+didn't volunteer it.
+
+---
+
+## 7. Notes for your specific tool
+
+### Claude Code
+
+Nothing to do. The three commands appear as skills in both the terminal version and
+the VS Code extension. Type `/recall` and you will see them.
+
+### Codex CLI
+
+Nothing to do. Codex uses the same skill format, and `setup` installs into
+`$CODEX_HOME/skills` (usually `~/.codex/skills`). Restart Codex once after installing so
+it picks up the new skills.
+
+### GitHub Copilot in VS Code (the chat sidebar)
+
+This is the one most people use, so read this bit.
+
+`setup` writes **prompt files** into VS Code's user folder. Open Copilot chat, type `/`,
+and you should see `recall`, `remember` and `handoff` in the dropdown.
+
+**If you don't see them:**
+
+1. Restart VS Code. New prompt files are picked up on start.
+2. Check that prompt files are switched on. Open Settings, search for `chat.promptFiles`,
+   and make sure it is enabled. On older VS Code builds this is off by default.
+3. Run `agent-memory doctor` to confirm the files landed in the folder VS Code is
+   actually reading.
+
+**One thing to remember:** when you upgrade the package, re-run `agent-memory setup`.
+Prompt files are copies, not links, so they do not update themselves.
+
+### GitHub Copilot CLI
+
+**Not supported, deliberately.** It is detected, and `setup` tells you it is skipping it.
+
+Copilot CLI has no user-wide place to put instructions, so there is nothing to install
+into. Writing a file into its config folder on a hunch is how you ship something that
+does nothing while claiming to work.
+
+If you want memory in a specific repository with Copilot CLI, add the instructions to
+that repo's `.github/copilot-instructions.md` by hand. That works, but you have to do it
+per repository — which is the exact problem this package exists to solve everywhere
+else.
+
+---
+
+## 8. Does this cost me extra requests?
+
+Almost never, and the reason is worth knowing.
+
+Your allowance is charged **per message you send**, not per action the assistant takes
+while answering. So when `/handoff` saves your working state, it does it *inside* a turn
+you already paid for. It is free.
+
+`/remember` costs one request, because you sent one message. That is the only charge,
+and you chose to spend it.
+
+The savings run the other way. Every question your memory answers is a conversation you
+did not have to have twice.
+
+---
+
+## 9. What it will not do
+
+Being clear about this now saves disappointment later.
+
+- **It does not save things on its own.** You invoke it, or `/handoff` does. Nothing
+  runs in the background. This is a deliberate choice: memory that fills itself up
+  becomes memory you cannot trust.
+- **It does not sync between machines.** Your notes live on the computer that wrote
+  them. There is no server, no account, no cloud.
+- **It is not shared with your team.** One person, one machine, for now.
+
+---
+
+## 10. Where your things live, and who can see them
+
+Everything is in one folder:
+
+```
+~/.agents/          (on Windows: C:\Users\you\.agents\)
+  handoffs/         your saved working states
+  memory/notes/     your notes, as plain markdown files
+```
+
+Three things worth knowing:
+
+**Nothing leaves your machine.** No server, no account, no telemetry, no background
+process, nothing to get approved by IT. It is a small program that writes text files.
+
+**Passwords and keys never get written down.** Anything that looks like a token, a key,
+a connection string or a session cookie is replaced with `<redacted>` *before* anything
+is saved — not to a note, not to a temporary file. There is no way to switch this off,
+which is the point.
+
+**Your notes are just files.** Open them in any text editor. Read them, edit them, put
+them in Dropbox, print them out. If you uninstall this tool tomorrow, every note stays
+exactly where it is and remains perfectly readable. You are not locked in — there is
+nothing to be locked into.
+
+**Nothing is ever deleted.** Notes that get replaced or go stale move to an `archive`
+folder rather than disappearing.
+
+---
+
+## 11. When something is wrong
+
+**Start here, always:**
+
+```bash
+agent-memory doctor
+```
+
+| Symptom | What's going on |
+|---|---|
+| `/recall` doesn't appear in VS Code | Restart VS Code, then check the `chat.promptFiles` setting. See §7. |
+| The commands vanished after an upgrade | Re-run `agent-memory setup`. |
+| It answers with outdated information | Notes show their age. Anything captured long ago is flagged `verify before trusting` — that flag is doing its job, and you should. |
+| `doctor` reports broken links | Usually means Node moved. Re-run `agent-memory setup`. |
+| Something is badly confused | `agent-memory compact` tidies and rebuilds. Your notes are the source of truth, so this cannot lose anything. |
+
+---
+
+## 12. Removing it
+
+**The order matters, and npm will not do it for you:**
+
+```bash
+agent-memory uninstall          # first — this removes the commands from your tools
+npm uninstall -g @vib795/agent-memory
+```
+
+If you do it the other way round, npm deletes the program *including the part that
+cleans up*, and your AI tools are left with commands that point at nothing. If that has
+already happened, install it again and run `agent-memory setup` — that clears the dead
+commands and puts working ones back.
+
+Your notes are untouched either way. They are at `~/.agents/memory`, they are plain
+text, and deleting them is your decision to make, not the uninstaller's.
+
+---
+
+## Cheat sheet
+
+```bash
+node --version                          # must be 22.5+
+npm install -g @vib795/agent-memory     # 1. download
+agent-memory setup                      # 2. install into your AI tools
+agent-memory doctor                     # is everything OK?
+```
+
+Then, in any AI chat:
+
+```
+/remember      keep what we just worked out
+/handoff       save my place so another window can continue
+/recall        what do we already know about this?
+```
+
+And most of the time, just ask your question normally and let it find the answer itself.
+
+---
+
+*More detail, and the reasoning behind the design, is in the
+[README](README.md). Problems and ideas go in
+[issues](https://github.com/vib795/agent-memory/issues).*

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Utkarsh Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,302 @@
+# agent-memory
+
+[![test](https://github.com/vib795/agent-memory/actions/workflows/test.yml/badge.svg)](https://github.com/vib795/agent-memory/actions/workflows/test.yml)
+[![node](https://img.shields.io/badge/node-%3E%3D22.5-brightgreen)](https://nodejs.org)
+[![dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)](package.json)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Give **GitHub Copilot** and **Claude Code** a memory that outlives the window, the
+repository, and the week — using nothing an IT security review would need to approve.
+
+Three user-level Agent Skills over one local store:
+
+| Skill | What it does |
+|---|---|
+| `/handoff` | Writes a portable working-state file so another window can pick up this thread |
+| `/remember` | Captures durable knowledge into a cross-repo graph |
+| `/recall` | Answers from that graph before deriving anything again |
+
+**New here? Read the [HOW-TO](HOWTO.md)** — install, first five minutes, and the
+per-tool notes for Claude Code, Codex and Copilot, written for people who do not
+want to read the rest of this file.
+
+## Why this exists
+
+Moving context between windows today means copy-pasting the chat, retyping from
+memory, and re-explaining. That costs 10 to 15 minutes per switch and burns premium
+request credits re-deriving conclusions already reached.
+
+Nothing in the platform closes the gap:
+
+| Mechanism | Why it doesn't help |
+|---|---|
+| Copilot Memory | Repo-scoped by design. Facts "can only be used in operations on the same repository", and expire after 28 days |
+| `/fork` | Copies a conversation inside one workspace |
+| Prompt files in `.github/prompts/` | Workspace-scoped, so every repo needs its own copy |
+| Third-party memory plugins | Blocked in many managed environments |
+
+## Zero runtime dependencies
+
+`node:sqlite` has shipped inside Node core since 22.5, so the graph index needs no
+package, no service, and no network. `npm ls -g --depth 0` shows nothing under it.
+On a locked-down desktop that is the difference between "a Node script" and "a new
+database", which is the entire argument you will have to make to get this approved.
+
+- **Markdown is the source of truth.** `index.db` is a disposable cache; delete it
+  and `agent-memory index` rebuilds it byte-identically.
+- **Nothing leaves the machine.** No daemon, no scheduled task, no telemetry.
+- **Uninstalling leaves readable notes behind.** The store is plain markdown and
+  stays useful with no tooling at all.
+
+## The memory graph
+
+Notes live at `%USERPROFILE%\.agents\memory\notes\<type>\<id>.md`, outside every
+repository — that is what makes a note written in one project readable from another.
+
+```yaml
+id: auth-service
+type: system            # system | decision | convention | constraint
+title: Auth uses server sessions
+scope: repo             # repo | global
+confidence: observed    # observed | inferred
+captured_sha: a1b2c3d   # repo HEAD at capture; drives the staleness signal
+repos: [orders-api]
+edges:
+  - rel: depends-on     # depends-on | applies-to | supersedes | contradicts | evidence-for
+    dst: postgres-primary
+```
+
+Traversal is a SQLite recursive CTE. There is no graph layer on top of SQLite; the
+recursive CTE *is* the graph engine, and `UNION` plus a depth bound is what keeps a
+`contradicts` cycle from recursing forever.
+
+### What keeps it honest
+
+- **Staleness is visible at the moment of use.** Every note records the repo HEAD it
+  was captured at. On recall, `get` prints `captured 47 commits ago — verify before
+  trusting`. A note that quietly rots is worse than no note.
+- **Redaction is fail-closed.** Keys, tokens, connection strings, private keys,
+  session cookies, internal hosts and foreign email addresses are replaced before any
+  byte reaches disk — not to a note, not to a temp file, not to the index.
+- **Truncation is never silent.** Whenever the tree or the retrieval budget drops
+  something, the omitted ids are printed. Silent truncation reads as full coverage.
+- **Constraints are never dropped.** At any cap, in either tier. A constraint is what
+  stops an agent burning a retry loop on an approach that was never going to ship.
+
+## CLI
+
+```
+agent-memory init [--skills "<p1>,<p2>"]   create the store, register skill files
+agent-memory index                         rebuild index.db from notes/
+agent-memory tree [--repo <name>] [--all]  routing map, scoped to a repo
+agent-memory get <id> [--depth N]          a note plus its neighborhood
+                     [--budget N] [--include-archived]
+agent-memory search <terms> [--limit N]    full-text fallback when the tree misses
+agent-memory write --from-json <file>      validated upsert; used by the skills
+agent-memory compact                       dedup, decay, reindex, regenerate
+agent-memory doctor                        preflight and health report
+```
+
+Every command takes `--json`. Every cap lives in `config.json` and is tunable.
+
+## Install
+
+Two commands, and the second one is not optional:
+
+```bash
+npm install -g @vib795/agent-memory
+agent-memory setup
+```
+
+Straight from git works too, and needs no registry access:
+
+```bash
+npm install -g https://github.com/vib795/agent-memory.git
+agent-memory setup
+```
+
+`setup` probes for every agent on the machine and installs into each one it finds,
+in whatever format that tool reads. It then creates the store and generates the
+routing digest.
+
+| Detected | Installed as | Where |
+|---|---|---|
+| Agent skills (shared convention) | linked skill directory | `~/.agents/skills/<name>/` |
+| Claude Code, CLI and VS Code extension | linked skill directory | `~/.claude/skills/<name>/` |
+| Codex CLI | linked skill directory | `$CODEX_HOME/skills/<name>/` |
+| VS Code, Insiders, VSCodium, Cursor, Windsurf | prompt file | `<user data>/prompts/<name>.prompt.md` |
+| Copilot CLI | *detected, skipped* | it documents no user-global prompt directory; use `.github/copilot-instructions.md` per repo |
+
+Prompt files are what GitHub Copilot chat reads, and they appear as `/recall`,
+`/remember` and `/handoff` in the chat box. They are **generated from the same
+`SKILL.md` files** rather than maintained separately, so the two formats cannot
+drift, and `compact` regenerates the routing digest into both.
+
+`agent-memory doctor` lists what it detected, so an install that appears to do
+nothing tells you whether your editor was missed or simply ignored the files.
+
+**Why it is not automatic.** There is a `postinstall` hook that does exactly this,
+but current npm refuses to run package install scripts unless you opt in per
+package, and prints only a warning when it skips them. Managed environments go
+further and set `ignore-scripts=true` globally. Rather than pretend, the second
+command is documented as part of the install. If you would rather have it automatic:
+
+```bash
+npm install -g --allow-scripts=@vib795/agent-memory @vib795/agent-memory
+```
+
+Either way `agent-memory doctor` tells you where you stand; it reports
+`skills linked: none registered` when setup has not run.
+
+Windows uses directory junctions, which need neither admin rights nor Developer
+Mode. On a network-backed profile (FSLogix, roaming) junctions fail and the skills
+are copied instead — setup says which one you got, and copies need
+`agent-memory setup` re-run after each upgrade.
+
+### From a clone
+
+```bash
+./install.sh                                          # macOS / Linux
+powershell -ExecutionPolicy Bypass -File .\install.ps1 # Windows
+```
+
+Both are thin wrappers over `agent-memory setup`; the linking logic lives in
+`src/setup.js` so there is one implementation rather than three that drift.
+
+Note that `npm install -g .` from a clone *symlinks* rather than copies, so
+`compact` regenerates the description in your working tree and
+`skills/recall/SKILL.md` will show as modified. That is expected — the description
+is generated state, and the committed value is only a placeholder.
+
+Needs Node 22.5 or newer; `doctor` says so plainly if the version is too old, and
+`postinstall` refuses rather than failing your install.
+
+Run `npm test` for the suite (71 tests, no dependencies). CI runs it on Linux,
+macOS and Windows across Node 22 and 24, and separately installs the packed tarball
+and exercises it end to end on all three.
+
+## It is not a chat summary
+
+A transcript summary reads fine and still leaves the next agent asking questions.
+`/handoff` reconstructs **working state** instead:
+
+- **Decisions** with the *why* and what was rejected
+- **Constraints** that are invisible in the code
+- **Rejected approaches**, so the next agent stops re-deriving your dead ends
+- **Next action** and what's blocking it
+- **Uncommitted work** as a file list, never inline diffs
+- **Anchors** — the `file:line` references that matter
+- **Open questions** only you can answer
+
+## Use
+
+Two different jobs, and it is worth being clear about which is which.
+
+**Moving a thread between windows.** In window A:
+
+```
+/handoff
+```
+
+It prints a pickup line. In window B, any repo, paste it:
+
+```
+Read C:\Users\you\.agents\handoffs\migrate-orders-to-result-type.md and continue this work. Follow the Next action.
+```
+
+**Keeping what stays true.** `/handoff` also writes durable knowledge into the graph
+in the same request — same turn, no extra credit. Mid-session, when something worth
+keeping is established and you are not switching windows:
+
+```
+/remember
+/remember the retry policy on the orders webhook
+```
+
+And in any repo, later, ask a question that memory should already answer. The agent
+invokes `/recall` on its own, because the skill description tells it what is in
+there.
+
+## Where things live
+
+```
+%USERPROFILE%\.agents\        (Windows; ~/.agents/ on macOS and Linux)
+  handoffs/
+    index.md            one row per thread, kept small so lookup stays cheap
+    <thread-id>.md      current handoff
+    <thread-id>.prev.md exactly one prior version
+  memory/
+    notes/<type>/<id>.md  the source of truth, plain markdown
+    notes/archive/        superseded, merged and decayed notes; never deleted
+    index.db              disposable SQLite cache, rebuildable at any time
+    ROUTING.md            generated map of everything known
+    config.json           every cap in the design, tunable
+```
+
+Re-running `/handoff` on the same thread updates it in place and keeps one `.prev`
+backup. Threads are matched by judgment, not by string-comparing titles, so a title
+that drifts as the work progresses does not create a duplicate.
+
+## Design constraints it holds to
+
+- **Memory work costs no extra requests.** A premium request is charged per prompt,
+  not per tool call, so capture rides inside a turn you already paid for. Only
+  `/remember` costs a request, and only because you chose to spend it.
+- **Zero infrastructure.** Files and Node core. No daemon, no server, no scheduled
+  task, no network call, nothing for an IT policy to approve.
+- **Secrets never hit disk.** Tokens, keys, and connection strings become
+  `<redacted:kind>` before any byte is written — not to a note, not to a temp file,
+  not to the index. There is no bypass flag.
+- **Nothing is deleted.** Superseded, merged and decayed notes move to `archive/`
+  and stay reachable with `--include-archived`.
+- **Reversible.** `npm uninstall -g agent-memory` removes the links and leaves every
+  note in place, readable with nothing installed.
+
+## Status
+
+Capture is **explicit**. You invoke it, or `/handoff` does; nothing fires on its own.
+
+Not built yet, by choice:
+
+- Automatic or ambient capture
+- Team sharing, multi-machine sync
+- An MCP server. It would read this same store, so it is an addition, not a rewrite.
+
+What is deliberately unproven, and where you will find out: the cold-read test — a
+fresh chat in a repo untouched for a month, answering correctly from the digest
+alone. That needs real elapsed time and cannot be faked in a test suite.
+
+## Uninstall
+
+Order matters, and npm will not do it for you:
+
+```bash
+agent-memory uninstall      # first — removes every skill link and prompt file
+npm uninstall -g @vib795/agent-memory
+```
+
+npm 7 dropped support for uninstall lifecycle hooks, so `npm uninstall -g` on its
+own deletes the package and leaves a symlink per skill per agent pointing at nothing
+— which every one of those agents will still try to load. Running it in the other
+order is unrecoverable by
+tooling, because the binary that would clean up has already been removed.
+
+If that already happened, reinstalling and re-running `agent-memory setup` repairs it:
+`setup` clears each stale link before writing the new one. Reinstalling alone is not
+enough unless you passed `--allow-scripts`, since that is the same hook npm declines to
+run. If you are not reinstalling, delete `~/.agents/skills/{handoff,recall,remember}`
+and the equivalents under the other agent directories by hand.
+
+`agent-memory doctor` reports broken links by path under `no broken skill links`.
+That catches the case reinstalling does not: links pointing at a global prefix that
+moved, which is what an `nvm` version switch does to a globally installed package.
+
+`uninstall` only removes links that resolve back to this package — a skill you put
+there yourself is left alone. Your notes stay at `~/.agents/memory`: they are plain
+markdown, they outlive the tool that indexed them, and removing them is your call.
+
+## Specs
+
+- [issue #1](https://github.com/vib795/agent-memory/issues/1) — `/handoff`
+- [issue #4](https://github.com/vib795/agent-memory/issues/4) — the memory
+  graph, with a comment listing every place the shipped code diverged from the spec