@vib795/agent-memory 0.1.0

package/src/setup.js

@@ -0,0 +1,211 @@
+import {
+  mkdirSync, rmSync, existsSync, lstatSync, symlinkSync, cpSync, readlinkSync, readFileSync,
+} from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { saveConfig, loadConfig } from './config.js';
+import { agentHome, installableTargets } from './targets.js';
+import { atomicWrite } from './atomic.js';
+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
+ * 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.
+ *
+ * Two formats are written, because the tools disagree about what a skill is. Agent
+ * skills are directories containing SKILL.md and get linked. VS Code prompt files are
+ * single `<name>.prompt.md` files and get written. Both are derived from the same
+ * skills/ directory, so there is still one source of truth.
+ */
+
+export const SKILLS = ['handoff', 'recall', 'remember'];
+
+/** Where the packaged skills live, whether installed globally or run from a checkout. */
+export function packagedSkillsDir() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+}
+
+/** Skill directories only. Kept for the dangling-link check and for uninstall. */
+export function skillTargets() {
+  return installableTargets().filter((t) => t.kind === 'skill-dir').map((t) => t.dir);
+}
+
+function isLink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function clear(path) {
+  // A stale symlink must be removed as a link rather than followed, or clearing it
+  // would delete the packaged skills on the other end.
+  if (isLink(path)) rmSync(path, { force: true });
+  else if (existsSync(path)) rmSync(path, { recursive: true, force: true });
+}
+
+/**
+ * Link one skill into one agent directory.
+ *
+ * 'junction' makes a directory junction on Windows, which needs neither admin rights
+ * nor Developer Mode, and is ignored on POSIX where an ordinary symlink is made.
+ * Junctions still fail on a network-backed profile (FSLogix, roaming), so there is a
+ * copy fallback and the caller is told which one it got.
+ */
+export function linkSkill(name, targetDir) {
+  const source = join(packagedSkillsDir(), name);
+  const link = join(targetDir, name);
+  mkdirSync(targetDir, { recursive: true });
+  clear(link);
+  try {
+    symlinkSync(source, link, 'junction');
+    return { name, path: link, mode: 'link' };
+  } catch (err) {
+    cpSync(source, link, { recursive: true });
+    return { name, path: link, mode: 'copy', reason: err.message };
+  }
+}
+
+/**
+ * Write one skill as a VS Code prompt file.
+ *
+ * Written rather than linked: prompt files are single files, and a symlinked one is
+ * not reliably picked up across VS Code's file watching. The cost is that an upgrade
+ * needs `agent-memory setup` re-run, which the installer says out loud.
+ */
+export function writePromptFile(name, targetDir) {
+  const source = join(packagedSkillsDir(), name, 'SKILL.md');
+  const dest = join(targetDir, `${name}.prompt.md`);
+  mkdirSync(targetDir, { recursive: true });
+  atomicWrite(dest, toPromptFile(readFileSync(source, 'utf8'), { name }));
+  return { name, path: dest, mode: 'prompt' };
+}
+
+/**
+ * Skill links whose target no longer exists.
+ *
+ * npm 7 dropped support for uninstall lifecycle hooks, so `npm uninstall -g` deletes
+ * the package and leaves these behind with nothing to clean them up — and by then the
+ * binary that would have done it is gone too. Detecting them is the only remedy left,
+ * and a broken skill an agent keeps trying to load is worth naming out loud.
+ */
+export function danglingSkillLinks() {
+  const out = [];
+  for (const name of SKILLS) {
+    for (const dir of skillTargets()) {
+      const link = join(dir, name);
+      // existsSync follows the link, so a true isLink with a false existsSync is
+      // exactly the broken case and nothing else.
+      if (isLink(link) && !existsSync(link)) out.push(link);
+    }
+  }
+  return out;
+}
+
+/**
+ * Remove everything this package installed, in both formats.
+ *
+ * Only entries that are ours are removed: a skill directory is ours if it resolves
+ * back to this package, and a prompt file is ours if it carries the generated marker.
+ * Someone may have written their own `recall.prompt.md`, and deleting it because the
+ * name matched would be destroying work we were never asked to manage.
+ *
+ * The store is never touched. Notes are the user's own writing and outlive the tool
+ * that indexed them; removing them is a separate, deliberate act.
+ */
+export function unlinkSkills() {
+  const packaged = packagedSkillsDir();
+  const removed = [];
+  const kept = [];
+
+  for (const target of installableTargets()) {
+    for (const name of SKILLS) {
+      if (target.kind === 'skill-dir') {
+        const link = join(target.dir, name);
+        if (!existsSync(link) && !isLink(link)) continue;
+        let owned = false;
+        try {
+          owned = isLink(link)
+            ? resolve(readlinkSync(link)) === join(packaged, name)
+            : existsSync(join(link, 'SKILL.md'));
+        } catch {
+          // A link we cannot read is a link we cannot claim. Leave it.
+          owned = false;
+        }
+        if (owned) {
+          clear(link);
+          removed.push(link);
+        } else {
+          kept.push(link);
+        }
+      } else {
+        const file = join(target.dir, `${name}.prompt.md`);
+        if (!existsSync(file)) continue;
+        if (isGenerated(readFileSync(file, 'utf8'))) {
+          rmSync(file, { force: true });
+          removed.push(file);
+        } else {
+          kept.push(file);
+        }
+      }
+    }
+  }
+  return { removed, kept };
+}
+
+/**
+ * Install into every agent present on this machine, then build the store.
+ *
+ * Only `recall` is registered for description regeneration. `compact` overwrites the
+ * description of every path it is given, and handoff and remember describe
+ * themselves; registering all three would replace two good descriptions with a third.
+ * Copies and prompt files register their own path, because rewriting the packaged
+ * original would never reach them.
+ */
+export function setup({ compactFn } = {}) {
+  const targets = installableTargets();
+  const installed = [];
+  const copies = [];
+
+  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);
+    }
+  }
+
+  const skillPaths = [
+    join(packagedSkillsDir(), 'recall', 'SKILL.md'),
+    ...copies.filter((c) => c.name === 'recall').map((c) => join(c.path, 'SKILL.md')),
+    ...installed.filter((i) => i.mode === 'prompt' && i.name === 'recall').map((i) => i.path),
+  ];
+  // Drop registrations whose file is gone before adding the current ones. Renaming
+  // the checkout, moving it, or reinstalling under a different prefix each leave a
+  // path that no longer resolves, and a union that never prunes keeps it forever --
+  // after which compact writes to a file that is not there and doctor reports a
+  // failure while naming the path that is fine.
+  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.
+  const result = compactFn ? compactFn() : null;
+  return {
+    targets,
+    installed,
+    copies,
+    skillPaths,
+    home: agentHome(),
+    digest: result?.digest ?? null,
+    notes: result?.indexed ?? 0,
+  };
+}

package/src/staleness.js

@@ -0,0 +1,151 @@
+import { execFileSync } from 'node:child_process';
+import { basename } from 'node:path';
+import { loadConfig } from './config.js';
+
+/**
+ * Staleness detection.
+ *
+ * A `system` note claiming "auth uses JWT" after the code moved to sessions is
+ * worse than no memory at all, because it misleads with confidence. This module
+ * cannot prevent that. What it does is make the age of a note visible at the exact
+ * moment the note is being used, which is the only moment anyone can act on it.
+ *
+ * Deterministic, no model involved, no scheduled job: just a commit count.
+ */
+
+const cache = new Map();
+
+function git(args, cwd) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 5000,
+  }).trim();
+}
+
+/** Repository name for the working directory, or null when not inside one. */
+export function currentRepo(cwd = process.cwd()) {
+  const key = `repo\0${cwd}`;
+  if (cache.has(key)) return cache.get(key);
+  let repo = null;
+  try {
+    repo = basename(git(['rev-parse', '--show-toplevel'], cwd));
+  } catch {
+    repo = null;
+  }
+  cache.set(key, repo);
+  return repo;
+}
+
+/**
+ * How many commits have landed since `sha`.
+ *
+ * Reachability is checked first so that a rebased or pruned commit reports
+ * `unreachable` instead of surfacing a git error to someone who only asked a
+ * question about their own codebase.
+ */
+export function commitsSince(sha, cwd = process.cwd()) {
+  if (!sha) return { status: 'no-sha' };
+  const key = `count\0${cwd}\0${sha}`;
+  if (cache.has(key)) return cache.get(key);
+
+  let result;
+  try {
+    git(['rev-parse', '--git-dir'], cwd);
+  } catch (err) {
+    result = { status: err.code === 'ENOENT' ? 'no-git' : 'no-repo' };
+    cache.set(key, result);
+    return result;
+  }
+
+  try {
+    git(['cat-file', '-e', `${sha}^{commit}`], cwd);
+  } catch {
+    result = { status: 'unreachable' };
+    cache.set(key, result);
+    return result;
+  }
+
+  try {
+    const count = Number.parseInt(git(['rev-list', '--count', `${sha}..HEAD`], cwd), 10);
+    result = Number.isFinite(count) ? { status: 'ok', count } : { status: 'unreachable' };
+  } catch {
+    // Reachable but not countable: HEAD may be unborn on a fresh repository.
+    result = { status: 'unreachable' };
+  }
+  cache.set(key, result);
+  return result;
+}
+
+/**
+ * The annotation for a node, or null when there is nothing worth saying.
+ *
+ * Only annotates when the current repository is one the note claims, because a
+ * commit count taken against unrelated history is noise dressed as a signal. A note
+ * scoped to another project is left alone rather than flagged as rewritten.
+ */
+export function annotate(node, { cwd = process.cwd(), cfg = loadConfig(), repo } = {}) {
+  if (!node?.captured_sha) return null;
+  const here = repo ?? currentRepo(cwd);
+  if (!here) return null;
+  if (Array.isArray(node.repos) && node.repos.length && !node.repos.includes(here)) return null;
+
+  const res = commitsSince(node.captured_sha, cwd);
+  if (res.status === 'unreachable') return 'history rewritten, verify';
+  if (res.status !== 'ok') return null;
+  if (res.count < cfg.staleAnnotateCommits) return null;
+  return `captured ${res.count} commits ago — verify before trusting`;
+}
+
+/** The same signal in structured form, for `--json` consumers. */
+export function staleness(node, opts = {}) {
+  const note = annotate(node, opts);
+  if (!note) return null;
+  const res = commitsSince(node.captured_sha, opts.cwd ?? process.cwd());
+  return {
+    status: res.status === 'ok' ? 'stale' : 'rewritten',
+    commits: res.status === 'ok' ? res.count : null,
+    note,
+  };
+}
+
+/**
+ * Nodes far enough behind to be worth a deliberate review, for `doctor`.
+ *
+ * Annotation happens where knowledge is used; this list exists so an operator can
+ * also go looking, rather than waiting to be told one note at a time.
+ */
+export function reviewCandidates(db, { cwd = process.cwd(), cfg = loadConfig() } = {}) {
+  const here = currentRepo(cwd);
+  if (!here) return [];
+
+  const rows = db
+    .prepare(`
+      SELECT id, type, title, captured_sha
+        FROM nodes
+       WHERE archived = 0 AND captured_sha IS NOT NULL
+       ORDER BY id
+    `)
+    .all();
+
+  const repoStmt = db.prepare('SELECT repo FROM node_repos WHERE node_id = ?');
+  const out = [];
+  for (const row of rows) {
+    const repos = repoStmt.all(row.id).map((r) => r.repo);
+    if (repos.length && !repos.includes(here)) continue;
+
+    const res = commitsSince(row.captured_sha, cwd);
+    if (res.status === 'unreachable') {
+      out.push({ ...row, reason: 'history rewritten', commits: null });
+    } else if (res.status === 'ok' && res.count >= cfg.staleReviewCommits) {
+      out.push({ ...row, reason: 'far behind HEAD', commits: res.count });
+    }
+  }
+  return out;
+}
+
+/** Testing seam: the per-process cache would otherwise outlive a fixture repo. */
+export function resetCache() {
+  cache.clear();
+}

package/src/targets.js

@@ -0,0 +1,139 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+
+/**
+ * Where the agents on this machine look for their instructions.
+ *
+ * Different tools read different places, and a user should not have to know which
+ * one they are using. `setup` probes for all of them and installs wherever a tool is
+ * actually present, then reports what it found and what it skipped.
+ *
+ * Nothing here is guessed. A path appears in this file only when the mechanism is
+ * documented or observed; a tool with no verifiable user-global hook is detected and
+ * reported rather than written to speculatively.
+ */
+
+/** Home, overridable so a test never touches a real profile. */
+export function agentHome() {
+  return process.env.AGENT_MEMORY_SKILLS_HOME || process.env.USERPROFILE || homedir();
+}
+
+/**
+ * VS Code and its forks keep user data in a per-application directory, and prompt
+ * files live in `User/prompts` inside it. The forks are included because they
+ * inherit the mechanism; on one that does not, an extra markdown file is inert.
+ */
+const VSCODE_FLAVOURS = [
+  ['vscode', 'VS Code', 'Code'],
+  ['vscode-insiders', 'VS Code Insiders', 'Code - Insiders'],
+  ['vscodium', 'VSCodium', 'VSCodium'],
+  ['cursor', 'Cursor', 'Cursor'],
+  ['windsurf', 'Windsurf', 'Windsurf'],
+];
+
+export function vscodeUserDir(flavourDir, home = agentHome()) {
+  if (platform() === 'darwin') {
+    return join(home, 'Library', 'Application Support', flavourDir, 'User');
+  }
+  if (platform() === 'win32') {
+    // %APPDATA% is authoritative on Windows, but it points at the real profile, so
+    // honouring it under an overridden home would let a test write into the actual
+    // VS Code installation. When the home is overridden, derive the path instead.
+    const overridden = Boolean(process.env.AGENT_MEMORY_SKILLS_HOME);
+    const appData = (!overridden && process.env.APPDATA) || join(home, 'AppData', 'Roaming');
+    return join(appData, flavourDir, 'User');
+  }
+  return join(home, '.config', flavourDir, 'User');
+}
+
+/**
+ * Codex keeps skills at `$CODEX_HOME/skills/<name>/SKILL.md`, the same layout Claude
+ * Code uses. Observed rather than assumed: its bundled `skill-installer` skill states
+ * the location, and the shipped system skills sit there in exactly that shape.
+ */
+export function codexHome(home = agentHome()) {
+  // As with %APPDATA%, CODEX_HOME points at the real profile, so honouring it under an
+  // overridden home would let a test write into the actual Codex installation.
+  const overridden = Boolean(process.env.AGENT_MEMORY_SKILLS_HOME);
+  return (!overridden && process.env.CODEX_HOME) || join(home, '.codex');
+}
+
+/** Every VS Code-family user directory that exists on this machine. */
+export function vscodeUserDirs(home = agentHome()) {
+  return VSCODE_FLAVOURS.map(([id, label, dir]) => ({
+    id,
+    label,
+    userDir: vscodeUserDir(dir, home),
+  })).filter((f) => existsSync(f.userDir));
+}
+
+/**
+ * Every install location, with whether the tool behind it is actually here.
+ *
+ * `kind` decides the format written:
+ *   skill-dir  -> <dir>/<name>/SKILL.md, linked
+ *   prompt-dir -> <dir>/<name>.prompt.md, written
+ */
+export function detectTargets(home = agentHome()) {
+  const targets = [
+    {
+      id: 'agents',
+      label: 'Agent skills (shared convention)',
+      kind: 'skill-dir',
+      dir: join(home, '.agents', 'skills'),
+      // Always installed: this is the location this project defines, so its absence
+      // means "not set up yet" rather than "tool not present".
+      detected: true,
+      note: 'read by GitHub Copilot agent skills',
+    },
+    {
+      id: 'claude-code',
+      label: 'Claude Code (CLI and VS Code extension)',
+      kind: 'skill-dir',
+      dir: join(home, '.claude', 'skills'),
+      detected: existsSync(join(home, '.claude')),
+    },
+    {
+      id: 'codex',
+      label: 'Codex CLI',
+      kind: 'skill-dir',
+      dir: join(codexHome(home), 'skills'),
+      detected: existsSync(codexHome(home)),
+      note: 'same SKILL.md layout as Claude Code',
+    },
+  ];
+
+  for (const f of vscodeUserDirs(home)) {
+    targets.push({
+      id: f.id,
+      label: `${f.label} (Copilot chat prompt files)`,
+      kind: 'prompt-dir',
+      dir: join(f.userDir, 'prompts'),
+      detected: true,
+      note: 'invoked as /recall, /remember, /handoff in chat',
+    });
+  }
+
+  // Detected and deliberately not written to. Copilot CLI documents no user-global
+  // prompt or skill directory, and writing into its config folder on a guess is how
+  // you ship a file that does nothing while claiming support for it.
+  const copilotCli = join(home, '.copilot');
+  if (existsSync(copilotCli)) {
+    targets.push({
+      id: 'copilot-cli',
+      label: 'Copilot CLI',
+      kind: 'unsupported',
+      dir: copilotCli,
+      detected: true,
+      note: 'no user-global prompt directory; use .github/copilot-instructions.md per repo',
+    });
+  }
+
+  return targets;
+}
+
+/** The targets setup will actually write to. */
+export function installableTargets(home = agentHome()) {
+  return detectTargets(home).filter((t) => t.detected && t.kind !== 'unsupported');
+}