@vib795/agent-memory 0.6.3 → 0.6.5

package/README.md

@@ -427,15 +427,31 @@ GitHub, and it is the path to use behind a proxy that blocks or quarantines npm:
 
 ```bash
 git clone https://github.com/vib795/agent-memory.git
-npm install -g ./agent-memory
+cd agent-memory && npm pack
+npm install -g ./vib795-agent-memory-*.tgz
 agent-memory setup
 ```
 
-**Do not install from the git URL directly.** `npm install -g <git-url>` does not
+**Pack first; do not install the directory.** `npm install -g ./agent-memory` looks
+equivalent and is not: npm links the global install to that folder rather than copying
+it, which shows up as an arrow in `npm list -g`:
+
+```
+`-- @vib795/agent-memory@0.6.5 -> .\..\..\..\agent-memory
+```
+
+Move or delete the clone afterwards and the global install points at nothing — the same
+breakage as the git-URL case below, arriving later and harder to trace. Installing a
+packed tarball copies, so the clone becomes disposable. Verified on npm 11.x.
+
+**Do not install from the git URL directly either.** `npm install -g <git-url>` does not
 work for this package: npm resolves a git install through
 `~/.npm/_cacache/tmp/git-clone*` and then removes that directory, leaving the global
-install pointing at a path that no longer exists. Cloning first avoids npm's git
-handling entirely. Verified on npm 11.18.
+install pointing at a path that no longer exists. Verified on npm 11.18.
+
+**And run the installed binary, not the checkout.** Skill links resolve relative to the
+code that creates them, so `npm run setup` inside a clone aims every link at that clone.
+Use `agent-memory setup`, which runs the copy npm installed.
 
 Every release is mirrored to **GitHub Packages**. Treat that as redundancy rather
 than a second front door: GitHub Packages requires authentication even for public

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vib795/agent-memory",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "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/handoff/SKILL.md

@@ -129,6 +129,12 @@ repos:
 agent: copilot | claude-code
 ---
 
+> **If the repository you are reading this in is not listed under `repos:` above, you are
+> replicating this work, not continuing it.** Follow Execution protocol, re-derive every
+> path, branch name and version from the repository you are actually in, and read Next
+> action as a record of what happened elsewhere rather than as an instruction. Do not open
+> the repository this was written in.
+
 ## Orientation
 
 3 to 5 sentences. What this thread is trying to accomplish and where it stands.
@@ -193,7 +199,9 @@ These separate a useful handoff from a readable paragraph that still leaves ques
 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.
+   of throwing" is not. When the thread spans more than one repository, name the repo
+   alongside the path: an unqualified path in a two-repo thread is a path the reader
+   goes looking for in the wrong tree, and finding it there is worse than not finding it.
 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.
@@ -296,8 +304,15 @@ request, which is the only reason this step belongs here rather than in its own
 - 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.
+Your Decisions table, Constraints section and **Execution protocol** are usually already
+the durable part. Write the protocol as a `convention`: it is the section a second
+repository actually needs, and the one most easily lost, because a sequence of steps
+reads like status even when it describes how every run of this kind is done. A handoff
+that records the protocol while the graph does not still leaves the next repository
+guessing — the handoff is read once, by whoever was handed the path, and the graph is
+what `/recall` reaches for afterwards.
+
+The Current task state section never is durable.
 
 ### Write it (ONE terminal call)
 

package/skills/recall/SKILL.md

@@ -62,6 +62,11 @@ 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.
+- When the question is about **doing** the work rather than understanding it, also
+  include the `convention` that governs how that kind of work is executed. A constraint
+  tells you which steps are forbidden; only a procedure tells you what order the allowed
+  ones go in. Branch choreography and deploy ordering live here, and they are what a
+  second repository gets wrong when nobody surfaces them.
 - Nothing in the tree looks relevant → go to Step 4.
 
 ---

package/src/cli.js

@@ -15,7 +15,8 @@ import { compact, maybeCompact } from './compact.js';
 import { staleness, currentRepo, reviewCandidates, captureGap } from './staleness.js';
 import { setup as runSetup, unlinkSkills, danglingSkillLinks, SKILLS } from './setup.js';
 import { detectTargets, installableTargets } from './targets.js';
-import { join, dirname } from 'node:path';
+import { join, dirname, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { atomicWrite } from './atomic.js';
 import { redactNodeForExport, buildReceipt, renderReceipt } from './pii.js';
 
@@ -29,6 +30,41 @@ import { redactNodeForExport, buildReceipt, renderReceipt } from './pii.js';
 
 const MIN_NODE = [22, 5];
 
+/**
+ * Where this process is actually running from, and what version it is.
+ *
+ * "What am I running" is the first question in every install problem and used to need
+ * `npm list -g` to answer, which reports what npm believes rather than what is on PATH.
+ * These read the package next to the running code, so they answer for the copy that
+ * will actually execute.
+ */
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..');
+}
+
+function installedVersion() {
+  try {
+    return JSON.parse(readFileSync(join(packageRoot(), 'package.json'), 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Whether the running code lives outside any `node_modules` tree.
+ *
+ * `npm install -g <folder>` links rather than copies, so a global install can be a
+ * pointer at a checkout the user will eventually tidy away — and skill links, which
+ * resolve relative to this file, follow it there. Node resolves symlinks before it sets
+ * `import.meta.url`, so the link itself is already invisible from in here; what stays
+ * visible, and is the thing that actually matters, is that the code is not sitting in an
+ * installed package. Running from a working copy is legitimate, so this reports the
+ * condition rather than failing on it.
+ */
+function runningFromWorkingCopy() {
+  return !packageRoot().split(sep).includes('node_modules');
+}
+
 function parseArgs(argv) {
   const opts = { _: [] };
   for (let i = 0; i < argv.length; i++) {
@@ -93,6 +129,8 @@ const USAGE = `agent-memory — durable cross-repo knowledge for coding agents
   engagement [show|list|use <name>]      which client store this window writes to
              [purge <name> --yes]        delete one engagement's store entirely
 
+  --version                              this version, and the path it runs from
+
 Add --json to any command for machine-readable output.
 Engagement: ${ENGAGEMENT.name} (${ENGAGEMENT.source})
 Store: ${paths.root}`;
@@ -164,6 +202,26 @@ function cmdSetup() {
     );
   }
 
+  // Naming what did not install is the whole point. A run that silently installs
+  // eleven of twelve reads as a success and sends the user back to an editor that is
+  // still missing a skill.
+  if (r.failed.length) {
+    lines.push('', '  Failed:');
+    for (const f of r.failed) lines.push(`    [failed] ${f.path} — ${f.error}`);
+    lines.push(
+      '',
+      '  A path that will not clear is usually a leftover link from an install that has',
+      '  since moved. `agent-memory uninstall` reclaims those, then run setup again.',
+    );
+  }
+  if (r.compactError) {
+    lines.push(
+      '',
+      `  Skills are installed, but refreshing the /recall description failed: ${r.compactError}`,
+      '  Run `agent-memory index` then `agent-memory compact` to retry just that step.',
+    );
+  }
+
   return {
     ok: true,
     ...r,
@@ -440,6 +498,25 @@ function cmdDoctor() {
   // reading it against the wrong client is the mistake this is here to prevent.
   add('engagement', true, `${ENGAGEMENT.name} (${ENGAGEMENT.source})`);
 
+  // Second, because "which version is this" preceded every other question in the one
+  // install failure this tool has actually been debugged through, and answering it
+  // needed a separate npm command that reports what npm believes rather than what ran.
+  add('version', true, `${installedVersion()} at ${packageRoot()}`);
+
+  // Skill links point at whatever copy of the code creates them. When that copy is a
+  // working directory rather than an installed package, deleting the directory dangles
+  // every link at once — which is exactly how this tool's own skill links were lost.
+  // Reported, not failed: running from a checkout is a normal thing to do deliberately.
+  add(
+    'runs from an installed package',
+    true,
+    runningFromWorkingCopy()
+      ? `no — working copy at ${packageRoot()}; skill links will point here, so moving or ` +
+        'deleting it breaks them. For a durable install: `npm pack` then ' +
+        '`npm install -g <tgz>`, and re-run setup.'
+      : 'yes',
+  );
+
   add('node version', nodeVersionOk(), `${process.versions.node} (need >= ${MIN_NODE.join('.')})`);
   if (!nodeVersionOk()) {
     return {
@@ -913,6 +990,12 @@ function main(argv) {
     process.stdout.write(`${USAGE}\n`);
     return 0;
   }
+  if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
+    // Prints the path as well as the number. A version alone cannot tell you that the
+    // binary on PATH belongs to a different install than the one you just upgraded.
+    process.stdout.write(`${installedVersion()}\n${packageRoot()}\n`);
+    return 0;
+  }
   const fn = COMMANDS[cmd];
   if (!fn) {
     process.stderr.write(`Unknown command ${JSON.stringify(cmd)}.\n\n${USAGE}\n`);

package/src/setup.js

@@ -55,11 +55,45 @@ function clear(path) {
       // end stay put — which is exactly what passing `recursive` here would risk.
       rmdirSync(path);
     }
+    // `force` tells rmSync to swallow ENOENT, and a junction whose target is gone can
+    // answer the stat rmSync makes with ENOENT while the reparse point itself stays on
+    // disk. The removal then reports success and changes nothing, after which
+    // symlinkSync fails EEXIST and the copy fallback lands on a path that still
+    // exists. Checking is what turns that silent no-op into an error naming the path.
+    if (isLink(path)) rmdirSync(path);
   } else if (existsSync(path)) {
     rmSync(path, { recursive: true, force: true });
   }
 }
 
+/**
+ * Decide whether a skill link at a path we manage was put there by this tool.
+ *
+ * Identity cannot be "points at where we live right now". An install that has since
+ * moved, or a checkout that was deleted, leaves a link that test would disown — and a
+ * disowned link is unreclaimable: `uninstall` keeps it as "not ours" and `setup`
+ * cannot replace what it will not clear, so the user is left holding a broken link
+ * that no command in this tool will fix.
+ */
+function ownsLink(link, name) {
+  let dest;
+  try {
+    dest = resolve(readlinkSync(link));
+  } catch {
+    // A link sitting at one of our paths whose target cannot even be read is ours to
+    // clear. Nothing downstream can use it either.
+    return true;
+  }
+  if (dest === join(packagedSkillsDir(), name)) return true;
+  // Dangling. Nothing is lost by reclaiming a link that points nowhere, and leaving it
+  // is precisely what deadlocks both commands.
+  if (!existsSync(dest)) return true;
+  // Live, but pointing into some other agent-memory tree — an older global install, or
+  // a checkout the user set up from. The signature is that its parent holds all three
+  // of our skills, which a hand-written skill directory would not.
+  return SKILLS.every((s) => existsSync(join(dirname(dest), s, 'SKILL.md')));
+}
+
 /**
  * Link one skill into one agent directory.
  *
@@ -130,7 +164,6 @@ export function danglingSkillLinks() {
  * that indexed them; removing them is a separate, deliberate act.
  */
 export function unlinkSkills() {
-  const packaged = packagedSkillsDir();
   const removed = [];
   const kept = [];
 
@@ -141,11 +174,9 @@ export function unlinkSkills() {
         if (!existsSync(link) && !isLink(link)) continue;
         let owned = false;
         try {
-          owned = isLink(link)
-            ? resolve(readlinkSync(link)) === join(packaged, name)
-            : existsSync(join(link, 'SKILL.md'));
+          owned = isLink(link) ? ownsLink(link, name) : existsSync(join(link, 'SKILL.md'));
         } catch {
-          // A link we cannot read is a link we cannot claim. Leave it.
+          // A directory we cannot stat is one we cannot claim. Leave it.
           owned = false;
         }
         if (owned) {
@@ -182,15 +213,30 @@ export function setup({ compactFn } = {}) {
   const targets = installableTargets();
   const installed = [];
   const copies = [];
+  const failed = [];
 
   for (const target of targets) {
     for (const name of SKILLS) {
-      const r =
-        target.kind === 'skill-dir'
-          ? linkSkill(name, target.dir)
-          : writePromptFile(name, target.dir);
-      installed.push({ ...r, target: target.id, label: target.label });
-      if (r.mode === 'copy') copies.push(r);
+      // Isolated per skill. One unwritable target used to abort the whole run and
+      // discard the report with it, so a user whose `.copilot` link was wedged got no
+      // output at all and no hint that the other eleven had been fine. A failure here
+      // is data to print, not a reason to stop.
+      try {
+        const r =
+          target.kind === 'skill-dir'
+            ? linkSkill(name, target.dir)
+            : writePromptFile(name, target.dir);
+        installed.push({ ...r, target: target.id, label: target.label });
+        if (r.mode === 'copy') copies.push(r);
+      } catch (err) {
+        failed.push({
+          name,
+          target: target.id,
+          label: target.label,
+          path: join(target.dir, target.kind === 'skill-dir' ? name : `${name}.prompt.md`),
+          error: err.message,
+        });
+      }
     }
   }
 
@@ -209,11 +255,25 @@ export function setup({ compactFn } = {}) {
 
   // compact is passed in so this module does not pull the database into memory just
   // to make some symlinks.
-  const result = compactFn ? compactFn() : null;
+  //
+  // Its failure must not sink the run. Linking is already done and written to disk by
+  // this point, so throwing here would throw away an accurate report of work that
+  // actually happened and leave the user with no idea any of it succeeded. compact
+  // touches every registered skill path, which is exactly the set most likely to hold
+  // a stale entry, so it is the step most likely to throw.
+  let result = null;
+  let compactError = null;
+  try {
+    result = compactFn ? compactFn() : null;
+  } catch (err) {
+    compactError = err.message;
+  }
   return {
     targets,
     installed,
     copies,
+    failed,
+    compactError,
     skillPaths,
     home: agentHome(),
     digest: result?.digest ?? null,