@vib795/agent-memory 0.7.4 → 0.8.1

package/HOWTO.md

@@ -49,14 +49,14 @@ 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 —
+You will need **Node.js version 22.16 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
+If that prints something like `v22.16.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:
@@ -402,7 +402,7 @@ text, and deleting them is your decision to make, not the uninstaller's.
 ## Cheat sheet
 
 ```bash
-node --version                          # must be 22.5+
+node --version                          # must be 22.16+
 npm install -g @vib795/agent-memory     # 1. download
 agent-memory setup                      # 2. install into your AI tools
 agent-memory doctor                     # is everything OK?

package/README.md

@@ -21,7 +21,7 @@ npm install -g @vib795/agent-memory
 agent-memory setup
 ```
 
-Node >= 22.5, and nothing else.
+Node >= 22.16, and nothing else.
 
 In Claude Code you can take the three skills as a plugin instead of letting `setup`
 link them:
@@ -61,7 +61,7 @@ the write and read paths, the tiered context cost, and the invariants underneath
 [![test](https://github.com/vib795/agent-memory/actions/workflows/test.yml/badge.svg)](https://github.com/vib795/agent-memory/actions/workflows/test.yml)
 [![release](https://github.com/vib795/agent-memory/actions/workflows/release.yml/badge.svg)](https://github.com/vib795/agent-memory/actions/workflows/release.yml)
 [![provenance](https://img.shields.io/badge/provenance-attested-brightgreen)](https://www.npmjs.com/package/@vib795/agent-memory)
-[![node](https://img.shields.io/badge/node-%3E%3D22.5-brightgreen)](https://nodejs.org)
+[![node](https://img.shields.io/badge/node-%3E%3D22.16-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)
 
@@ -82,11 +82,43 @@ Nothing in the platform closes the gap:
 
 ## Zero runtime dependencies
 
-`node:sqlite` has shipped inside Node core since 22.5, so the graph index needs no
+`node:sqlite` is built into Node core — no package, no addon — 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.
 
+**Why that is not just a smaller dependency count.** The usual way to reach SQLite
+from Node is `better-sqlite3`, and it is a *native addon*: npm fetches it, then either
+downloads a per-platform prebuilt `.node` binary or compiles C++ on the machine at
+install time. That adds a package to the allowlist, a compiler or a prebuilt artefact
+to every desktop, and a transitive tree behind both. `node:sqlite` is the same engine,
+already inside the Node binary your organisation approved. Nothing is fetched and
+nothing compiles.
+
+So "zero dependencies" here does not mean *vendored*, and it does not mean *only small
+ones*. Every import in `src/` is a Node built-in:
+
+```
+node:child_process   node:crypto   node:fs   node:os
+node:path            node:sqlite   node:url
+```
+
+`package.json` has no `dependencies` key at all, and no `devDependencies` either. A
+reviewer has nothing to audit but this repository. It is enforced rather than promised
+— `.github/workflows/test.yml` fails the build if a dependency is ever added:
+
+```bash
+n=$(node -p "Object.keys(require('./package.json').dependencies||{}).length")
+test "$n" -eq 0 || { echo "::error::$n runtime dependencies; this package must have none"; exit 1; }
+```
+
+The price of this is the Node floor: **22.16 or newer**, and it took three steps to get
+there. `node:sqlite` first appeared in 22.5 behind `--experimental-sqlite`; it was
+unflagged in 22.13; and the bundled SQLite only gained the **FTS5** extension in 22.16.
+`search` is built on FTS5, so 22.16 is the first version where this package runs rather
+than merely imports. That is the one real cost, and it is why `doctor` reports the Node
+version and `fts5: available` as two separate lines.
+
 - **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.
@@ -440,7 +472,7 @@ equivalent and is not: npm links the global install to that folder rather than c
 it, which shows up as an arrow in `npm list -g`:
 
 ```
-`-- @vib795/agent-memory@0.7.4 -> .\..\..\..\agent-memory
+`-- @vib795/agent-memory@0.8.1 -> .\..\..\..\agent-memory
 ```
 
 Move or delete the clone afterwards and the global install points at nothing — the same
@@ -559,9 +591,9 @@ there — `skills/recall/SKILL.md` and `skills/remember/SKILL.md` are tracked fi
 their committed descriptions are deliberately generic placeholders. `compact` prints
 them as skipped, which is the intended outcome, not a failure.
 
-Needs Node 22.5 or newer; `doctor` says so plainly if the version is too old.
+Needs Node 22.16 or newer; `doctor` says so plainly if the version is too old.
 
-Run `npm test` for the suite (111 tests, no dependencies). CI runs it on Linux,
+Run `npm test` for the suite (113 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vib795/agent-memory",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "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",
@@ -20,10 +20,10 @@
   "author": "Utkarsh Singh (https://github.com/vib795)",
   "type": "module",
   "bin": {
-    "agent-memory": "src/cli.js"
+    "agent-memory": "src/bin.js"
   },
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=22.16.0"
   },
   "scripts": {
     "test": "node --test",

package/skills/handoff/SKILL.md

@@ -26,6 +26,22 @@ Every extra request costs the user credits, which is the reason this skill exist
 
 ---
 
+## Scope
+
+Bare `/handoff`: you decide what the working state is.
+
+`/handoff <focus>` — "just the auth work", "the migration, skip the CI detour" — names
+which thread of a braided conversation to carry forward. Treat it as a filter on Step 2
+and Step 3, not as a title. Work outside that focus stays out of Orientation, Decisions
+and Current task state even when it was the more recent work: a long conversation
+usually holds more than one thread, and carrying both is how a handoff becomes the
+transcript summary this skill exists to avoid.
+
+If the focus names a thread you cannot find in the conversation, say so in one line and
+hand off what you did find. Do not invent a thread to match the words.
+
+---
+
 ## Step 0 — Resolve the store path
 
 | Platform | Store |

package/skills/recall/SKILL.md

@@ -59,6 +59,10 @@ are the router. There is no keyword matching underneath this and there should no
 be: a title is a sentence, and matching sentences to a question is what you do well
 and what a regex does badly.
 
+When the user typed `/recall <topic>`, `<topic>` is the question. Route on it, and carry
+it into Step 5 — a cold `/recall deploy ordering` is someone asking what the store knows
+about deploy ordering, not asking for a tour of the store.
+
 - 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.
@@ -115,7 +119,10 @@ Rules that separate a useful recall from a confident wrong one:
    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.
+5. **Answer the question.** An explicit `/recall <topic>` is the target whenever one
+   was given, and it wins over a different question already in the conversation —
+   the user narrowed it on purpose. Fall back to the conversation's own question only
+   for a bare `/recall`. Either way, do not summarize the store.
 
 ---
 
@@ -124,7 +131,7 @@ Rules that separate a useful recall from a confident wrong one:
 - **`agent-memory: command not found`.** The package is not installed or not on
   PATH. This is the expected state when the skill was installed on its own, with
   `gh skill install`, rather than with the package. Answer from the code, then say
-  once that the store needs `npm install -g @vib795/agent-memory` (Node >= 22.5).
+  once that the store needs `npm install -g @vib795/agent-memory` (Node >= 22.16).
   Do not run it yourself: installing a global package is the user's decision, and on
   a managed desktop it is one they may not be free to make.
 - **Empty store.** Answer from the code, then mention `/remember` once.

package/skills/remember/SKILL.md

@@ -107,6 +107,13 @@ Skip this step only when the user named exactly what to write and it is plainly
 
 ## Step 1 — Select what is durable
 
+When the user typed `/remember <what>`, `<what>` is both a filter and a mandate: select
+only what bears on it, and select that even if you would otherwise have ranked something
+else higher. It does not suspend the durability test below. If the named thing is task
+state, write nothing and say so in one line — `that reads as task state, not durable;
+nothing written`. Writing nothing *silently* after an explicit request is the failure
+that matters here, because the user leaves believing it was captured.
+
 <!-- 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.
@@ -243,7 +250,7 @@ Warnings from `write` are worth surfacing verbatim:
   once. If it fails again, print the errors and stop; do not guess at the schema.
 - **`agent-memory: command not found`.** Print the JSON in the chat first, so the
   work is not lost, then say the store needs `npm install -g @vib795/agent-memory`
-  (Node >= 22.5). Do not run it yourself. This is the expected state when the skill
+  (Node >= 22.16). Do not run it yourself. This is the expected state when the skill
   was installed on its own with `gh skill install` rather than with the package.
 - **Nothing durable in the conversation.** Say so in one line. That is a correct
   outcome, not a failure.

package/src/bin.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * The version gate, ahead of the module graph.
+ *
+ * `cli.js` statically imports `index-db.js`, which imports `node:sqlite`. ESM imports
+ * hoist, so on a Node without that module the entire graph fails to load with
+ * `ERR_UNKNOWN_BUILTIN_MODULE` before one line of our code runs — including `doctor`,
+ * whose whole job is to say the version is wrong. A user on Node 20 got an internal
+ * stack trace instead of a sentence telling them what to do.
+ *
+ * So the check lives here, in the one file that imports nothing, and `cli.js` is
+ * loaded dynamically only once the runtime is known to be capable. This is the same
+ * reasoning as `atomic.js` importing nothing from the package: a guard that depends on
+ * what it guards is not a guard.
+ *
+ * MIN_NODE is stated twice, here and in `cli.js`, because this file cannot import from
+ * a module that pulls in the database. The test suite asserts the two agree.
+ */
+const MIN_NODE = [22, 16];
+
+const [major, minor] = process.versions.node.split('.').map(Number);
+
+if (major < MIN_NODE[0] || (major === MIN_NODE[0] && minor < MIN_NODE[1])) {
+  process.stderr.write(
+    `agent-memory needs Node >= ${MIN_NODE.join('.')}; this process is ${process.versions.node}.\n` +
+      'The store is SQLite via node:sqlite, which carries the FTS5 extension only from\n' +
+      '22.16 onward, and search is built on FTS5. There is no dependency to install —\n' +
+      'upgrade Node and run the same command again.\n',
+  );
+  process.exit(1);
+}
+
+await import('./cli.js');

package/src/cli.js

@@ -30,7 +30,7 @@ import { redactNodeForExport, buildReceipt, renderReceipt } from './pii.js';
  * run and the first thing that breaks after a reboot.
  */
 
-const MIN_NODE = [22, 5];
+const MIN_NODE = [22, 16];
 
 /**
  * Where this process is actually running from, and what version it is.
@@ -589,7 +589,7 @@ function cmdDoctor() {
       checks,
       text:
         `FAIL node version: ${process.versions.node}, need >= ${MIN_NODE.join('.')}.\n` +
-        'node:sqlite ships in Node core from 22.5 onward; there is no dependency to install.',
+        'node:sqlite carries FTS5 in Node core from 22.16 onward; there is no dependency to install.',
     };
   }