@vib795/agent-memory 0.1.0

package/install.ps1

@@ -0,0 +1,54 @@
+<#
+.SYNOPSIS
+  Installs agent-memory and all three skills from a checkout.
+
+.DESCRIPTION
+  `npm install -g .` does this on its own via the postinstall hook. This script
+  exists for two cases: installing straight from a clone without npm, and finishing
+  the job when a managed npm config sets ignore-scripts=true and silently skips it.
+
+  The linking itself lives in src\setup.js, not here. That is deliberate: a PowerShell
+  reimplementation could only be tested on Windows, and the machine this was written
+  on is not Windows. One implementation, three entry points, no drift.
+
+  Skills are linked into both agent directories:
+    %USERPROFILE%\.agents\skills\<name>   -> read by GitHub Copilot in every window
+    %USERPROFILE%\.claude\skills\<name>   -> read by Claude Code
+
+  Directory junctions are used, which need neither admin rights nor Developer Mode.
+  They fail on a network-backed profile (FSLogix, roaming), and setup falls back to
+  copying and says so.
+
+.EXAMPLE
+  powershell -ExecutionPolicy Bypass -File .\install.ps1
+#>
+
+$ErrorActionPreference = 'Stop'
+
+$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
+}
+
+& node (Join-Path $source 'src\cli.js') setup
+
+Write-Host ""
+Write-Host "Linking the CLI" -ForegroundColor Cyan
+& npm install -g $source 2>&1 | Out-Null
+if ($LASTEXITCODE -eq 0) {
+    Write-Host "  [npm] agent-memory installed globally" -ForegroundColor Green
+} else {
+    # A global install failing on a managed desktop is common and not worth aborting
+    # on. The skills are already linked; this one step can be finished by hand.
+    Write-Host "  [npm] global install failed. Run this yourself:" -ForegroundColor Yellow
+    Write-Host "        npm install -g `"$source`"" -ForegroundColor Yellow
+}
+
+Write-Host ""
+& node (Join-Path $source 'src\cli.js') doctor
+
+Write-Host ""
+Write-Host "Installed. Restart VS Code, then try /recall, /remember, or /handoff." -ForegroundColor Cyan

package/install.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Installs agent-memory and all three skills from a checkout, on macOS/Linux.
+#
+# `npm install -g .` does this on its own via the postinstall hook. This script
+# exists for two cases: installing straight from a clone without npm, and finishing
+# the job when a managed npm config sets ignore-scripts=true and silently skips it.
+#
+# The linking itself lives in src/setup.js, not here. One implementation, three entry
+# points, so this script and its PowerShell twin cannot drift from each other.
+set -euo 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
+
+node "$source_dir/src/cli.js" setup
+
+echo
+echo "Linking the CLI"
+if npm install -g "$source_dir" >/dev/null 2>&1; then
+  echo "  [npm] agent-memory installed globally"
+else
+  # A global install needing sudo is common and is not worth aborting on. The skills
+  # are already linked, and the user can finish this one step by hand.
+  echo "  [npm] global install failed (permissions?). Run this yourself:"
+  echo "        npm install -g \"$source_dir\""
+fi
+
+echo
+node "$source_dir/src/cli.js" doctor || true
+
+echo
+echo "Installed. Restart VS Code, then try /recall, /remember, or /handoff."

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@vib795/agent-memory",
+  "version": "0.1.0",
+  "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",
+    "claude-code",
+    "agent-skills",
+    "memory",
+    "knowledge-graph",
+    "sqlite",
+    "zero-dependencies"
+  ],
+  "homepage": "https://github.com/vib795/agent-memory#readme",
+  "bugs": "https://github.com/vib795/agent-memory/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vib795/agent-memory.git"
+  },
+  "author": "Utkarsh Singh (https://github.com/vib795)",
+  "type": "module",
+  "bin": {
+    "agent-memory": "src/cli.js"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "postinstall": "node scripts/postinstall.js",
+    "setup": "node src/cli.js setup"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "skills/",
+    "install.sh",
+    "install.ps1",
+    "README.md",
+    "HOWTO.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Link the skills when the package is installed.
+ *
+ * This must never fail an install. A missing symlink is a nuisance; an `npm install`
+ * that exits non-zero on a managed desktop is the kind of thing that gets a tool
+ * banned. Every failure here is reported and swallowed, and `agent-memory setup`
+ * remains available to finish the job by hand.
+ *
+ * Note that managed npm configurations often set `ignore-scripts=true`, in which case
+ * this file never runs and nothing warns you. That is precisely why the same work is
+ * exposed as a command, and why `doctor` names it.
+ */
+
+const say = (msg) => process.stdout.write(`${msg}\n`);
+
+if (process.env.AGENT_MEMORY_SKIP_POSTINSTALL) {
+  process.exit(0);
+}
+
+try {
+  const [maj, min] = process.versions.node.split('.').map((s) => Number.parseInt(s, 10));
+  if (maj < 22 || (maj === 22 && min < 5)) {
+    say(`agent-memory: Node ${process.versions.node} is too old; needs >= 22.5 for node:sqlite.`);
+    say('agent-memory: skills not linked. Upgrade Node, then run: agent-memory setup');
+    process.exit(0);
+  }
+
+  const { setup } = await import('../src/setup.js');
+  const { compact } = await import('../src/compact.js');
+  const r = setup({ compactFn: () => compact() });
+
+  const links = r.installed.filter((s) => s.mode === 'link').length;
+  const copies = r.copies.length;
+  say(`agent-memory: linked ${links} skill${links === 1 ? '' : 's'}${copies ? `, copied ${copies}` : ''}.`);
+  say(`agent-memory: ${r.notes} notes indexed. Restart VS Code, then try /recall.`);
+  if (copies) {
+    say('agent-memory: copies happen on network-backed profiles; re-run `agent-memory setup` after upgrades.');
+  }
+} catch (err) {
+  say(`agent-memory: automatic setup did not complete (${err.message}).`);
+  say('agent-memory: run `agent-memory setup` to finish. Nothing else is affected.');
+}
+
+process.exit(0);

package/skills/handoff/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: handoff
+version: 0.1.0
+description: Capture the working state of the current conversation into a portable handoff file, so an agent in a different VS Code window or a different repository can continue the work without the user re-explaining it. Use when the user says handoff, hand this off, save context, wrap this up, or continue this elsewhere.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+triggers:
+  - handoff
+  - hand this off
+  - save context for another window
+  - continue this in another repo
+---
+
+# handoff
+
+Write one file that lets a different agent, in a different window, on a different
+repo, pick up this thread cold.
+
+You are not summarizing the conversation. You are reconstructing **working state**.
+A transcript summary is a failure mode: it reads fine and still leaves the next
+agent asking the questions the user is trying to avoid answering twice.
+
+Do the whole job in **one pass**. Gather facts in a single terminal call, then
+write. Do not loop, do not re-read source files, do not interrogate the user.
+Every extra request costs the user credits, which is the reason this skill exists.
+
+---
+
+## Step 0 — Resolve the store path
+
+| Platform | Store |
+|---|---|
+| Windows | `$env:USERPROFILE\.agents\handoffs` |
+| macOS / Linux | `$HOME/.agents/handoffs` |
+
+The store lives outside every repository on purpose. That is what makes a handoff
+readable from a window opened on a different project.
+
+---
+
+## Step 1 — Gather deterministic facts (ONE terminal call)
+
+Run one command that creates the store, reads the index, and collects git state.
+Everything the deterministic layer contributes comes from this single call.
+
+**PowerShell (Windows / AVD):**
+
+```powershell
+$store = Join-Path $env:USERPROFILE '.agents\handoffs'
+New-Item -ItemType Directory -Force -Path $store | Out-Null
+Write-Output "STORE=$store"
+Write-Output "--- INDEX ---"
+if (Test-Path (Join-Path $store 'index.md')) { Get-Content (Join-Path $store 'index.md') } else { Write-Output "(no index yet)" }
+Write-Output "--- GIT ---"
+Write-Output "ROOT=$(git rev-parse --show-toplevel 2>$null)"
+Write-Output "BRANCH=$(git branch --show-current 2>$null)"
+Write-Output "HEAD=$(git rev-parse --short HEAD 2>$null)"
+Write-Output "--- STATUS ---"
+git status --porcelain 2>$null
+Write-Output "UTC=$([DateTime]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ'))"
+```
+
+**bash (macOS / Linux):**
+
+```bash
+store="$HOME/.agents/handoffs"; mkdir -p "$store"
+echo "STORE=$store"
+echo "--- INDEX ---"; [ -f "$store/index.md" ] && cat "$store/index.md" || echo "(no index yet)"
+echo "--- GIT ---"
+echo "ROOT=$(git rev-parse --show-toplevel 2>/dev/null)"
+echo "BRANCH=$(git branch --show-current 2>/dev/null)"
+echo "HEAD=$(git rev-parse --short HEAD 2>/dev/null)"
+echo "--- STATUS ---"; git status --porcelain 2>/dev/null
+echo "UTC=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+```
+
+If the directory is not a git repository, `ROOT`/`BRANCH`/`HEAD` come back empty.
+That is not an error. Record the working directory path and omit the git fields.
+
+---
+
+## Step 2 — Identify the thread
+
+Read the `--- INDEX ---` output and decide, **by judgment**, whether this
+conversation continues an existing thread or starts a new one. Do not string-match
+titles; a title drifts as work progresses and the thread is still the same thread.
+
+- Same goal as an existing row, even under a different name → reuse that `id`.
+- Same repo but a genuinely different goal → new `id`.
+- Nothing close → new `id`.
+
+New ids are kebab-case, 3 to 6 words, naming the **goal**, not the topic:
+`migrate-orders-to-result-type`, not `orders-work`.
+
+State your choice in the final output: "Updating thread `<id>`" or
+"Creating thread `<id>`". If you guessed wrong the user corrects it in one line,
+which is cheaper than asking.
+
+---
+
+## Step 3 — Compose the handoff
+
+Use this exact structure.
+
+```markdown
+---
+id: <kebab-slug>
+title: <one line, states the goal not the topic>
+status: active | blocked | done
+created: <ISO 8601 UTC>
+updated: <ISO 8601 UTC>
+repos:
+  - name: <repo name>
+    path: <absolute path>
+    branch: <branch>
+    head: <short sha>
+agent: copilot | claude-code
+---
+
+## Orientation
+
+3 to 5 sentences. What this thread is trying to accomplish and where it stands.
+Written for a reader with zero prior context.
+
+## Decisions
+
+| # | Decision | Why | Alternatives rejected |
+|---|----------|-----|----------------------|
+
+## Constraints
+
+Things not discoverable by reading the code: environment restrictions,
+unavailable tooling, plan limits, deadlines, taste calls already settled.
+
+## Rejected approaches
+
+What was tried and why it failed. Mandatory. This is the section that stops the
+next agent re-deriving known dead ends on the user's credits.
+
+## Current task state
+
+**Next action:** <one imperative sentence>
+**Blocked on:** <specific blocker, or "nothing">
+
+### Uncommitted work
+
+| File | State | What changed |
+|------|-------|--------------|
+
+### Anchors
+
+| Path | Why it matters |
+|------|----------------|
+
+## Open questions
+
+Numbered. Only questions the user can answer.
+```
+
+`State` in Uncommitted work comes from `git status --porcelain`: `modified`,
+`added`, `deleted`, `untracked`, `renamed`.
+
+### Quality rules
+
+These separate a useful handoff from a readable paragraph that still leaves questions.
+
+1. Write for a reader with zero context. No pronoun without a stated antecedent.
+2. Every decision carries its **why**. Rationale is what never survives
+   re-explanation and is the whole reason a handoff beats a transcript.
+3. Never quote or paraphrase the transcript. Record conclusions, not the path to them.
+4. Anchor claims to a file path or a decision number. "We refactored the service
+   layer" is a failure. "`src/services/order.ts:42` now returns `Result<T>` instead
+   of throwing" is not.
+5. Record only what the conversation actually established. Prefix anything you
+   inferred with `inferred:` so the next agent knows to verify it.
+6. Never inline a diff or a patch. List changed files with one line each.
+7. Soft target 150 lines. On overflow, move detail into `<id>.detail.md` and
+   reference it. Never drop Decisions or Rejected approaches to hit the target.
+8. Empty sections say `None.` They are never deleted. A missing section reads as
+   an oversight; an explicit `None.` reads as a fact.
+
+---
+
+## Step 4 — Redact before writing
+
+Scan the drafted body and replace any of these with `<redacted:kind>`:
+
+API keys, access tokens, bearer tokens, passwords, connection strings, private
+keys, session cookies, internal hostnames or IPs, and personal email addresses
+that are not the user's own git identity.
+
+The store is plaintext on a corporate machine. Never write the raw value, not even
+once, not even to a temp file.
+
+---
+
+## Step 5 — Write the files
+
+Prefer your file-write tool targeting the absolute store path. If it refuses to
+write outside the workspace root, fall back to the terminal.
+
+Order matters:
+
+1. If `<id>.md` exists, move it to `<id>.prev.md`, overwriting any existing `.prev`.
+   Exactly one prior version is kept. There is no version history.
+2. Write the new body to `<id>.md.tmp`.
+3. Rename `<id>.md.tmp` to `<id>.md`.
+4. Only if the soft target overflowed, write `<id>.detail.md` the same way.
+
+**PowerShell fallback.** Use a single-quoted here-string so `$` and backticks in
+the content are not expanded:
+
+```powershell
+$store = Join-Path $env:USERPROFILE '.agents\handoffs'
+$id = '<id>'
+$cur = Join-Path $store "$id.md"
+if (Test-Path $cur) { Move-Item -Force $cur (Join-Path $store "$id.prev.md") }
+$body = @'
+<the full handoff body>
+'@
+Set-Content -Path (Join-Path $store "$id.md.tmp") -Value $body -Encoding UTF8
+Move-Item -Force (Join-Path $store "$id.md.tmp") $cur
+```
+
+---
+
+## Step 6 — Update the index
+
+`index.md` is what makes retrieval cheap later. Keep it to one row per thread.
+
+```markdown
+| id | title | status | repos | updated |
+|----|-------|--------|-------|---------|
+```
+
+Replace the row whose `id` matches. Append only when the id is new. Never let two
+rows share an id.
+
+---
+
+## Step 7 — Capture durable knowledge
+
+Skip this step entirely if `agent-memory` is not installed. It is optional
+machinery; the handoff above is complete without it.
+
+A handoff carries this thread. The graph carries what stays true after the thread
+ends. You already hold the whole conversation, so writing both costs the same single
+request, which is the only reason this step belongs here rather than in its own skill.
+
+### What is durable
+
+<!-- extraction-rules:start -->
+- A node is durable only if it will still be true next month. Task state is not
+  durable and belongs in a handoff file, not in the graph.
+- Every `decision` node carries its why and its rejected alternatives, or it is not
+  written. Rationale is the thing that never survives re-explanation.
+- Anything the conversation did not actually establish is `confidence: inferred`,
+  and the body says what would confirm it.
+- Prefer updating an existing node over creating a near-duplicate. `write` returns
+  the existing id on a content-hash match.
+- A decision that replaces a known prior sets `supersedes` to that prior's id.
+- Constraints are the highest-value type. An environment restriction, a blocked
+  tool, a policy that forbids an approach: write it, because it is what stops a
+  future agent burning a retry loop on something that was never going to ship.
+- Zero durable knowledge is a valid outcome. Writing nothing beats writing noise.
+<!-- extraction-rules:end -->
+
+Your Decisions table and Constraints section are usually already the durable part.
+The Current task state section never is.
+
+### Write it (ONE terminal call)
+
+Types are `system`, `decision`, `convention`, `constraint`. Edge relations are
+`depends-on`, `applies-to`, `supersedes`, `contradicts`, `evidence-for`.
+
+```bash
+tmp="$(mktemp)"
+cat > "$tmp" <<'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
+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
+```
+
+`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.
+
+---
+
+## Step 8 — Print the pickup line
+
+End your reply with exactly this, and nothing after it:
+
+```
+Handoff written: <absolute path to id.md>
+Thread: <id> (<created|updated>)
+
+Paste this in the other window:
+Read <absolute path to id.md> and continue this work. Follow the Next action.
+```
+
+---
+
+## Self-check before you write
+
+Answer all five. If any is no, fix the file before writing it.
+
+1. Could a fresh agent execute **Next action** from this file alone?
+2. Does every decision state why, and what was rejected?
+3. Is Rejected approaches non-empty, or explicitly `None.`?
+4. Is every claim anchored to a path or a decision number?
+5. Is there a single secret, token, or connection string left in the body?
+
+---
+
+## Failure handling
+
+- **File-write tool refuses paths outside the workspace.** Use the PowerShell or
+  bash fallback in Step 5. Expected on some configurations; not an error.
+- **Terminal commands are approval-gated.** Proceed anyway. One approval click is
+  worth minutes of re-explanation. Do not ask the user to disable the gate.
+- **Both write paths blocked.** Print the complete handoff body in the chat with
+  its intended absolute path and tell the user to save it manually. Never silently
+  fail, and never claim you wrote a file you did not write.
+- **Not a git repository.** Omit git fields, record the working directory path,
+  continue.

package/skills/recall/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: recall
+version: 0.1.0
+description: "Durable project knowledge store. This line is regenerated by `agent-memory compact`. Use when you need to know how a system works, why a decision was made, what convention applies, or what the environment forbids."
+allowed-tools:
+  - Bash
+  - Read
+triggers:
+  - how does this work
+  - why did we
+  - what did we decide
+  - what is the convention
+  - recall
+---
+
+# recall
+
+Answer from what this project already knows, before deriving it again.
+
+The description line above is regenerated by `agent-memory compact`. It is the only
+part of this system loaded into every conversation, so it stays short on purpose.
+Everything below is read only when you actually invoke the skill.
+
+Do the whole job in **one pass**. The routing map and the notes are two terminal
+calls inside a single turn. Do not loop, do not re-read, do not ask the user what
+they already told a previous window.
+
+---
+
+## Step 1 — Load the routing map (ONE terminal call)
+
+```bash
+agent-memory tree
+```
+
+`tree` scopes itself to the current repository and always includes globally scoped
+notes, because a global constraint applies here too.
+
+Output is one line per note: type, id, title.
+
+```
+# memory: orders-api — 12 notes
+constraint no-external-db     No externally hosted databases
+decision   use-sessions       Chose sessions over JWT
+system     auth-service       Auth uses server sessions
+```
+
+If the last line reads `N nodes not shown`, that is a real gap, not decoration.
+Run `agent-memory tree --all` when the answer plausibly lives in what was dropped.
+
+If the store is empty, say so in one line and answer from the code instead. Do not
+invent notes and do not apologize at length.
+
+---
+
+## Step 2 — Choose what to load
+
+Read the titles and decide, **by judgment**, which notes bear on the question. You
+are the router. There is no keyword matching underneath this and there should not
+be: a title is a sentence, and matching sentences to a question is what you do well
+and what a regex does badly.
+
+- Pick 1 to 3 ids. More than 3 means the question is really several questions.
+- Always include a `constraint` that touches the subject, even when the user did not
+  ask about limits. Constraints are what stop an approach that cannot ship.
+- Nothing in the tree looks relevant → go to Step 4.
+
+---
+
+## Step 3 — Load them (ONE terminal call)
+
+```bash
+agent-memory get auth-service --depth 1
+agent-memory get no-external-db --depth 1
+```
+
+`--depth 1` returns the note plus everything one edge away. Use `--depth 2` only
+when the question is about how parts fit together rather than about one part.
+
+Two things in the output are load-bearing:
+
+- `[captured N commits ago — verify before trusting]` means the note was written
+  against an older state of this repository. Say so when you use it.
+- `N nodes omitted for budget` means the neighborhood was larger than the return
+  budget. The omitted ids are listed; ask for one directly if it matters.
+
+---
+
+## Step 4 — Fall back to search
+
+Only when the tree had nothing plausible:
+
+```bash
+agent-memory search "session revocation"
+```
+
+Full text over titles and bodies. If this also misses, the store genuinely does not
+know, and saying so plainly is the correct answer.
+
+---
+
+## Step 5 — Answer
+
+Rules that separate a useful recall from a confident wrong one:
+
+1. **Cite the note id** for every claim you take from memory, and the `path:line`
+   inside the note when it has one.
+2. **Repeat the staleness annotation** if the note carried one. A note captured 47
+   commits ago may still be right, but the user decides that, not you.
+3. **The code wins.** If a note contradicts what you can read in the repository
+   right now, trust the repository, say which note is wrong, and suggest
+   `/remember` to correct it. A store that quietly rots is worse than no store.
+4. **Never present an `inferred` note as established.** The note says which it is.
+5. Answer the question. Do not summarize the store.
+
+---
+
+## Failure handling
+
+- **`agent-memory: command not found`.** The package is not installed or not on
+  PATH. Say so and answer from the code; do not attempt to install it.
+- **Empty store.** Answer from the code, then mention `/remember` once.
+- **`doctor` reports a problem.** Report it in one line and continue. `index.db` is
+  a cache; `agent-memory index` rebuilds it from the markdown, which is the source
+  of truth and is never lost.