@vib795/agent-memory 0.1.9 → 0.1.11

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

@@ -96,6 +96,7 @@ 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
+                     --from-json -         read the JSON from stdin instead
 agent-memory compact                       dedup, decay, reindex, regenerate
 agent-memory doctor                        preflight and health report
 ```
@@ -397,10 +398,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.9",
+  "version": "0.1.11",
   "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/skills/handoff/SKILL.md

@@ -274,8 +274,7 @@ Types are `system`, `decision`, `convention`, `constraint`. Edge relations are
 `depends-on`, `applies-to`, `supersedes`, `contradicts`, `evidence-for`.
 
 ```bash
-tmp="$(mktemp)"
-cat > "$tmp" <<'JSON'
+agent-memory write --from-json - --source handoff <<'JSON'
 {"nodes":[
   {"id":"use-sessions","type":"decision",
    "title":"Chose server sessions over JWT",
@@ -283,19 +282,21 @@ cat > "$tmp" <<'JSON'
    "edges":[{"rel":"evidence-for","dst":"auth-service"}]}
 ]}
 JSON
-agent-memory write --from-json "$tmp" --source handoff
-rm -f "$tmp"
 ```
 
 ```powershell
-$tmp = [System.IO.Path]::GetTempFileName()
 @'
 <the JSON>
-'@ | Set-Content -Path $tmp -Encoding UTF8
-agent-memory write --from-json $tmp --source handoff
-Remove-Item -Force $tmp
+'@ | Set-Content -Path .agent-memory-write.json -Encoding UTF8
+agent-memory write --from-json .agent-memory-write.json --source handoff
+Remove-Item -Force .agent-memory-write.json
 ```
 
+**Use these as written. Do not introduce a variable.** Some agent terminals rewrite
+`$`-prefixed lines before the shell sees them, corrupting the payload into malformed
+JSON. PowerShell writes a file rather than piping because Windows PowerShell pipes to
+a native command using `$OutputEncoding`, which is not UTF-8 by default.
+
 `write` redacts before anything reaches disk and reports every validation error at
 once. Surface its warnings verbatim; a `title collision` warning means two ids now
 describe the same thing and the user should know.

package/skills/remember/SKILL.md

@@ -98,25 +98,32 @@ Fields you may set: `id`, `type`, `title`, `body`, `repos`, `scope`, `confidence
 **bash (macOS / Linux):**
 
 ```bash
-tmp="$(mktemp)"
-cat > "$tmp" <<'JSON'
+agent-memory write --from-json - --source remember <<'JSON'
 <the JSON from Step 2>
 JSON
-agent-memory write --from-json "$tmp" --source remember
-rm -f "$tmp"
 ```
 
 **PowerShell (Windows / AVD):**
 
 ```powershell
-$tmp = [System.IO.Path]::GetTempFileName()
 @'
 <the JSON from Step 2>
-'@ | Set-Content -Path $tmp -Encoding UTF8
-agent-memory write --from-json $tmp --source remember
-Remove-Item -Force $tmp
+'@ | Set-Content -Path .agent-memory-write.json -Encoding UTF8
+agent-memory write --from-json .agent-memory-write.json --source remember
+Remove-Item -Force .agent-memory-write.json
 ```
 
+**Use these as written. Do not introduce a variable.** Some agent terminals rewrite
+`$`-prefixed lines before the shell sees them, which turns the payload into malformed
+JSON and costs you two retries diagnosing a corruption that never reached disk. Both
+recipes above are free of variables for that reason.
+
+PowerShell writes a file rather than piping, because Windows PowerShell pipes to a
+native command using `$OutputEncoding`, which is not UTF-8 by default and would mangle
+any non-ASCII character in a body. `-Encoding UTF8` on a file is explicit and safe. The
+file is written next to you and removed on the next line; if you see it left behind,
+the write failed and the JSON is still there to read.
+
 Redaction runs inside `write`, before any bytes reach disk, and cannot be turned
 off. You still must not paste a raw secret into the JSON: the guard is a backstop,
 not a licence.

package/src/cli.js

@@ -298,7 +298,11 @@ function cmdSearch(opts) {
 }
 
 function readNodesFrom(file) {
-  const raw = JSON.parse(readFileSync(file, 'utf8'));
+  // `-` means stdin. Naming a temp file takes a shell variable, and some agent
+  // terminals rewrite `$`-prefixed lines before the shell ever sees them, which
+  // corrupts the payload into malformed JSON with nothing to point at. Reading the
+  // document straight off the pipe removes the variable, and with it the failure.
+  const raw = JSON.parse(readFileSync(file === '-' ? 0 : file, 'utf8'));
   if (Array.isArray(raw)) return raw;
   if (Array.isArray(raw?.nodes)) return raw.nodes;
   return [raw];
@@ -306,11 +310,11 @@ function readNodesFrom(file) {
 
 function cmdWrite(opts) {
   const file = opts['from-json'];
-  if (!file || file === true || !existsSync(file)) {
+  if (!file || file === true || (file !== '-' && !existsSync(file))) {
     return {
       ok: false,
-      error: 'write requires --from-json <file>',
-      text: 'write requires --from-json <file>',
+      error: 'write requires --from-json <file>, or - to read stdin',
+      text: 'write requires --from-json <file>, or - to read stdin',
     };
   }
 

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"