@vib795/agent-memory 0.7.0 → 0.7.2

package/README.md

@@ -561,7 +561,7 @@ 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.
 
-Run `npm test` for the suite (105 tests, no dependencies). CI runs it on Linux,
+Run `npm test` for the suite (109 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.0",
+  "version": "0.7.2",
   "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/src/compact.js

@@ -1,4 +1,5 @@
 import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { join, sep, basename, dirname } from 'node:path';
 import { loadConfig, paths } from './config.js';
@@ -152,28 +153,78 @@ function decay(active, cfg, now) {
  * 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
+// `<package>/skills/<name>`, so a description write normally 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));
 
+// One process, one answer, so a per-run cache cannot go stale. `compact` asks about
+// every registered path on every call, and most of them resolve to the same few trees.
+const trackedCache = new Map();
+
 /**
- * Is this path inside the package's own git checkout?
+ * Does git consider this exact file tracked?
  *
- * 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.
+ * `true` and `false` are answers; `null` means git could not be asked and the caller
+ * has to fall back. A non-zero exit covers both "not tracked" and "not in a repository",
+ * and those mean the same thing here: writing the file publishes nothing.
+ */
+function isTracked(real) {
+  if (trackedCache.has(real)) return trackedCache.get(real);
+  let answer;
+  try {
+    execFileSync('git', ['ls-files', '--error-unmatch', '--', basename(real)], {
+      cwd: dirname(real),
+      stdio: ['ignore', 'ignore', 'ignore'],
+      timeout: 5000,
+    });
+    answer = true;
+  } catch (err) {
+    // ENOENT is git missing, which is not an answer about the file. Anything else is
+    // git having run and said no.
+    answer = err.code === 'ENOENT' ? null : false;
+  }
+  trackedCache.set(real, answer);
+  return answer;
+}
+
+/**
+ * Would writing this file commit local state into someone's repository?
+ *
+ * The question is about the **target**, not about where this code is running from, and
+ * that distinction is the bug this replaced. The old test asked whether the running
+ * package had a `.git`, which is true from a checkout and false from an installed
+ * package — so a registered path pointing into a checkout was refused in dev mode and
+ * silently written in normal mode. Switching a machine from `npm install -g .` to the
+ * published package leaves exactly such a path behind, and the next `compact` wrote a
+ * machine-specific digest into a tracked file. The same failure that shipped one
+ * machine's note count for twenty releases, reached from the other direction.
+ *
+ * Tracked-ness is the property that actually matters, so ask git directly. Resolved
+ * through `realpathSync` first because the path arrives as a symlink planted by
+ * `setup`: the link sits outside the repository even when its target is inside it, and
+ * asking about the link would answer "not tracked" and then write straight through it.
+ *
+ * Without git, fall back to the old package-root heuristic. It is narrower than the
+ * real question but it is what this shipped with, and a machine with no git also has
+ * no tracked file to damage.
  */
 export function insideCheckout(file) {
-  if (!existsSync(join(PACKAGE_ROOT, '.git'))) return false;
   let real;
-  let root;
   try {
     real = realpathSync(file);
+  } catch {
+    return false;
+  }
+
+  const tracked = isTracked(real);
+  if (tracked !== null) return tracked;
+
+  if (!existsSync(join(PACKAGE_ROOT, '.git'))) return false;
+  let root;
+  try {
     root = realpathSync(PACKAGE_ROOT);
   } catch {
     return false;
@@ -182,6 +233,11 @@ export function insideCheckout(file) {
   return real === root || real.startsWith(root + sep);
 }
 
+/** Testing seam: the per-process cache would otherwise outlive a fixture repo. */
+export function resetTrackedCache() {
+  trackedCache.clear();
+}
+
 export function writeSkillDescription(skillPath, description) {
   if (!existsSync(skillPath)) return false;
   if (insideCheckout(skillPath)) return false;

package/src/config.js

@@ -103,6 +103,7 @@ export const DEFAULTS = {
   captureGapCommits: 50, // repo movement with no capture at all before it is worth saying
   compactThreshold: 10, // node-count delta that triggers an automatic compact
   briefRecentMinutes: 120, // window the capture brief calls already covered
+  briefRecentIds: 10, // ids printed from that window before the rest are counted
 };
 
 // Written by the installer: every SKILL.md whose description compact regenerates.
@@ -134,7 +135,10 @@ export function loadConfig() {
   const merged = { ...DEFAULTS, skillPaths: [] };
 
   for (const [k, v] of Object.entries(readJson(paths.config))) {
-    if (k in DEFAULTS && typeof v === 'number' && Number.isFinite(v) && v > 0) merged[k] = v;
+    // Integer, not merely finite. Every cap here counts something, and one of them is
+    // bound into a SQL `LIMIT`, where a fractional value is a datatype mismatch rather
+    // than a rounding question.
+    if (k in DEFAULTS && Number.isSafeInteger(v) && v > 0) merged[k] = v;
   }
   const machine = readJson(paths.machineConfig);
   for (const k of LIST_KEYS) {
@@ -163,7 +167,7 @@ export function saveConfig(patch) {
   let capsDirty = false;
   let machineDirty = false;
   for (const [k, v] of Object.entries(patch || {})) {
-    if (k in DEFAULTS && typeof v === 'number' && Number.isFinite(v) && v > 0) {
+    if (k in DEFAULTS && Number.isSafeInteger(v) && v > 0) {
       caps[k] = v;
       capsDirty = true;
     }

package/src/digest.js

@@ -1,4 +1,5 @@
 import { loadConfig, NOTE_TYPES } from './config.js';
+import { createHash } from 'node:crypto';
 import { captureGap, currentRepo } from './staleness.js';
 
 /**
@@ -31,6 +32,47 @@ const USE_WHEN =
   'Use when you need to know how a system works, why a decision was made, ' +
   'what convention applies, or what the environment forbids.';
 
+/**
+ * A repository name safe to put in front of a model.
+ *
+ * `currentRepo` is `basename(git rev-parse --show-toplevel)` — a directory name. That
+ * value reaches Tier 1, the one string loaded into every conversation, and
+ * `writeSkillDescription` only JSON-quotes the line, which keeps the YAML valid and
+ * does nothing about the content.
+ *
+ * The charset filter alone is not enough, and the reason is specific: a GitHub
+ * repository name is drawn from exactly this charset, so
+ * `SYSTEM-ignore-previous-instructions` survives it unchanged and arrives by nothing
+ * more exotic than `git clone`. Hyphens separate words as well as spaces do.
+ *
+ * So shape decides. A repository name is one to three segments and short; an
+ * instruction needs more words than that. Anything outside that shape is rendered as a
+ * stable non-semantic identifier instead — the name is still distinguishable from
+ * another repository's, and still tells a reader in the wrong tree that the numbers are
+ * not theirs, which is the only job it had.
+ *
+ * The cost is honest: a legitimate four-segment name shows as `repo-<hash>`. That is a
+ * deliberate trade of some legibility for a Tier-1 string that cannot be authored by
+ * whoever chose the directory name.
+ *
+ * Display only. Every query still matches on the real name, because a repository whose
+ * notes stopped being found would be a worse bug than the one this closes.
+ */
+export function safeRepo(name) {
+  if (typeof name !== 'string' || !name) return 'unnamed';
+  // Filtering must not be able to *make* a name look ordinary. Stripping the spaces
+  // out of "Ignore previous instructions" collapses it into one long token that would
+  // pass the shape test below, so a name that had to be modified at all is already
+  // outside the shape and goes straight to an identifier.
+  const untouched = /^[A-Za-z0-9._-]+$/.test(name);
+  const segments = name.split(/[-._]+/).filter(Boolean);
+  if (untouched && segments.length <= 3 && name.length <= 32) return name;
+  // Stable across runs and machines, so the same repository always reads the same and
+  // two repositories never collide in the description.
+  return `repo-${createHash('sha256').update(name).digest('hex').slice(0, 8)}`;
+}
+
+
 function typeRank(type) {
   const i = TYPE_ORDER.indexOf(type);
   return i === -1 ? TYPE_ORDER.length : i;
@@ -88,7 +130,7 @@ export function buildDigest(db, { cfg = loadConfig() } = {}) {
        ORDER BY c DESC, r.repo
     `)
     .all()
-    .map((r) => r.repo);
+    .map((r) => safeRepo(r.repo));
 
   const topics = db
     .prepare(`
@@ -210,17 +252,20 @@ export function buildCaptureNudge(db, { cfg = loadConfig(), cwd = process.cwd(),
   // and the commit branches below stay on that same definition. The broader count is
   // reserved for the covered branches, where the question is how much knowledge applies
   // here rather than how much of it was captured here.
+  // Display only. `repoScopedCount` below is still given the real name.
+  const label = safeRepo(g.repo);
+
   if (g.notes === 0) {
     // captureGap withholds its note on a repository too young for the absence to mean
     // anything. Stay silent with it: nagging on commit three is how a signal gets
     // discounted long before the day it matters.
     return compose(
-      g.note ? `Nothing has ever been captured for ${g.repo} — ${g.commits} commits of history.` : null,
+      g.note ? `Nothing has ever been captured for ${label} — ${g.commits} commits of history.` : null,
     );
   }
 
   // Captured, but the repository has moved a long way since the most recent one.
-  if (g.note) return compose(`${g.commits} commits since anything was captured for ${g.repo}.`);
+  if (g.note) return compose(`${g.commits} commits since anything was captured for ${label}.`);
 
   // Current on commits, but blind in the type that matters most. `digest` privileges
   // constraints and never drops them from Tier 1; a store holding none has not recorded
@@ -228,13 +273,13 @@ export function buildCaptureNudge(db, { cfg = loadConfig(), cwd = process.cwd(),
   const notes = repoScopedCount(db, g.repo);
   if (repoScopedCount(db, g.repo, PRIVILEGED) === 0) {
     return compose(
-      `${notes} note${notes === 1 ? '' : 's'} for ${g.repo} and no constraint recorded — ` +
+      `${notes} note${notes === 1 ? '' : 's'} for ${label} and no constraint recorded — ` +
         'what this environment forbids has never been written down.',
     );
   }
 
   // Covered. Report the state plainly and let the routing clause do the rest.
-  return compose(`${notes} note${notes === 1 ? '' : 's'} for ${g.repo}, capture is current.`);
+  return compose(`${notes} note${notes === 1 ? '' : 's'} for ${label}, capture is current.`);
 }
 
 /**
@@ -301,7 +346,7 @@ export function buildTree(db, { repo = null, all = false, cfg = loadConfig() } =
 }
 
 export function renderTree(result) {
-  const scope = result.repo ? result.repo : 'all repos';
+  const scope = result.repo ? safeRepo(result.repo) : 'all repos';
   const out = [`# memory: ${scope} — ${result.total} notes`];
   const width = result.lines.reduce((w, e) => Math.max(w, e.id.length), 0);
   for (const e of result.lines) {
@@ -366,10 +411,15 @@ function typeCounts(db, repo) {
  * window wide enough to cover the working session is the honest approximation.
  */
 function recentlyCaptured(db, repo, cfg, now) {
+  // Bound straight into SQLite's `LIMIT ?`, which rejects a REAL with `datatype
+  // mismatch`. Callers may hand in a cfg that never went through loadConfig -- every
+  // test does -- so the floor lives here as well as there.
+  const cap = Math.max(1, Math.floor(cfg.briefRecentIds));
   // Same format store.js writes, so a lexicographic compare is a chronological one.
   const cutoff = new Date(now - cfg.briefRecentMinutes * 60000)
     .toISOString()
     .replace(/\.\d{3}Z$/, 'Z');
+  // One row past the cap is the cheap overflow probe.
   const rows = repo
     ? db
         .prepare(`
@@ -378,15 +428,31 @@ function recentlyCaptured(db, repo, cfg, now) {
             LEFT JOIN node_repos r ON r.node_id = n.id
            WHERE n.archived = 0 AND n.updated >= ? AND (n.scope = 'global' OR r.repo = ?)
            ORDER BY n.updated DESC, n.id
+           LIMIT ?
         `)
-        .all(cutoff, repo)
+        .all(cutoff, repo, cap + 1)
     : db
         .prepare(`
           SELECT id, updated FROM nodes
            WHERE archived = 0 AND updated >= ? ORDER BY updated DESC, id
+           LIMIT ?
+        `)
+        .all(cutoff, cap + 1);
+
+  if (rows.length <= cap) return { ids: rows.map((r) => r.id), omitted: 0 };
+
+  // The exact count is only worth a second query when there is something to report.
+  const total = repo
+    ? db
+        .prepare(`
+          SELECT COUNT(DISTINCT n.id) AS c
+            FROM nodes n
+            LEFT JOIN node_repos r ON r.node_id = n.id
+           WHERE n.archived = 0 AND n.updated >= ? AND (n.scope = 'global' OR r.repo = ?)
         `)
-        .all(cutoff);
-  return rows.map((r) => r.id);
+        .get(cutoff, repo).c
+    : db.prepare('SELECT COUNT(*) AS c FROM nodes WHERE archived = 0 AND updated >= ?').get(cutoff).c;
+  return { ids: rows.slice(0, cap).map((r) => r.id), omitted: total - cap };
 }
 
 /**
@@ -411,6 +477,7 @@ export function buildBrief(db, { repo, cwd = process.cwd(), cfg = loadConfig(),
   const g = gap !== undefined ? gap : here ? captureGap(db, { cwd, cfg, repo: here }) : null;
   const tree = buildTree(db, { repo: here, cfg });
   const counts = typeCounts(db, here);
+  const recent = recentlyCaptured(db, here, cfg, now);
 
   return {
     repo: here,
@@ -418,15 +485,16 @@ export function buildBrief(db, { repo, cwd = process.cwd(), cfg = loadConfig(),
     tree,
     counts: Object.fromEntries(counts),
     missing: NOTE_TYPES.filter((t) => counts.get(t) === 0),
-    recent: recentlyCaptured(db, here, cfg, now),
+    recent: recent.ids,
+    recentOmitted: recent.omitted,
     recentMinutes: cfg.briefRecentMinutes,
     total: tree.total,
   };
 }
 
 export function renderBrief(result) {
-  const { repo, gap, tree, counts, missing, recent, recentMinutes } = result;
-  const scope = repo ?? 'all repos';
+  const { repo, gap, tree, counts, missing, recent, recentOmitted, recentMinutes } = result;
+  const scope = repo ? safeRepo(repo) : 'all repos';
 
   // The header carries the same signal the remember description does, at the same
   // moment it is being acted on. A brief that opens with a note count while the repo
@@ -471,9 +539,13 @@ export function renderBrief(result) {
   if (recent.length) {
     // Written as the reason rather than the rule, because the rule is already in the
     // skill and the model is being asked to apply it, not to learn it again.
+    // Bounded, and it says so. A bulk write or import stamps every note with the same
+    // minute; printing all of them would spend the context this brief exists to
+    // conserve, while reading as the whole list -- the exact failure the tree refuses.
+    const more = recentOmitted ? ` (+${recentOmitted} more)` : '';
     out.push(
       '',
-      `captured in the last ${recentMinutes} minutes, so already covered: ${recent.join(', ')}`,
+      `captured in the last ${recentMinutes} minutes, so already covered: ${recent.join(', ')}${more}`,
     );
   }