@vib795/agent-memory 0.1.13 → 0.1.15

package/HOWTO.md

@@ -170,6 +170,21 @@ You can also point it at something specific:
 **Don't bother remembering** anything the code already says. If someone can find it by
 opening a file, it does not need a note. Notes are for what lives in people's heads.
 
+**You will also see it happen without you asking.** When a decision settles or a
+constraint turns up mid-conversation, the assistant writes it down and tells you in
+one line:
+
+```
+captured 2 notes [decision, constraint]
+```
+
+Then it carries on with whatever you were actually asking about. This is on purpose:
+the fact worth keeping is usually the one nobody stops to write down. It costs you
+nothing — your allowance is charged per message you send, not per thing the assistant
+does while answering — and you can see everything it captured with `/recall` or
+`agent-memory tree`. If it ever writes down something you did not want, the notes are
+plain markdown files you can edit or delete.
+
 ### `/handoff` — for moving work between windows
 
 This one is not a chat summary. Summaries read nicely and still leave the next

package/README.md

@@ -16,7 +16,7 @@ Three user-level Agent Skills over one local store:
 | Skill | What it does |
 |---|---|
 | `/handoff` | Writes a portable working-state file so another window can pick up this thread |
-| `/remember` | Captures durable knowledge into a cross-repo graph |
+| `/remember` | Captures durable knowledge into a cross-repo graph — and fires on its own when a juncture passes |
 | `/recall` | Answers from that graph before deriving anything again |
 
 **New here? Read the [HOW-TO](HOWTO.md)** — install, first five minutes, and the
@@ -78,6 +78,14 @@ recursive CTE *is* the graph engine, and `UNION` plus a depth bound is what keep
 - **Staleness is visible at the moment of use.** Every note records the repo HEAD it
   was captured at. On recall, `get` prints `captured 47 commits ago — verify before
   trusting`. A note that quietly rots is worse than no note.
+- **An empty graph says so.** Staleness cannot tell you a repo has nothing in it —
+  a repo nobody captured in has no stale notes either, so it reads as fully covered.
+  `tree` and `doctor` print `47 commits since anything was captured here` instead.
+  Silence has to mean covered, never empty.
+- **Capture does not wait to be asked.** The agent invokes `/remember` itself when a
+  decision settles, a constraint surfaces or a root cause is found, and says so in one
+  line. Judged by the model in the turn where the context still exists — never on a
+  timer or a tool count, because volume is what makes a graph useless.
 - **Redaction is fail-closed.** Keys, tokens, connection strings, private keys,
   session cookies, internal hosts and foreign email addresses are replaced before any
   byte reaches disk — not to a note, not to a temp file, not to the index.
@@ -336,7 +344,21 @@ Mid-session, when something worth keeping has been established:
 ```
 
 Bare, it selects the durable knowledge itself. With an argument, it writes that and
-nothing else. Either way it makes one terminal call, and `write` reports each id:
+nothing else.
+
+You will also see it fire without being asked, when a decision settles, a constraint
+surfaces, a root cause is found or a convention is agreed. It reports one line at the
+end of whatever it was already answering and carries on:
+
+```
+captured 2 notes [decision, constraint]
+```
+
+That costs nothing — a request is charged per prompt, not per tool call, so capture
+inside a turn you already paid for is free. Only typing `/remember` yourself spends
+one.
+
+Either way it makes one terminal call, and `write` reports each id:
 
 ```
 created auth-service [system]
@@ -482,10 +504,21 @@ it. And because a request is charged per prompt rather than per tool call, captu
 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:
 
-- A capture-gap signal — the store knows when a note has gone stale, but not yet when
-  a repo has moved a hundred commits with nothing captured at all
 - 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.13",
+  "version": "0.1.15",
   "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/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();