@vib795/agent-memory 0.1.12 → 0.1.14

package/README.md

@@ -465,11 +465,38 @@ that drifts as the work progresses does not create a duplicate.
 
 ## Status
 
-Capture is **explicit**. You invoke it, or `/handoff` does; nothing fires on its own.
+Capture is **judged, not scheduled.** You invoke it, `/handoff` does, or the agent
+does on its own when a juncture has just passed — a decision settled, a constraint
+found, a root cause identified, a convention agreed. It says so in one line and
+carries on with what you actually asked:
+
+```
+captured 2 notes [decision, constraint]
+```
+
+Nothing fires on a timer, on a tool count, or on every reply. That distinction is the
+whole design: a store full of task chatter is worse than an empty one, because it
+buries the four notes that mattered. The judgment of what is durable belongs to the
+model, in the turn where the context still exists; there is no keyword list deciding
+it. And because a request is charged per prompt rather than per tool call, capture
+that rides inside a turn you already paid for is free — which is why it can afford to
+happen at the moment the knowledge is fresh instead of whenever someone remembers.
+
+The inverse is reported too. Staleness answers *is this note still true*; it cannot
+answer *is there anything here yet*, and those fail in opposite directions — a repo
+nobody has ever captured in has no stale notes either, so it reads exactly like one
+that is fully covered. `tree` and `doctor` both say so:
+
+```
+47 commits since anything was captured for orders-api — /remember is behind
+```
+
+Measured to the *nearest* capture, so one fresh note closes the gap however old the
+rest of the graph is, and silent below `captureGapCommits` (50) so a young repo is
+never nagged. Silence has to mean covered, never empty.
 
 Not built yet, by choice:
 
-- Automatic or ambient capture
 - Team sharing, multi-machine sync
 - An MCP server. It would read this same store, so it is an addition, not a rewrite.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vib795/agent-memory",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "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

@@ -1,7 +1,7 @@
 ---
 name: remember
 version: 0.1.0
-description: Capture durable project knowledge from the current conversation into the shared memory graph, so a later conversation in any window or repository already knows it. Use when the user says remember this, save this, note this for later, or /remember.
+description: Capture durable project knowledge from this conversation into a cross-repo memory graph, so a later conversation anywhere already knows it. Use when the user says remember this, save this, note this for later, or /remember. Also invoke it unasked when a juncture passes - a decision settled, a constraint found, a root cause identified, a convention agreed - then say so in one line and carry on.
 license: MIT
 allowed-tools: Bash Read Write
 triggers:
@@ -25,11 +25,51 @@ call. Do not ask the user to confirm each node.
 
 ---
 
-## Two forms
+## Three forms
 
 - **`/remember`** — you select the durable knowledge from the conversation so far.
 - **`/remember <what>`** — the user named the thing. Write that, with full context
   from the conversation, and write nothing unrelated to it.
+- **Unasked** — you noticed a juncture pass and captured it without being told.
+
+### Capturing unasked
+
+A memory that only grows when someone remembers to grow it stays thin, and thin is
+how it dies: the one fact worth having is the one nobody stopped to write down.
+
+Invoke this yourself the moment one of these has just happened, in the same turn:
+
+- a **decision** was settled, and the reasons and rejected options are still in view
+- a **constraint** surfaced — a blocked tool, a policy, an environment restriction
+- a **root cause** was found, as opposed to a symptom worked around
+- a **convention** was agreed, or discovered by reading the code
+
+Do not capture on a timer, on a tool count, or at every reply. Those produce volume,
+and volume is what makes a graph useless — a store full of task chatter is worse than
+an empty one, because it buries the four notes that mattered.
+
+Never capture: task status, what you are about to do next, anything already in the
+graph, or anything that will be false next month. If you captured a juncture earlier
+in this conversation, do not capture it again because it came up a second time.
+
+**It is free, and that is the point.** A request is charged per prompt, not per tool
+call, so capturing inside a turn you were already answering costs nothing. Only a
+user typing `/remember` spends a request. That is the whole reason to do this
+yourself rather than wait to be asked.
+
+**Report it in one line, then carry on:**
+
+```
+captured 2 notes [decision, constraint]
+```
+
+At the end of the answer you were already giving. Do not print the JSON, do not
+summarize what you wrote, and do not make it the subject of the reply — the user
+asked you about something else and is still waiting for it. One line is enough for
+them to know it happened and to run `/recall` if they want the detail.
+
+If nothing durable happened, say nothing at all. Silence is the correct output for
+most turns.
 
 ---
 

package/src/cli.js

@@ -9,7 +9,7 @@ import {
 import { neighborhood, applyBudget } from './graph.js';
 import { buildTree, renderTree, buildDigest } from './digest.js';
 import { compact, maybeCompact } from './compact.js';
-import { staleness, currentRepo, reviewCandidates } from './staleness.js';
+import { staleness, currentRepo, reviewCandidates, captureGap } from './staleness.js';
 import { setup as runSetup, unlinkSkills, danglingSkillLinks, SKILLS } from './setup.js';
 import { detectTargets, installableTargets } from './targets.js';
 import { join } from 'node:path';
@@ -210,8 +210,11 @@ function cmdTree(opts) {
   const db = openDb();
   const repo = opts.repo === true ? null : (opts.repo ?? currentRepo());
   const result = buildTree(db, { repo, all: !!opts.all, cfg });
+  // Only when scoped to a repo. Across all repos there is no single history to
+  // measure against, and a number that means nothing is worse than no number.
+  const gap = repo ? captureGap(db, { cfg, repo }) : null;
   db.close();
-  return { ok: true, ...result, text: renderTree(result) };
+  return { ok: true, ...result, gap, text: renderTree({ ...result, gap }) };
 }
 
 function cmdGet(opts) {
@@ -515,6 +518,21 @@ function cmdDoctor() {
     stale.length === 0,
     stale.length ? `${stale.length} notes worth reviewing` : 'nothing far behind HEAD',
   );
+
+  // The opposite failure to staleness, and the one that leaves no trace: a repo where
+  // nothing was ever captured has no stale notes either, so it passes every check
+  // above while knowing nothing at all.
+  const gap = captureGap(db, { cfg });
+  add(
+    'capture gap',
+    !gap?.note,
+    gap?.note
+      ?? (!gap
+        ? 'not in a repository'
+        : gap.notes === 0
+          ? `nothing captured for ${gap.repo} yet, and not enough history for that to mean anything`
+          : `${gap.notes} notes, nearest capture is current`),
+  );
   db.close();
 
   const text = [
@@ -525,9 +543,9 @@ function cmdDoctor() {
   ].join('\n');
 
   // Staleness is a report, not a failure. Being told about it is the whole feature.
-  const advisory = new Set(['staleness', 'skills linked']);
+  const advisory = new Set(['staleness', 'capture gap', 'skills linked']);
   const fatal = checks.filter((c) => !c.ok && !advisory.has(c.name));
-  return { ok: fatal.length === 0, checks, stale, digest, text };
+  return { ok: fatal.length === 0, checks, stale, gap, digest, text };
 }
 
 // --- dispatch ---------------------------------------------------------------

package/src/config.js

@@ -31,6 +31,7 @@ export const DEFAULTS = {
   decayDays: 90, // archive threshold for unreferenced, unread notes
   staleAnnotateCommits: 10, // below this, staleness is not worth mentioning
   staleReviewCommits: 100, // above this, doctor flags it for review
+  captureGapCommits: 50, // repo movement with no capture at all before it is worth saying
   compactThreshold: 10, // node-count delta that triggers an automatic compact
 };
 

package/src/digest.js

@@ -195,5 +195,8 @@ export function renderTree(result) {
     // most dangerous thing this tool could do, because it looks like an answer.
     out.push(`${result.omitted.length} nodes not shown, run agent-memory tree --all`);
   }
+  // The map is what recall reads before answering, so it is where a thin graph has to
+  // admit that it is thin. A short list and a silent footer read as full coverage.
+  if (result.gap?.note) out.push(result.gap.note);
   return out.join('\n');
 }

package/src/staleness.js

@@ -145,6 +145,68 @@ export function reviewCandidates(db, { cwd = process.cwd(), cfg = loadConfig() }
   return out;
 }
 
+/**
+ * How far this repository has moved since anything was captured in it at all.
+ *
+ * Staleness answers "is this note still true". It cannot answer "is there anything
+ * here yet", and those fail in opposite directions: a repository nobody has ever run
+ * `/remember` in has no stale notes to warn about, so it reads exactly like one that
+ * is fully covered. Silence means both "all good" and "nothing here", which is the
+ * same conflation `doctor` already refuses to make about installed skills.
+ *
+ * Measured as the distance from HEAD to the nearest capture, so a single fresh note
+ * closes the gap no matter how old the rest of the graph is.
+ */
+export function captureGap(db, { cwd = process.cwd(), cfg = loadConfig(), repo } = {}) {
+  const here = repo ?? currentRepo(cwd);
+  if (!here) return null;
+
+  const rows = db
+    .prepare('SELECT id, captured_sha FROM nodes WHERE archived = 0 AND captured_sha IS NOT NULL')
+    .all();
+  const repoStmt = db.prepare('SELECT repo FROM node_repos WHERE node_id = ?');
+
+  let scoped = 0;
+  let nearest = null;
+  for (const row of rows) {
+    const repos = repoStmt.all(row.id).map((r) => r.repo);
+    if (repos.length && !repos.includes(here)) continue;
+    scoped += 1;
+    const res = commitsSince(row.captured_sha, cwd);
+    if (res.status !== 'ok') continue;
+    if (nearest === null || res.count < nearest) nearest = res.count;
+  }
+
+  if (scoped === 0) {
+    // A repository with three commits in it does not need to be told it has no
+    // memory yet. Only say this once there is enough history for the absence to
+    // mean something.
+    let depth = 0;
+    try {
+      depth = Number.parseInt(git(['rev-list', '--count', 'HEAD'], cwd), 10) || 0;
+    } catch {
+      return null;
+    }
+    if (depth < cfg.captureGapCommits) return { repo: here, notes: 0, commits: null, note: null };
+    return {
+      repo: here,
+      notes: 0,
+      commits: depth,
+      note: `nothing captured yet for ${here} — ${depth} commits of history and an empty graph`,
+    };
+  }
+
+  if (nearest === null || nearest < cfg.captureGapCommits) {
+    return { repo: here, notes: scoped, commits: nearest, note: null };
+  }
+  return {
+    repo: here,
+    notes: scoped,
+    commits: nearest,
+    note: `${nearest} commits since anything was captured for ${here} — /remember is behind`,
+  };
+}
+
 /** Testing seam: the per-process cache would otherwise outlive a fixture repo. */
 export function resetCache() {
   cache.clear();