@vib795/agent-memory 0.3.1 → 0.5.0

package/README.md

@@ -124,6 +124,89 @@ Two things are deliberately dropped on the way through:
 Importing the same file twice updates rather than duplicates, so re-running after a
 change is safe.
 
+### Sharing an export with another person
+
+Scope decides *whose* knowledge travels. It does not decide whether the file can be
+handed to a person, and those are separate questions. Every export is scanned for
+personal identifiers on the way out, and the file carries a receipt naming the rule
+set that ran and what it took.
+
+```
+$ agent-memory export --out carry.json
+Exported 41 global-scope notes to carry.json.
+rule set: pii/v1
+redacted: 6 phone, 2 payment-card, 1 ssn
+withheld: 1 note
+  oncall-roster — 8 identifiers (phone)
+
+Structured identifiers only. Have an agent review this file for names and
+identifying prose before sharing it outside your team.
+```
+
+Notes are **redacted in place**, so the knowledge survives and the identifier does
+not. A note that is *mostly* identifiers — a roster, a contact sheet — is withheld
+whole and named in the receipt, because a redacted skeleton is useless to the reader
+and still re-identifiable from the structure that remains.
+
+**Two layers, and the markers tell you which one acted.**
+
+| | Runs at | Asks | Marker |
+|---|---|---|---|
+| `src/redact.js` | capture | could this authenticate as someone? | `<redacted:kind>` |
+| `src/pii.js` | export | could this identify a person? | `[redacted:kind]` |
+
+They disagree about your own email address on purpose. Capture keeps it, because it
+is already public in every commit you have ever pushed. Export removes it, because it
+is not yours to hand to someone else alongside a hundred notes about how a client
+works.
+
+**What the deterministic layer does not catch.** Names, job titles, postal addresses
+and identifying prose have no shape to match on. They are language, and the honest
+place to judge them is the model already in the conversation — so the receipt says so
+instead of letting a pattern imply a completeness it does not have. Ask your agent to
+review the export before it leaves your team.
+
+## Evals and governance
+
+Disclosure control is a claim until it is measured, so it is measured on every run of
+`npm test`:
+
+```
+[pii/v1] recall by kind
+  email          2/2
+  ip-address     2/2
+  payment-card   3/3
+  phone          4/4
+  ssn            2/2
+[pii/v1] precision 15/15 on the negative corpus
+[pii/v1] 3 known gaps pass through by design: person name, postal address, bare internal identifier
+```
+
+The practices behind that number, which are the transferable part:
+
+- **Both error directions are costed, not just the obvious one.** A miss discloses one
+  identifier. A false hit shreds a sentence, and a tool that mangles ordinary prose
+  gets switched off, which discloses everything. Recall is held at 1.0 because no
+  number of leaked identifiers is acceptable; precision is held at 1.0 against a
+  corpus built to tempt each detector with what it most resembles — a git SHA for a
+  card, a four-part version for an address, a date for a phone number.
+- **Gaps are asserted as gaps.** `test/pii.eval.test.js` proves that names and
+  addresses pass through, so closing one has to be a deliberate act rather than a
+  silent change in what an old receipt meant.
+- **The eval is checked for teeth.** Removing the Luhn validation drops precision to
+  14/15 and fails the build. A green suite that cannot go red is decoration.
+- **Corpora are synthetic.** Reserved ranges only — RFC 5737 addresses, the card
+  networks' published test numbers — so the file that tests for leaks is not one.
+- **Rule sets are versioned.** A receipt means something only against the rules that
+  produced it, so `pii/v1` is stamped into every export and changing a detector
+  changes the name.
+
+For sharing outside your team: keep the receipt with the file, re-export rather than
+hand-editing a file you already sent, and treat `--scope all` as a decision with your
+name on it. What this is not: it is not encryption, access control, or a DLP product.
+It is one command that refuses to hand over identifiers, and it says exactly what it
+checked.
+
 ## Engagements
 
 If you work for more than one client on one machine, knowledge from one of them is
@@ -279,10 +362,11 @@ npm install -g ./agent-memory
 agent-memory setup
 ```
 
-**Do not install from the git URL directly.** `npm install -g <git-url>` fails for
-this package: npm links the package into `~/.npm/_cacache/tmp/git-clone*`, a
-directory it then cleans, and `postinstall` dies with `Cannot find module` before it
-can run. Cloning first avoids npm's git handling entirely. Verified on npm 11.18.
+**Do not install from the git URL directly.** `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.
 
 Every release is mirrored to **GitHub Packages**. Treat that as redundancy rather
 than a second front door: GitHub Packages requires authentication even for public
@@ -324,17 +408,16 @@ drift, and `compact` regenerates the routing digest into both.
 `agent-memory doctor` lists what it detected, so an install that appears to do
 nothing tells you whether your editor was missed or simply ignored the files.
 
-**Why it is not automatic.** There is a `postinstall` hook that does exactly this,
-but current npm refuses to run package install scripts unless you opt in per
-package, and prints only a warning when it skips them. Managed environments go
-further and set `ignore-scripts=true` globally. Rather than pretend, the second
-command is documented as part of the install. If you would rather have it automatic:
-
-```bash
-npm install -g --allow-scripts=@vib795/agent-memory @vib795/agent-memory
-```
+**Why it is not automatic.** Installing the package writes nothing to your machine.
+There is no `postinstall` hook, and its absence is a security decision rather than an
+omission: an install script that writes into *other* tools' agent directories —
+`~/.claude`, `~/.codex`, your editor's prompt folder — is mechanically
+indistinguishable from a supply-chain attack that hijacks an AI agent, and
+supply-chain scanners classify it as exactly that. Installing this package and
+granting it your agents are two separate decisions, so they are two commands.
+`agent-memory setup` is the one that asks.
 
-Either way `agent-memory doctor` tells you where you stand. It checks the files
+`agent-memory doctor` tells you where you stand. It checks the files
 rather than the tools, and names any agent it found that has no skills in it:
 
 ```
@@ -387,10 +470,9 @@ Note that `npm install -g .` from a clone *symlinks* rather than copies, so
 `skills/recall/SKILL.md` will show as modified. That is expected — the description
 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, and
-`postinstall` refuses rather than failing your install.
+Needs Node 22.5 or newer; `doctor` says so plainly if the version is too old.
 
-Run `npm test` for the suite (74 tests, no dependencies). CI runs it on Linux,
+Run `npm test` for the suite (87 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.3.1",
+  "version": "0.5.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",
@@ -27,19 +27,11 @@
   },
   "scripts": {
     "test": "node --test",
-    "postinstall": "node scripts/postinstall.js",
     "setup": "node src/cli.js setup"
   },
   "files": [
     "src/",
-    "scripts/",
     "skills/",
-    "install.sh",
-    "install.ps1",
-    "update.sh",
-    "update.ps1",
-    "uninstall.sh",
-    "uninstall.ps1",
     "README.md",
     "HOWTO.md",
     "LICENSE"

package/src/cli.js

@@ -17,6 +17,7 @@ import { setup as runSetup, unlinkSkills, danglingSkillLinks, SKILLS } from './s
 import { detectTargets, installableTargets } from './targets.js';
 import { join, dirname } from 'node:path';
 import { atomicWrite } from './atomic.js';
+import { redactNodeForExport, buildReceipt, renderReceipt } from './pii.js';
 
 /**
  * One process, one answer.
@@ -131,10 +132,10 @@ function cmdInit(opts) {
 /**
  * Link the skills into both agents and build the store.
  *
- * Runs automatically from npm postinstall, but exists as a command because managed
- * npm configurations often set `ignore-scripts=true`, which skips postinstall with
- * no warning. When that happens the recovery is one command rather than hunting for
- * a shell script inside a global node_modules directory.
+ * This is the only thing that writes into an agent's directory, and it only runs when
+ * a person types it. The package deliberately ships no install hook: writing into
+ * another tool's agent surface from an install script is the shape of a supply-chain
+ * agent hijack, whoever does it and for whatever reason.
  */
 function cmdSetup() {
   ensureStore();
@@ -496,10 +497,10 @@ function cmdDoctor() {
   );
 
   // Detection is not installation, and conflating them is how this tool reports
-  // healthy while doing nothing. npm gates postinstall scripts behind allow-scripts,
-  // and managed profiles set ignore-scripts=true; in both cases the CLI lands on PATH
-  // and every agent directory stays empty, while every other check here still passes.
-  // So verify the files, per agent, rather than trusting that setup ever ran.
+  // healthy while doing nothing. Installing the package does not install the skills;
+  // only `agent-memory setup` does, so the CLI routinely lands on PATH with every
+  // agent directory empty while every other check here still passes. Verify the
+  // files, per agent, rather than trusting that setup ever ran.
   const gaps = [];
   for (const t of installableTargets()) {
     const absent = SKILLS.filter((name) =>
@@ -581,6 +582,10 @@ const EXPORT_SCOPES = ['global', 'repo', 'all'];
  * `captured_sha` is deliberately dropped. It names a commit that does not exist
  * anywhere else, and a staleness signal that cannot be checked is worse than none:
  * it would either read as current forever or claim the history was rewritten.
+ *
+ * Personal identifiers are removed on the way out, and the export carries a receipt
+ * saying which rule set ran and what it took. Scope decides whose knowledge travels;
+ * the receipt decides whether it can be handed to a person.
  */
 function cmdExport(opts) {
   const scope = opts.scope === true ? 'global' : (opts.scope ?? 'global');
@@ -612,21 +617,42 @@ function cmdExport(opts) {
     source: n.source ?? 'manual',
   }));
 
-  const payload = `${JSON.stringify({ nodes }, null, 2)}\n`;
+  // Export is the only path by which the store leaves this machine, which makes it
+  // the only place disclosure control belongs. It is a different question from the
+  // one capture-time redaction answers, and src/pii.js says why at length.
+  const results = nodes.map((n) => ({ id: n.id, ...redactNodeForExport(n) }));
+  const clean = results.filter((r) => !r.withheld).map((r) => r.node);
+  const receipt = buildReceipt(results, { scanned: nodes.length });
+  const payload = `${JSON.stringify({ nodes: clean, redaction: receipt }, null, 2)}\n`;
+
   if (typeof opts.out === 'string') {
     atomicWrite(opts.out, payload);
     return {
       ok: true,
-      exported: nodes.length,
+      exported: clean.length,
+      withheld: receipt.withheld.length,
       scope,
       out: opts.out,
-      text: `Exported ${nodes.length} ${scope}-scope note${nodes.length === 1 ? '' : 's'} to ${opts.out}.`,
+      redaction: receipt,
+      text: [
+        `Exported ${clean.length} ${scope}-scope note${clean.length === 1 ? '' : 's'} to ${opts.out}.`,
+        ...renderReceipt(receipt),
+      ].join('\n'),
     };
   }
-  // Straight to stdout so it pipes, with the count on stderr where it will not
-  // corrupt the document.
-  process.stderr.write(`${nodes.length} ${scope}-scope notes\n`);
-  return { ok: true, exported: nodes.length, scope, nodes, text: payload.trimEnd() };
+  // Straight to stdout so it pipes, with the count and the receipt on stderr where
+  // they will not corrupt the document.
+  process.stderr.write(`${clean.length} ${scope}-scope notes\n`);
+  for (const line of renderReceipt(receipt)) process.stderr.write(`${line}\n`);
+  return {
+    ok: true,
+    exported: clean.length,
+    withheld: receipt.withheld.length,
+    scope,
+    nodes: clean,
+    redaction: receipt,
+    text: payload.trimEnd(),
+  };
 }
 
 /**

package/src/pii.js

@@ -0,0 +1,269 @@
+/**
+ * Disclosure control for export.
+ *
+ * This is not the same job as src/redact.js and must not be folded into it. That one
+ * runs at capture and asks "could this authenticate as someone?" — its threat is a
+ * credential reaching disk, and it deliberately preserves the operator's own email
+ * because that address is already public in every commit they have ever pushed.
+ *
+ * This one runs at export and asks "could this identify a person?" — its threat is a
+ * human reading the file. The operator's own email is the clearest case of the
+ * difference: safe to store, not yours to hand to someone else along with a hundred
+ * notes about how their client works.
+ *
+ * Two layers, and only one of them lives here. Structured identifiers have shape, so
+ * they are matched and validated deterministically, which makes them testable and the
+ * result reproducible from a named rule set. Names, addresses and identifying prose
+ * have no shape; they are language, and the honest place to judge them is the model
+ * already sitting in the conversation. The receipt says so out loud rather than
+ * letting a regex imply a completeness it does not have.
+ */
+
+/** Bump when a detector changes. A receipt is only reproducible against its rule set. */
+export const RULE_SET = 'pii/v1';
+
+/** Detections in one note before the note is withheld whole rather than redacted. */
+export const DEFAULT_WITHHOLD_COUNT = 8;
+
+/** Share of the text that may be replaced before redaction stops being meaningful. */
+export const DEFAULT_WITHHOLD_RATIO = 0.3;
+
+/** Luhn, the checksum every payment card carries. Turns a digit run into a card. */
+function luhnValid(digits) {
+  let sum = 0;
+  let double = false;
+  for (let i = digits.length - 1; i >= 0; i -= 1) {
+    let d = digits.charCodeAt(i) - 48;
+    if (d < 0 || d > 9) return false;
+    if (double) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    double = !double;
+  }
+  return sum % 10 === 0;
+}
+
+/**
+ * A US SSN has structure the Social Security Administration never issues.
+ * Checking it is what separates an SSN from any other nine digits with dashes.
+ */
+function ssnValid(area, group, serial) {
+  if (area === '000' || area === '666' || area[0] === '9') return false;
+  if (group === '00' || serial === '0000') return false;
+  return true;
+}
+
+function octetsValid(ip) {
+  const parts = ip.split('.');
+  return parts.length === 4 && parts.every((p) => p.length <= 3 && Number(p) <= 255);
+}
+
+/**
+ * Addresses that describe infrastructure rather than a person.
+ *
+ * The privacy interest in an IP is that a routable one, with a timestamp, can be put
+ * to a subscriber by whoever holds the logs. A pod CIDR cannot. Capture-time
+ * redaction already removes these ranges as infrastructure, so scrubbing them again
+ * here would only cost meaning in ordinary engineering notes.
+ */
+function reservedV4(ip) {
+  const [a, b] = ip.split('.').map(Number);
+  if (a === 0 || a === 10 || a === 127 || a >= 224) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  return false;
+}
+
+/**
+ * Every detector is precision-first.
+ *
+ * A false negative leaks one identifier. A false positive shreds a sentence, and a
+ * tool that mangles ordinary prose gets switched off, which leaks everything. So each
+ * pattern here carries a checksum, a structural rule, or a separator requirement that
+ * ordinary technical writing does not satisfy. Bare digit runs are left to the
+ * semantic pass rather than guessed at, because a git SHA, an order number and a
+ * national ID are the same characters.
+ *
+ * Order is load-bearing. A grouped card number is also a valid phone shape, so cards
+ * are consumed before phones get a chance; reordering this array silently changes
+ * what the labels say happened.
+ */
+const DETECTORS = [
+  {
+    kind: 'email',
+    // No self-address exemption. That exemption is correct at capture and wrong here.
+    re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+  },
+  {
+    kind: 'ssn',
+    // Only the delimited form. Nine adjacent digits are too many other things.
+    re: /(?<![\w-])(\d{3})-(\d{2})-(\d{4})(?![\w-])/g,
+    validate: (m) => ssnValid(m[1], m[2], m[3]),
+  },
+  {
+    kind: 'payment-card',
+    re: /(?<![\w-])(?:\d[ -]?){12,18}\d(?![\w-])/g,
+    validate: (m) => {
+      const digits = m[0].replace(/\D/g, '');
+      return digits.length >= 13 && digits.length <= 19 && luhnValid(digits);
+    },
+  },
+  {
+    kind: 'phone',
+    // Requires separators or a country code, so `10.2.4` and `v1.2.3` cannot match,
+    // and a bare run of ten digits is left alone on purpose.
+    re: /(?<![\w-])(?:\+\d{1,3}[\s.-]?)?(?:\(\d{2,4}\)|\d{2,4})[\s.-]\d{2,4}[\s.-]\d{2,5}(?:[\s.-]\d{1,5})?(?![\w-])/g,
+    validate: (m) => {
+      const digits = m[0].replace(/\D/g, '');
+      if (digits.length < 10 || digits.length > 15) return false;
+      // One repeated digit is a placeholder or a masked field, never a number.
+      if (/^(\d)\1+$/.test(digits)) return false;
+      // A date reads as three separated numbers too. Reject anything shaped like one
+      // rather than deciding by punctuation, which varies by locale.
+      return !/^\d{4}[.\-/]\d{1,2}[.\-/]\d{1,2}$/.test(m[0].trim());
+    },
+  },
+  {
+    kind: 'ip-address',
+    // Capture-time redaction removes RFC1918 ranges as infrastructure. A routable
+    // address is the one that can identify a subscriber, and it survives to here.
+    re: /(?<![\w.])\d{1,3}(?:\.\d{1,3}){3}(?![\w.])/g,
+    validate: (m) => {
+      if (!octetsValid(m[0])) return false;
+      // Four single-digit groups is a four-part version string (6.0.1.2) far more
+      // often than an address. A deliberate recall gap, measured in the eval and
+      // covered by the semantic pass rather than paid for in shredded prose.
+      if (/^\d(\.\d){3}$/.test(m[0])) return false;
+      return !reservedV4(m[0]);
+    },
+  },
+];
+
+/**
+ * Scan text, returning the redacted form and what fired.
+ *
+ * Fail-closed in the same sense as capture: a non-string is a programming error, and
+ * returning it unscanned would be the one outcome worse than throwing.
+ */
+export function scanText(text) {
+  if (typeof text !== 'string') {
+    throw new TypeError('scanText() requires a string; refusing to export unscanned content');
+  }
+  const counts = new Map();
+  let redactedChars = 0;
+  let out = text;
+
+  for (const { kind, re, validate } of DETECTORS) {
+    out = out.replace(re, (...args) => {
+      const match = args.slice(0, -2);
+      const whole = match[0];
+      if (validate && !validate(match)) return whole;
+      counts.set(kind, (counts.get(kind) || 0) + 1);
+      redactedChars += whole.length;
+      return `[redacted:${kind}]`;
+    });
+  }
+
+  return {
+    text: out,
+    findings: [...counts.entries()].map(([kind, count]) => ({ kind, count })),
+    redactedChars,
+  };
+}
+
+/**
+ * Clean one node for export, or decide it cannot be cleaned.
+ *
+ * Withholding is not a fallback for a broken redactor; it answers a different
+ * question. A note that is mostly identifiers is a contact record rather than
+ * knowledge, and its redacted skeleton is both useless to the reader and still
+ * re-identifiable from the structure that remains. Better to name it in the receipt
+ * and leave it behind.
+ */
+export function redactNodeForExport(node, opts = {}) {
+  const withholdCount = opts.withholdCount ?? DEFAULT_WITHHOLD_COUNT;
+  const withholdRatio = opts.withholdRatio ?? DEFAULT_WITHHOLD_RATIO;
+
+  const clean = { ...node };
+  const counts = new Map();
+  let redactedChars = 0;
+  let textChars = 0;
+
+  for (const field of ['title', 'body']) {
+    if (typeof clean[field] !== 'string') continue;
+    textChars += clean[field].length;
+    const r = scanText(clean[field]);
+    clean[field] = r.text;
+    redactedChars += r.redactedChars;
+    for (const f of r.findings) counts.set(f.kind, (counts.get(f.kind) || 0) + f.count);
+  }
+
+  const findings = [...counts.entries()].map(([kind, count]) => ({ kind, count }));
+  const total = findings.reduce((n, f) => n + f.count, 0);
+  const ratio = textChars ? redactedChars / textChars : 0;
+
+  if (total >= withholdCount || ratio > withholdRatio) {
+    return {
+      node: null,
+      findings,
+      withheld: true,
+      reason:
+        total >= withholdCount ? `${total} identifiers` : `${Math.round(ratio * 100)}% of the text`,
+    };
+  }
+  return { node: clean, findings, withheld: false, reason: null };
+}
+
+/**
+ * Fold per-note results into the receipt that ships with the export.
+ *
+ * The receipt is the governance artifact. An export without one is a file of unknown
+ * provenance, and the reason to write it down is that "we redact PII" is a claim
+ * while "pii/v1 removed four emails and withheld two notes" is evidence.
+ */
+export function buildReceipt(results, { scanned }) {
+  const counts = new Map();
+  const withheld = [];
+  for (const r of results) {
+    for (const f of r.findings) counts.set(f.kind, (counts.get(f.kind) || 0) + f.count);
+    if (r.withheld) {
+      withheld.push({ id: r.id, reason: r.reason, kinds: r.findings.map((f) => f.kind) });
+    }
+  }
+  const redactions = [...counts.entries()]
+    .map(([kind, count]) => ({ kind, count }))
+    .sort((a, b) => b.count - a.count || a.kind.localeCompare(b.kind));
+
+  return {
+    ruleSet: RULE_SET,
+    scanned,
+    exported: scanned - withheld.length,
+    redactions,
+    withheld,
+    // Stated in the artifact rather than only in the docs, because the person who
+    // reads the receipt is the person deciding whether to send the file.
+    semanticReviewRequired:
+      'Structured identifiers only. Names, job titles, addresses and identifying prose are not detected here; have an agent review the export before sharing it outside your team.',
+  };
+}
+
+/** The receipt as lines, for the humans who will read it in a terminal. */
+export function renderReceipt(receipt) {
+  const out = [`rule set: ${receipt.ruleSet}`];
+  if (receipt.redactions.length) {
+    out.push(`redacted: ${receipt.redactions.map((r) => `${r.count} ${r.kind}`).join(', ')}`);
+  } else {
+    out.push('redacted: nothing matched');
+  }
+  if (receipt.withheld.length) {
+    out.push(`withheld: ${receipt.withheld.length} note${receipt.withheld.length === 1 ? '' : 's'}`);
+    for (const w of receipt.withheld) out.push(`  ${w.id} — ${w.reason} (${w.kinds.join(', ')})`);
+  }
+  out.push('');
+  out.push('Structured identifiers only. Have an agent review this file for names and');
+  out.push('identifying prose before sharing it outside your team.');
+  return out;
+}

package/src/setup.js

@@ -11,8 +11,8 @@ import { toPromptFile, isGenerated } from './promptfile.js';
 /**
  * Installation, in Node rather than in two shell scripts.
  *
- * This is the single implementation behind three entry points: `npm install` via
- * postinstall, `agent-memory setup`, and install.sh / install.ps1. Writing it once
+ * This is the single implementation behind both entry points: `agent-memory setup`,
+ * and install.sh / install.ps1 which are thin wrappers over it. Writing it once
  * matters because the machine that has to run it is a Windows desktop this was never
  * developed on, and a PowerShell copy of this logic would drift silently.
  *
@@ -207,8 +207,8 @@ export function setup({ compactFn } = {}) {
   const existing = (loadConfig().skillPaths || []).filter((p) => existsSync(p));
   saveConfig({ skillPaths: [...new Set([...existing, ...skillPaths])] });
 
-  // compact is passed in so this module does not pull the database, and the whole
-  // npm postinstall path with it, into memory just to make some symlinks.
+  // compact is passed in so this module does not pull the database into memory just
+  // to make some symlinks.
   const result = compactFn ? compactFn() : null;
   return {
     targets,

package/install.ps1

@@ -1,71 +0,0 @@
-<#
-.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 writes its warnings to stderr, and `2>&1` turns each one into an ErrorRecord,
-# which $ErrorActionPreference = 'Stop' then treats as terminating. A managed npm
-# config makes that certain rather than unlikely: an unknown key such as `always-auth`
-# produces a warning on every single npm invocation, so this step could never succeed
-# on the desktops this script exists for. It aborted the whole install — no fallback
-# message, no doctor, no closing instructions — over a warning about an unrelated
-# config key. Scope the preference to this one call.
-$previousPreference = $ErrorActionPreference
-$ErrorActionPreference = 'Continue'
-try {
-    & npm install -g $source 2>&1 | Out-Null
-    $npmExit = $LASTEXITCODE
-} catch {
-    $npmExit = 1
-} finally {
-    $ErrorActionPreference = $previousPreference
-}
-
-if ($npmExit -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

@@ -1,36 +0,0 @@
-#!/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/scripts/postinstall.js

@@ -1,45 +0,0 @@
-#!/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/uninstall.ps1

@@ -1,54 +0,0 @@
-<#
-.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

@@ -1,39 +0,0 @@
-#!/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

@@ -1,45 +0,0 @@
-<#
-.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

@@ -1,26 +0,0 @@
-#!/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"