@vib795/agent-memory 0.1.10 → 0.1.12

package/HOWTO.md

@@ -236,16 +236,17 @@ 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.
+**Supported.** `setup` installs the three skills into `~/.copilot/skills/<name>/`, and
+they appear as `/handoff`, `/remember` and `/recall`.
 
-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.
+GitHub documents two personal skill directories, `~/.copilot/skills` and
+`~/.agents/skills`, and Copilot reads both. The shared one is always written, so
+Copilot is served even on a machine that has never run the CLI; the `.copilot` one is
+written as well when that directory exists, so a machine that has run it keeps its
+skills where its own documentation says to look.
 
-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.
+Earlier versions of this guide said Copilot CLI was unsupported. That was true when it
+was written and stopped being true in 0.1.5.
 
 ---
 
@@ -326,9 +327,40 @@ agent-memory doctor
 
 ---
 
-## 12. Removing it
+## 12. Updating it
 
-**The order matters, and npm will not do it for you:**
+**Installed from npm:**
+
+```bash
+npm install -g @vib795/agent-memory@latest
+agent-memory setup
+```
+
+The second line is not optional. Prompt files are copies rather than links, so VS Code
+keeps reading the old text until something rewrites them, and nothing warns you.
+
+**Installed from a clone** — one command, which pulls and re-runs the installer:
+
+```bash
+./update.sh                                            # macOS / Linux
+powershell -ExecutionPolicy Bypass -File .\update.ps1  # Windows
+```
+
+Both finish with `agent-memory doctor`, so you find out straight away if a tool was
+left holding stale files. Your notes are never touched by an upgrade.
+
+---
+
+## 13. Removing it
+
+**One command, which does the two steps in the order that works:**
+
+```bash
+./uninstall.sh                                            # macOS / Linux
+powershell -ExecutionPolicy Bypass -File .\uninstall.ps1  # Windows
+```
+
+**Or by hand. The order matters, and npm will not do it for you:**
 
 ```bash
 agent-memory uninstall          # first — this removes the commands from your tools

package/README.md

@@ -322,32 +322,111 @@ A transcript summary reads fine and still leaves the next agent asking questions
 
 ## Use
 
-Two different jobs, and it is worth being clear about which is which.
+Three commands, two different jobs. You type the slash command in your agent; the
+agent runs the CLI. The terminal equivalents are shown so you can see what it did,
+and drive it by hand when you want to.
 
-**Moving a thread between windows.** In window A:
+### `/remember` — keep what stays true
+
+Mid-session, when something worth keeping has been established:
 
 ```
-/handoff
+/remember
+/remember the retry policy on the orders webhook
 ```
 
-It prints a pickup line. In window B, any repo, paste it:
+Bare, it selects the durable knowledge itself. With an argument, it writes that and
+nothing else. Either way it makes one terminal call, and `write` reports each id:
 
 ```
-Read C:\Users\you\.agents\handoffs\migrate-orders-to-result-type.md and continue this work. Follow the Next action.
+created auth-service [system]
+created use-sessions [decision]
+warning: use-sessions: redacted 1x github-token
 ```
 
-**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:
+That warning is the redactor firing before anything reached disk. The skill then
+repeats the list back to you with titles attached, so you can see what was captured
+without opening the files.
 
+What it ran, which you can run yourself:
+
+```bash
+agent-memory write --from-json - --source remember <<'JSON'
+{"nodes":[
+  {"id":"use-sessions","type":"decision",
+   "title":"Chose server sessions over JWT",
+   "body":"Why: revocation had to take effect immediately.\nRejected: short-TTL JWT, because logout would lag by the TTL.\nImplemented in src/auth/session.js:42.",
+   "edges":[{"rel":"evidence-for","dst":"auth-service"}]}
+]}
+JSON
 ```
-/remember
-/remember the retry policy on the orders webhook
+
+### `/recall` — answer from memory before deriving again
+
+You rarely type this one. Ask a question memory should already answer and the agent
+invokes it on its own, because the skill description advertises what is in the store:
+
+```
+Why do we use sessions instead of JWT here?
+/recall the auth decision
+```
+
+It reads the routing map first, then pulls only the notes it needs:
+
+```bash
+agent-memory tree                      # what exists, scoped to this repo
+agent-memory get use-sessions --depth 1   # that note plus its neighbourhood
+agent-memory search "session revocation"  # full text, when the tree misses
+```
+
+A note that is still current prints clean, with its edges:
+
 ```
+## use-sessions  [decision]  depth 0
+Chose server sessions over JWT
 
-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.
+Why: revocation had to take effect immediately.
+
+  -> evidence-for auth-service
+```
+
+Once the code has moved on underneath it, the same note arrives carrying the warning.
+This is the part that keeps the store honest:
+
+```
+## use-sessions  [decision]  depth 0  [captured 47 commits ago — verify before trusting]
+```
+
+### `/handoff` — move a thread to another window
+
+In window A:
+
+```
+/handoff
+```
+
+It writes the working-state file and prints a pickup line. In window B, any repo,
+paste it:
+
+```
+Read ~/.agents/handoffs/migrate-orders-to-result-type.md and continue this work. Follow the Next action.
+```
+
+`/handoff` also writes durable knowledge into the graph in the same request — same
+turn, no extra request charged. To see what it produced:
+
+```bash
+ls ~/.agents/handoffs/           # index.md, <thread>.md, one <thread>.prev.md
+agent-memory tree                # the nodes it captured on the way past
+```
+
+### Housekeeping
+
+```bash
+agent-memory doctor              # after install, after an upgrade, when something looks off
+agent-memory compact             # dedup, decay, regenerate the routing digest
+agent-memory tree --repo         # every repo, not just this one
+```
 
 ## Where things live
 
@@ -398,10 +477,40 @@ What is deliberately unproven, and where you will find out: the cold-read test
 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.
 
+## Update
+
+An upgrade is not finished until `setup` has run again. Prompt files are copies
+rather than links, so an editor keeps reading the old text until something rewrites
+them, and nothing warns you.
+
+**Installed from npm:**
+
+```bash
+npm install -g @vib795/agent-memory@latest
+agent-memory setup
+```
+
+**Installed from a clone** — one command, which pulls and re-runs the installer:
+
+```bash
+./update.sh                                            # macOS / Linux
+powershell -ExecutionPolicy Bypass -File .\update.ps1  # Windows
+```
+
+Both end in `agent-memory doctor`, so you find out immediately if an agent was left
+holding stale files. Your notes are never touched by an upgrade.
+
 ## Uninstall
 
 Order matters, and npm will not do it for you:
 
+```bash
+./uninstall.sh                                            # macOS / Linux
+powershell -ExecutionPolicy Bypass -File .\uninstall.ps1  # Windows
+```
+
+Or by hand, which is the same two steps in the same order:
+
 ```bash
 agent-memory uninstall      # first — removes every skill link and prompt file
 npm uninstall -g @vib795/agent-memory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vib795/agent-memory",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Durable cross-repo knowledge graph for GitHub Copilot and Claude Code. Markdown source of truth, disposable SQLite index, zero runtime dependencies.",
   "keywords": [
     "github-copilot",
@@ -36,6 +36,10 @@
     "skills/",
     "install.sh",
     "install.ps1",
+    "update.sh",
+    "update.ps1",
+    "uninstall.sh",
+    "uninstall.ps1",
     "README.md",
     "HOWTO.md",
     "LICENSE"

package/uninstall.ps1

@@ -0,0 +1,54 @@
+<#
+.SYNOPSIS
+  Removes the skills and the CLI, in the order that is recoverable.
+
+.DESCRIPTION
+  npm will not enforce that order and gets it wrong on its own: `npm uninstall -g`
+  deletes the package and leaves one link per skill per agent pointing at nothing,
+  which every one of those agents still tries to load. By then the binary that would
+  have cleaned them up is gone too, so tooling cannot fix it. This unlinks first and
+  removes the package second.
+
+  Your notes are never touched. They are plain markdown under
+  %USERPROFILE%\.agents\memory, they outlive the tool that indexed them, and removing
+  them is your call, not this script's.
+
+.EXAMPLE
+  powershell -ExecutionPolicy Bypass -File .\uninstall.ps1
+#>
+
+# Not 'Stop': a half-finished uninstall is worse than a reported failure, so each step
+# is allowed to fail and say so.
+$ErrorActionPreference = 'Continue'
+
+$source = $PSScriptRoot
+
+$node = Get-Command node -ErrorAction SilentlyContinue
+if (-not $node) {
+    Write-Error "node not found on PATH. agent-memory needs Node >= 22.5."
+    exit 1
+}
+
+Write-Host "Removing skills" -ForegroundColor Cyan
+# Run from the checkout rather than the installed binary, so this still works when the
+# global package is already gone.
+& node (Join-Path $source 'src\cli.js') uninstall
+
+Write-Host ""
+Write-Host "Removing the CLI" -ForegroundColor Cyan
+try {
+    & npm uninstall -g '@vib795/agent-memory' 2>&1 | Out-Null
+    $npmExit = $LASTEXITCODE
+} catch {
+    $npmExit = 1
+}
+
+if ($npmExit -eq 0) {
+    Write-Host "  [npm] package removed" -ForegroundColor Green
+} else {
+    Write-Host "  [npm] not removed. It may not be installed globally:" -ForegroundColor Yellow
+    Write-Host "        npm uninstall -g `"@vib795/agent-memory`"" -ForegroundColor Yellow
+}
+
+Write-Host ""
+Write-Host "Done. Your notes are untouched." -ForegroundColor Cyan

package/uninstall.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Removes the skills and the CLI, in the order that is recoverable.
+#
+# npm will not enforce that order and gets it wrong on its own: `npm uninstall -g`
+# deletes the package and leaves one link per skill per agent pointing at nothing,
+# which every one of those agents still tries to load. By then the binary that would
+# have cleaned them up is gone too, so tooling cannot fix it. Unlink first, remove
+# the package second.
+#
+# Your notes are never touched. They are plain markdown under ~/.agents/memory, they
+# outlive the tool that indexed them, and removing them is your call, not this script's.
+#
+# No `set -e`: a half-finished uninstall is worse than a reported failure, so each
+# step is allowed to fail and say so.
+set -uo pipefail
+
+source_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "node not found on PATH. agent-memory needs Node >= 22.5." >&2
+  exit 1
+fi
+
+echo "Removing skills"
+# Run from the checkout rather than the installed binary, so this still works when
+# the global package is already gone.
+node "$source_dir/src/cli.js" uninstall
+
+echo
+echo "Removing the CLI"
+if npm uninstall -g @vib795/agent-memory >/dev/null 2>&1; then
+  echo "  [npm] package removed"
+else
+  echo "  [npm] not removed. It may not be installed globally, or may need sudo:"
+  echo "        npm uninstall -g @vib795/agent-memory"
+fi
+
+echo
+echo "Done. Your notes are untouched at ${AGENT_MEMORY_HOME:-$HOME/.agents/memory}."

package/update.ps1

@@ -0,0 +1,45 @@
+<#
+.SYNOPSIS
+  Updates a clone install: pull, then re-run the installer.
+
+.DESCRIPTION
+  The install logic is deliberately not repeated here. install.ps1 already relinks the
+  skills, relinks the CLI and runs doctor; an update is exactly that plus a pull, and
+  writing it a second time is how the two drift.
+
+  Re-running setup is not optional on an upgrade. Prompt files are copies rather than
+  links, so VS Code keeps reading the old text until something rewrites it.
+
+.EXAMPLE
+  powershell -ExecutionPolicy Bypass -File .\update.ps1
+#>
+
+$ErrorActionPreference = 'Stop'
+
+$source = $PSScriptRoot
+
+if (-not (Test-Path (Join-Path $source '.git'))) {
+    Write-Host "This is not a git checkout, so there is nothing to pull." -ForegroundColor Yellow
+    Write-Host "If you installed from npm, update with:" -ForegroundColor Yellow
+    Write-Host "  npm install -g @vib795/agent-memory@latest" -ForegroundColor Yellow
+    Write-Host "  agent-memory setup" -ForegroundColor Yellow
+    exit 1
+}
+
+Write-Host "Pulling" -ForegroundColor Cyan
+# git writes ordinary progress to stderr, and `Stop` would treat that as terminating.
+$previousPreference = $ErrorActionPreference
+$ErrorActionPreference = 'Continue'
+try {
+    & git -C $source pull --ff-only 2>&1 | Write-Host
+    $gitExit = $LASTEXITCODE
+} finally {
+    $ErrorActionPreference = $previousPreference
+}
+if ($gitExit -ne 0) {
+    Write-Error "git pull failed. Resolve that first, then run this again."
+    exit 1
+}
+
+Write-Host ""
+& powershell -ExecutionPolicy Bypass -File (Join-Path $source 'install.ps1')

package/update.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Updates a clone install: pull, then re-run the installer.
+#
+# The install logic is deliberately not repeated here. install.sh already relinks the
+# skills, relinks the CLI and runs doctor; an update is exactly that plus a pull, and
+# writing it a second time is how the two drift.
+#
+# Re-running setup is not optional on an upgrade. Prompt files are copies rather than
+# links, so an editor keeps reading the old text until something rewrites it.
+set -euo pipefail
+
+source_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [ ! -d "$source_dir/.git" ]; then
+  echo "This is not a git checkout, so there is nothing to pull." >&2
+  echo "If you installed from npm, update with:" >&2
+  echo "  npm install -g @vib795/agent-memory@latest" >&2
+  echo "  agent-memory setup" >&2
+  exit 1
+fi
+
+echo "Pulling"
+git -C "$source_dir" pull --ff-only
+
+echo
+exec "$source_dir/install.sh"