@vib795/agent-memory 0.7.2 → 0.7.4

package/README.md

@@ -440,7 +440,7 @@ equivalent and is not: npm links the global install to that folder rather than c
 it, which shows up as an arrow in `npm list -g`:
 
 ```
-`-- @vib795/agent-memory@0.6.5 -> .\..\..\..\agent-memory
+`-- @vib795/agent-memory@0.7.4 -> .\..\..\..\agent-memory
 ```
 
 Move or delete the clone afterwards and the global install points at nothing — the same
@@ -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 (109 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.2",
+  "version": "0.7.4",
   "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

@@ -104,6 +104,7 @@ export const DEFAULTS = {
   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.

package/src/digest.js

@@ -3,22 +3,25 @@ import { createHash } from 'node:crypto';
 import { captureGap, currentRepo } from './staleness.js';
 
 /**
- * Two-tier routing.
+ * Tiers 1 and 2 of a three-tier ladder.
  *
- * Tier 1 is the `recall` skill's description, which is loaded into every chat
- * whether or not memory is ever used. It is standing cost, so it has to read like
- * a description rather than a document.
+ * Tier 1 is a skill description, loaded into every chat whether or not memory is ever
+ * used. It is standing cost, so it has to read like a description rather than a
+ * document. It has two occupants, not one: `recall`'s description advertises what the
+ * store knows; `remember`'s advertises what it is missing. Both are the same mechanism
+ * — a line of frontmatter that code regenerates and every conversation loads —
+ * pointed at opposite halves of the same problem.
  *
- * Tier 2 is the tree, printed only when `recall` actually fires. Per-invocation
- * cost, paid once, and only when someone is already looking something up.
+ * Tier 2 is printed only when a skill actually fires: the tree for `recall`, the
+ * capture brief for `remember`. Per-invocation cost, paid once, and only when someone
+ * is already looking something up or about to write one down.
  *
- * Neither tier costs a premium request. A request is charged per prompt, not per
- * tool call, so both of these ride inside a turn that was already paid for.
+ * Tier 3 — note bodies, and the colliding note that `write` hands back — lives
+ * outside this module, because by then the question is which note rather than which
+ * of them.
  *
- * Tier 1 has two occupants, not one. `recall`'s description advertises what the store
- * knows; `remember`'s advertises what it is missing. Both are the same mechanism — a
- * line of frontmatter that code regenerates and every conversation loads — pointed at
- * opposite halves of the same problem.
+ * Neither tier here costs a premium request. A request is charged per prompt, not per
+ * tool call, so both of these ride inside a turn that was already paid for.
  */
 
 // Never dropped from either tier. A constraint is what stops an agent from burning