@vib795/agent-memory 0.7.1 → 0.7.3

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 (106 tests, no dependencies). CI runs it on Linux,
+Run `npm test` for the suite (111 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.1",
+  "version": "0.7.3",
   "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/remember/SKILL.md

@@ -223,7 +223,15 @@ Then stop. Do not summarize the conversation.
 Warnings from `write` are worth surfacing verbatim:
 
 - `title collision` means an existing note reads as the same thing under a different
-  id. Tell the user which two, and offer to merge or link them with `contradicts`.
+  id. The warning now carries that note's type, title and body, so decide in **this
+  turn** — do not run `get` to fetch what you were already handed:
+  - **Same claim, better wording** — update the existing id with the fuller body. One
+    note, improved.
+  - **The claim changed** — set `supersedes` to the old id on your new note.
+  - **They genuinely disagree** — link them with `contradicts` and say so to the user.
+
+  Two notes making one claim is the thing compaction cannot repair for you: it merges
+  on identical content, and these are not identical, only synonymous.
 - `redacted Nx <kind>` means the guard caught something. Say what kind was caught so
   the user knows a secret was in play, never what the value was.
 

package/src/cli.js

@@ -400,6 +400,20 @@ function readNodesFrom(file) {
   return [raw];
 }
 
+/**
+ * A readable slice of a note body, cut on a boundary rather than mid-word.
+ *
+ * Enough to decide whether two notes make the same claim, and no more: this rides
+ * inside a `write` response, which is not the place to reproduce a 4 KB note.
+ */
+function clip(body, limit) {
+  const text = String(body ?? '').trim();
+  if (text.length <= limit) return { text, truncated: false };
+  const head = text.slice(0, limit);
+  const cut = Math.max(head.lastIndexOf('\n'), head.lastIndexOf(' '));
+  return { text: (cut > limit / 2 ? head.slice(0, cut) : head).trimEnd(), truncated: true };
+}
+
 function cmdWrite(opts) {
   const file = opts['from-json'];
   if (!file || file === true || (file !== '-' && !existsSync(file))) {
@@ -432,6 +446,8 @@ function cmdWrite(opts) {
 
   // Normalized titles of what already exists, so two agents naming one thing two
   // different ways surface as a collision instead of quietly becoming two nodes.
+  // Bodies are deliberately not loaded here: a collision is rare, and paying for every
+  // body in the store to describe the one that collided is the wrong trade.
   const titles = new Map();
   for (const row of db.prepare('SELECT id, title, content_hash FROM nodes').all()) {
     titles.set(normalizeTitle(row.title), { id: row.id, hash: row.content_hash });
@@ -440,6 +456,7 @@ function cmdWrite(opts) {
   const written = [];
   const failed = [];
   const warnings = [];
+  const collisions = [];
   for (const raw of incoming) {
     const node = { ...raw };
     node.source = node.source || (opts.source === true ? undefined : opts.source) || 'manual';
@@ -453,9 +470,25 @@ function cmdWrite(opts) {
     try {
       const res = writeNote(node, { selfEmail });
       if (collision && collision.id !== res.node.id) {
+        // The id alone forced a second turn: deciding whether this is a duplicate to
+        // merge or a genuine contradiction needs the other note's words, and fetching
+        // them meant another `get`, which on a per-prompt biller is another request.
+        // One row, and only when a collision actually happened.
+        const other = getNodeRow(db, collision.id);
+        const excerpt = other ? clip(other.body, cfg.collisionBodyChars) : null;
+        collisions.push({
+          id: res.node.id,
+          existing: collision.id,
+          existingType: other?.type ?? null,
+          existingTitle: other?.title ?? null,
+          existingArchived: Boolean(other?.archived),
+          excerpt: excerpt?.text ?? null,
+          truncated: Boolean(excerpt?.truncated),
+        });
         warnings.push(
-          `title collision: ${res.node.id} reads the same as existing ${collision.id}; ` +
-            'set contradicts or merge them',
+          `title collision: ${res.node.id} reads the same as existing ${collision.id}` +
+            (other ? ` [${other.type}] ${other.title}` : '') +
+            (other?.archived ? ' (archived)' : ''),
         );
       }
       written.push({
@@ -479,9 +512,18 @@ function cmdWrite(opts) {
   const compacted = maybeCompact(db, before, after, cfg);
   db.close();
 
+  // Printed under the warning and indented, so it reads as evidence rather than as a
+  // second instruction competing with the first.
+  const collisionLines = collisions.flatMap((c) => [
+    ...(c.excerpt ? c.excerpt.split('\n').map((l) => `    ${l}`) : []),
+    ...(c.truncated ? [`    ... agent-memory get ${c.existing} for the rest`] : []),
+    `    -> update ${c.existing} by id, or set supersedes or contradicts on ${c.id}.`,
+  ]);
+
   const text = [
     ...written.map((w) => `${w.created ? 'created' : 'updated'} ${w.id} [${w.type}]`),
     ...warnings.map((w) => `warning: ${w}`),
+    ...collisionLines,
     ...failed.map((f) => `failed ${f.id ?? '<no id>'}: ${f.errors.join('; ')}`),
     written.length ? '' : 'No nodes written.',
     compacted ? `compacted: ${compacted.indexed} notes indexed` : '',
@@ -489,7 +531,9 @@ function cmdWrite(opts) {
     .filter(Boolean)
     .join('\n');
 
-  return { ok: failed.length === 0, written, failed, warnings, compacted: !!compacted, text };
+  return {
+    ok: failed.length === 0, written, failed, warnings, collisions, compacted: !!compacted, text,
+  };
 }
 
 function cmdCompact() {

package/src/config.js

@@ -103,6 +103,8 @@ 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
+  collisionBodyChars: 500, // excerpt returned with a title collision, so one turn can fix it
 };
 
 // Written by the installer: every SKILL.md whose description compact regenerates.
@@ -134,7 +136,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 +168,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}`,
     );
   }