@vib795/agent-memory 0.5.2 → 0.6.1

package/README.md

@@ -1,17 +1,45 @@
 # agent-memory
 
-[![npm](https://img.shields.io/npm/v/@vib795/agent-memory)](https://www.npmjs.com/package/@vib795/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)
-[![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)
-[![dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)](package.json)
-[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+**Durable memory for Claude Code and GitHub Copilot — that survives an IT security review.**
+
+Your agent forgets everything between windows. Most tools that fix that cannot be
+installed where you actually work.
+
+This one has **zero runtime dependencies, zero dev dependencies, and no install
+script**. Nothing runs when you install it; granting it your agents is a second,
+separate command. It has been [independently scanned](#independently-scanned) and
+passed. `npm ls -g --depth 0` shows nothing underneath it, because there is nothing
+underneath it.
 
-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.
+## Install
 
-Three user-level Agent Skills over one local store:
+Two commands, and the second one is not optional — it creates the store and installs
+into every agent on the machine, in whatever format that tool reads:
+
+```bash
+npm install -g @vib795/agent-memory
+agent-memory setup
+```
+
+Node >= 22.5, and nothing else.
+
+In Claude Code you can take the three skills as a plugin instead of letting `setup`
+link them:
+
+```
+/plugin marketplace add vib795/agent-memory
+/plugin install agent-memory@vib795
+```
+
+The plugin carries the skills; `npm` carries the store. You want both — the skills
+will tell you so if you only have one.
+
+Behind a proxy that quarantines npm, or want the GitHub Packages mirror?
+[Every install path is here](#install-1).
+
+## What you get
+
+Three user-level Agent Skills over one local markdown store:
 
 | Skill | What it does |
 |---|---|
@@ -19,9 +47,23 @@ Three user-level Agent Skills over one local store:
 | `/remember` | Captures durable knowledge into a cross-repo graph — and fires on its own when a juncture passes |
 | `/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.
+The store is plain markdown in `~/.agents/memory/`, outside every repository — which
+is what lets a note written in one project be read from another. Nothing leaves the
+machine: no daemon, no scheduled task, no telemetry.
+
+**New here?** [HOWTO.md](HOWTO.md) — install, first five minutes, and the per-tool
+notes for Claude Code, Codex and Copilot.
+
+**How does it work?** [ARCHITECTURE.md](ARCHITECTURE.md) — the source-of-truth split,
+the write and read paths, the tiered context cost, and the invariants underneath.
+
+[![npm](https://img.shields.io/npm/v/@vib795/agent-memory)](https://www.npmjs.com/package/@vib795/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)
+[![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)
+[![dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)](package.json)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 ## Why this exists
 
@@ -472,7 +514,7 @@ Claude Code can take the same three as a plugin:
 
 ```
 /plugin marketplace add vib795/agent-memory
-/plugin install agent-memory@agent-memory
+/plugin install agent-memory@vib795
 ```
 
 The same caveat applies: the plugin carries the skills, `npm` carries the store.
@@ -499,7 +541,7 @@ 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.
 
-Run `npm test` for the suite (88 tests, no dependencies). CI runs it on Linux,
+Run `npm test` for the suite (91 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.5.2",
+  "version": "0.6.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",

package/skills/recall/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: recall
 version: 0.1.0
-description: "Durable project knowledge: 5 notes, 1 constraint across agent-memory. Topics: memory store is markdown with a disposable sqlite cache, chose node:sqlite over better-sqlite3, sqlite recursive cte is the graph engine. Use when you need to know how a system works, why a decision was made, what convention applies, or what the environment forbids."
+description: "Durable project knowledge store, currently empty. Run /remember to capture the first note. Use when you need to know how a system works, why a decision was made, what convention applies, or what the environment forbids."
 license: MIT
 allowed-tools: Bash Read
 triggers:

package/src/cli.js

@@ -75,7 +75,7 @@ function git(args, cwd = process.cwd()) {
 const USAGE = `agent-memory — durable cross-repo knowledge for coding agents
 
   setup                                  link all three skills, build the store
-                                         (runs automatically on npm install)
+                                         (run this once, by hand, after install)
   uninstall                              remove the skill links; keeps every note
   init [--skills "<p1>,<p2>"]            create the store; register skill files
   index                                  rebuild index.db from notes/
@@ -424,6 +424,9 @@ function cmdCompact() {
     ...r.malformed.map((m) => `warning: unparseable ${m.path}`),
     `digest ${r.digestChars} chars`,
     ...r.skills.map((s) => `updated description in ${s}`),
+    ...(r.skipped || []).map(
+      (s) => `skipped ${s}: inside this package's git checkout, so the file is tracked`
+    ),
   ].join('\n');
   return { ok: true, ...r, text };
 }

package/src/compact.js

@@ -1,4 +1,6 @@
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, sep } from 'node:path';
 import { loadConfig, paths } from './config.js';
 import { listNotes, archiveNote, contentHash, nowIso, serializeNote } from './store.js';
 import { atomicWrite } from './atomic.js';
@@ -149,8 +151,40 @@ function decay(active, cfg, now) {
  * reading its description, so regenerating that line is how the store advertises
  * what it now knows without costing anything at chat time.
  */
+// The directory this package was installed into. `setup` links skill directories at
+// `<package>/skills/<name>`, so every description write lands in the package's own
+// files. That is correct for an installed package and wrong for a git checkout, where
+// those files are tracked: one developer's digest gets committed and then published to
+// everyone. It shipped that way for twenty releases, advertising one machine's five
+// notes to every user who installed the plugin.
+const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url));
+
+/**
+ * Is this path inside the package's own git checkout?
+ *
+ * Resolved through `realpathSync` because the path arrives as a symlink planted by
+ * `setup`; the link sits outside the checkout even when its target is inside it, which
+ * is the whole reason this went unnoticed. The `.git` test separates a developer's
+ * working tree from an ordinary install, which has no `.git` and must keep being
+ * written to — that write is the Tier-1 mechanism, not a bug.
+ */
+export function insideCheckout(file) {
+  if (!existsSync(join(PACKAGE_ROOT, '.git'))) return false;
+  let real;
+  let root;
+  try {
+    real = realpathSync(file);
+    root = realpathSync(PACKAGE_ROOT);
+  } catch {
+    return false;
+  }
+  if (root.endsWith(sep)) root = root.slice(0, -1);
+  return real === root || real.startsWith(root + sep);
+}
+
 export function writeSkillDescription(skillPath, description) {
   if (!existsSync(skillPath)) return false;
+  if (insideCheckout(skillPath)) return false;
   const src = readFileSync(skillPath, 'utf8');
   if (!src.startsWith('---')) return false;
   const end = src.indexOf('\n---', 3);
@@ -185,10 +219,17 @@ function regenerate(db, cfg) {
   atomicWrite(paths.routing, routing);
 
   const skills = [];
+  const skipped = [];
   for (const p of cfg.skillPaths || []) {
+    // Reported, never swallowed. A description that silently did not update reads
+    // exactly like one that did, and this is the line that routes every recall.
+    if (insideCheckout(p)) {
+      skipped.push(p);
+      continue;
+    }
     if (writeSkillDescription(p, digest)) skills.push(p);
   }
-  return { digest, digestChars: digest.length, routing: paths.routing, skills };
+  return { digest, digestChars: digest.length, routing: paths.routing, skills, skipped };
 }
 
 /**

package/src/digest.js

@@ -59,7 +59,14 @@ export function buildDigest(db, { cfg = loadConfig() } = {}) {
   const cap = cfg.digestChars;
   const total = db.prepare('SELECT COUNT(*) AS c FROM nodes WHERE archived = 0').get().c;
   if (!total) {
-    return 'Durable project knowledge store, currently empty. Run /remember to capture the first note.';
+    // USE_WHEN belongs here too. This branch used to return without it, which stripped
+    // the routing triggers from Tier 1 on exactly the machines that need them most: a
+    // fresh install, where the store is empty and the skill still has to earn its
+    // first use. An empty store is a reason to say when to call recall, not to stop.
+    return (
+      'Durable project knowledge store, currently empty. ' +
+      `Run /remember to capture the first note. ${USE_WHEN}`
+    );
   }
 
   const constraints = db

package/src/promptfile.js

@@ -15,7 +15,7 @@ export const GENERATED_MARKER =
 
 /** Split a leading `---` frontmatter block from the body. */
 function splitFrontmatter(text) {
-  const src = String(text).replace(/^/, '').replace(/\r\n/g, '\n');
+  const src = String(text).replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
   if (!src.startsWith('---')) return { head: '', body: src.trim() };
   const end = src.indexOf('\n---', 3);
   if (end === -1) return { head: '', body: src.trim() };