feat: route the capture signal to the model instead of to doctor (0.7.0)

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "agent-memory",
       "source": "./",
       "description": "Durable cross-repository memory for coding agents — built to survive an IT security review. Zero runtime dependencies, zero dev dependencies, no install script: nothing runs when you install it, and granting it your agents is a separate explicit command. Independently scanned, with a passing verdict. Adds /handoff, /remember and /recall over one local markdown store. Requires the CLI: npm install -g @vib795/agent-memory (Node >= 22.5).",
-      "version": "0.6.5",
+      "version": "0.7.0",
       "author": {
         "name": "Utkarsh Singh",
         "url": "https://github.com/vib795"

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-memory",
   "displayName": "agent-memory",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "Durable cross-repository memory for coding agents — built to survive an IT security review. Zero runtime dependencies, zero dev dependencies, no install script: nothing runs when you install it, and granting it your agents is a separate explicit command. Independently scanned, with a passing verdict. Adds /handoff, /remember and /recall over one local markdown store. Requires the CLI: npm install -g @vib795/agent-memory (Node >= 22.5).",
   "author": {
     "name": "Utkarsh Singh",

ARCHITECTURE.md

@@ -250,7 +250,8 @@ premium request budget behind it.
 ```mermaid
 flowchart TB
     subgraph t1["TIER 1 — standing cost, every chat"]
-        D["recall skill description<br/>≤ 400 chars<br/>'Durable project knowledge: 5 notes, 1 constraint<br/>across agent-memory. Topics: … Use when …'"]
+        D["recall description<br/>≤ 400 chars — what the store knows<br/>'Durable project knowledge: 5 notes, 1 constraint<br/>across agent-memory. Topics: … Use when …'"]
+        R["remember description<br/>≤ 400 chars — what it is missing<br/>'340 commits since anything was captured<br/>for agent-memory. Use when …'"]
     end
     subgraph t2["TIER 2 — per-invocation, only when recall fires"]
         TR["routing tree<br/>≤ 80 lines<br/>type · id · title, ordered by<br/>constraint-first then degree"]
@@ -266,14 +267,28 @@ flowchart TB
 ```
 
 Tier 1 is loaded into every chat whether or not memory is ever used, so it has to read
-like a description rather than a document. It is composed from constraint count, then
-repos by note count, then topics by edge degree — and on overflow it sheds the
+like a description rather than a document. `recall`'s is composed from constraint count,
+then repos by note count, then topics by edge degree — and on overflow it sheds the
 lowest-degree topics first, then repos, **one whole item at a time**. Cutting mid-word
 would leave the description looking corrupted, which is worse than saying less.
 
 Two pieces are structural and never dropped: the constraint count, and the closing
 "use when" clause — which is the entire reason an agent decides to invoke at all.
 
+**Tier 1 has two occupants.** `recall`'s description advertises what the store knows;
+`remember`'s advertises what it is missing. The second is `captureGap` — the distance
+in commits from HEAD to the nearest capture, which the store has always been able to
+compute — routed to the one surface that is loaded at the moment capture is worth
+doing. Before 0.7 it went only to `doctor`, a command run by the person who least
+needed telling.
+
+It is written as a *state*, never as an instruction: "340 commits since anything was
+captured here" is a fact the model can weigh against what just happened in the
+conversation, where "remember to capture things" is wallpaper it stops seeing. Code
+supplies the timing signal; the model still decides whether anything durable happened.
+On a covered repository it goes quiet and simply reports the count — a line that nags
+at a current store teaches the reader to discount it before the day it matters.
+
 Neither tier costs a premium request. A request is charged per prompt, not per tool
 call, so both ride inside a turn that was already paid for.
 

README.md

@@ -349,11 +349,12 @@ lives under `~/.agents/memory`, nothing is written into the projects you point i
 at, and there is no per-repo setup step. `cd` between projects freely: the store
 does not move, split, or reset.
 
-One exception, and it is this repository rather than yours: if you installed from a
-clone, `npm install -g .` symlinks rather than copies, so `compact` regenerating the
-skill descriptions lands in your working tree and `skills/recall/SKILL.md` shows as
-modified. That is generated state, and [From a clone](#from-a-clone) says so. No
-project repository is ever written to.
+One note, and it is about this repository rather than yours: if you installed from a
+clone, `npm install -g .` symlinks rather than copies, so the skill links resolve back
+into your working tree. `compact` detects that and refuses to write there — the files
+are tracked, and one developer's note count committed and published is exactly what
+happened for twenty releases. It reports them as skipped instead. No project repository
+is ever written to.
 
 What the working directory changes is *scope*, never location.
 
@@ -366,6 +367,7 @@ What the working directory changes is *scope*, never location.
 | `search` | whole store | nothing — full text hits every note in every repo |
 | `get` | whole store | the staleness line only; the note is found by id either way |
 | `tree` | whole store | **filters it** — defaults to the current repo |
+| `brief` | whole store | **filters it** — the same scoping as `tree` |
 | `write` | whole store | **is stamped into the note** — see below |
 
 The current repo is `git rev-parse --show-toplevel` reduced to its directory name.
@@ -403,6 +405,7 @@ Only `init` is a once-per-machine command, and `agent-memory setup` already ran
 | `init` | once, via `setup`. Again only to register extra skill paths |
 | `write` | every capture |
 | `tree`, `get`, `search` | every lookup |
+| `brief` | every capture, before `write` — what is already known here |
 | `index` | repair only — `write` reindexes on every call. Run it after hand-editing or deleting notes, or after deleting `index.db` |
 | `compact` | occasionally. Nothing schedules it: no daemon, no cron, no hook |
 | `doctor` | after install, after an upgrade, and whenever something looks wrong |
@@ -550,14 +553,15 @@ powershell -ExecutionPolicy Bypass -File .\install.ps1 # Windows
 Both are thin wrappers over `agent-memory setup`; the linking logic lives in
 `src/setup.js` so there is one implementation rather than three that drift.
 
-Note that `npm install -g .` from a clone *symlinks* rather than copies, so
-`compact` regenerates the description in your working tree and
-`skills/recall/SKILL.md` will show as modified. That is expected — the description
-is generated state, and the committed value is only a placeholder.
+Note that `npm install -g .` from a clone *symlinks* rather than copies, so the skill
+links point back into your working tree. `compact` will not regenerate a description
+there — `skills/recall/SKILL.md` and `skills/remember/SKILL.md` are tracked files, and
+their committed descriptions are deliberately generic placeholders. `compact` prints
+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 (91 tests, no dependencies). CI runs it on Linux,
+Run `npm test` for the suite (105 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.json

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

skills/remember/SKILL.md

@@ -79,6 +79,32 @@ most turns.
 
 ---
 
+## Step 0 — Read what is already known (ONE terminal call)
+
+```bash
+agent-memory brief
+```
+
+Read-only, safe on every shell including PowerShell, and it costs no request of its
+own — it rides inside the turn you are already answering.
+
+It answers three things you would otherwise guess at:
+
+- **What is already here.** Deduplication is by exact content, so the same claim in
+  different words becomes a second node. If the brief already lists it, either say
+  nothing or update that note by its id.
+- **Which ids are real.** An `edges[].dst` or `supersedes` pointing at an id you
+  invented is accepted and then silently never connects. Take targets from the brief.
+- **Which types are empty.** A store with no `constraint` has not recorded what the
+  environment forbids, which is the type that saves a future session a wasted retry.
+
+If the brief lists an id under "already covered", that juncture was captured minutes
+ago. Do not capture it again.
+
+Skip this step only when the user named exactly what to write and it is plainly new.
+
+---
+
 ## Step 1 — Select what is durable
 
 <!-- extraction-rules:start -->

src/cli.js

@@ -10,7 +10,9 @@ import {
   openDb, reindex, searchNodes, getNodeRow, markAccessed, nodeCount, hasFts,
 } from './index-db.js';
 import { neighborhood, applyBudget } from './graph.js';
-import { buildTree, renderTree, buildDigest } from './digest.js';
+import {
+  buildTree, renderTree, buildDigest, buildCaptureNudge, buildBrief, renderBrief,
+} from './digest.js';
 import { compact, maybeCompact } from './compact.js';
 import { staleness, currentRepo, reviewCandidates, captureGap } from './staleness.js';
 import { setup as runSetup, unlinkSkills, danglingSkillLinks, SKILLS } from './setup.js';
@@ -121,6 +123,7 @@ const USAGE = `agent-memory — durable cross-repo knowledge for coding agents
   search <terms> [--limit N]             full-text fallback when the tree misses
   write --from-json <file>               validated upsert; used by the skills
         [--source <name>] [--repo <name>]
+  brief [--repo <name>]                  what is already known here, before capturing
   compact                                dedup, decay, reindex, regenerate
   doctor                                 preflight and health report
   export [--scope global|repo|all]       knowledge worth carrying to another machine
@@ -217,7 +220,7 @@ function cmdSetup() {
   if (r.compactError) {
     lines.push(
       '',
-      `  Skills are installed, but refreshing the /recall description failed: ${r.compactError}`,
+      `  Skills are installed, but refreshing the /recall and /remember descriptions failed: ${r.compactError}`,
       '  Run `agent-memory index` then `agent-memory compact` to retry just that step.',
     );
   }
@@ -286,6 +289,23 @@ function cmdTree(opts) {
   return { ok: true, ...result, gap, text: renderTree({ ...result, gap }) };
 }
 
+/**
+ * Tier 2 of the capture pipeline: what the store already knows, before writing to it.
+ *
+ * The counterpart to \`tree\`. Same scoping, same budget, opposite reader: \`tree\` tells an
+ * agent which note answers a question, this tells it which note it is about to write
+ * twice. One call, in a turn already paid for.
+ */
+function cmdBrief(opts) {
+  const cfg = loadConfig();
+  const db = openDb();
+  // \`--repo\` with no value means every repo, matching tree. Anything else names one.
+  const repo = opts.repo === true ? null : (opts.repo ?? currentRepo());
+  const result = buildBrief(db, { repo, cfg });
+  db.close();
+  return { ok: true, ...result, text: renderBrief(result) };
+}
+
 function cmdGet(opts) {
   const cfg = loadConfig();
   const id = opts._[0];
@@ -481,6 +501,7 @@ function cmdCompact() {
     ...r.decayed.map((d) => `archived ${d.id}, last seen ${d.lastSeen}`),
     ...r.malformed.map((m) => `warning: unparseable ${m.path}`),
     `digest ${r.digestChars} chars`,
+    `capture nudge ${r.nudgeChars} chars`,
     ...r.skills.map((s) => `updated description in ${s}`),
     ...(r.skipped || []).map(
       (s) => `skipped ${s}: inside this package's git checkout, so the file is tracked`
@@ -553,6 +574,11 @@ function cmdDoctor() {
   const digest = buildDigest(db, { cfg });
   add('digest within cap', digest.length <= cfg.digestChars, `${digest.length}/${cfg.digestChars} chars`);
 
+  // The nudge shares the cap and the silent fallback: over it, Tier 1 quietly becomes
+  // the generic string, which reads exactly like a store with nothing to report.
+  const nudge = buildCaptureNudge(db, { cfg });
+  add('capture nudge within cap', nudge.length <= cfg.digestChars, `${nudge.length}/${cfg.digestChars} chars`);
+
   const registered = cfg.skillPaths || [];
   const missing = registered.filter((p) => !existsSync(p));
   add(
@@ -640,7 +666,7 @@ function cmdDoctor() {
   // Staleness is a report, not a failure. Being told about it is the whole feature.
   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, gap, digest, text };
+  return { ok: fatal.length === 0, checks, stale, gap, digest, nudge, text };
 }
 
 // --- dispatch ---------------------------------------------------------------
@@ -974,6 +1000,7 @@ const COMMANDS = {
   init: cmdInit,
   index: cmdIndex,
   tree: cmdTree,
+  brief: cmdBrief,
   get: cmdGet,
   search: cmdSearch,
   write: cmdWrite,

src/compact.js

@@ -1,11 +1,11 @@
 import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { join, sep } from 'node:path';
+import { join, sep, basename, dirname } from 'node:path';
 import { loadConfig, paths } from './config.js';
 import { listNotes, archiveNote, contentHash, nowIso, serializeNote } from './store.js';
 import { atomicWrite } from './atomic.js';
 import { openDb, reindex } from './index-db.js';
-import { buildDigest, buildTree, renderTree } from './digest.js';
+import { buildDigest, buildCaptureNudge, buildTree, renderTree } from './digest.js';
 
 /**
  * Compaction is pure code. No model is involved, and none should be.
@@ -203,9 +203,33 @@ export function writeSkillDescription(skillPath, description) {
   return true;
 }
 
-/** Regenerate everything derived: ROUTING.md and each installed skill description. */
+/**
+ * Which skill a registered path belongs to.
+ *
+ * Derived from the path rather than stored beside it, because `setup` is what creates
+ * these paths and it only ever creates the two shapes below. Keeping `skillPaths` a
+ * flat list of strings means no config migration and no second source of truth about
+ * which skill is which — the layout already answers it.
+ */
+export function skillNameFromPath(p) {
+  const file = basename(p);
+  if (file === 'SKILL.md') return basename(dirname(p));
+  const m = file.match(/^(.+)\.prompt\.md$/);
+  return m ? m[1] : null;
+}
+
+/**
+ * Regenerate everything derived: ROUTING.md and each installed skill description.
+ *
+ * Two descriptions are generated, not one, and which a path receives is decided by the
+ * skill it belongs to. `remember` gets the capture nudge; everything else registered
+ * gets the digest. Before this, one text was written to every registered path, which is
+ * why `setup` could only ever register `recall` — handing `remember` the digest would
+ * have replaced a good description with a description of the wrong thing.
+ */
 function regenerate(db, cfg) {
   const digest = buildDigest(db, { cfg });
+  const nudge = buildCaptureNudge(db, { cfg });
   const tree = buildTree(db, { all: true, cfg });
 
   const routing = [
@@ -227,9 +251,18 @@ function regenerate(db, cfg) {
       skipped.push(p);
       continue;
     }
-    if (writeSkillDescription(p, digest)) skills.push(p);
+    const text = skillNameFromPath(p) === 'remember' ? nudge : digest;
+    if (writeSkillDescription(p, text)) skills.push(p);
   }
-  return { digest, digestChars: digest.length, routing: paths.routing, skills, skipped };
+  return {
+    digest,
+    digestChars: digest.length,
+    nudge,
+    nudgeChars: nudge.length,
+    routing: paths.routing,
+    skills,
+    skipped,
+  };
 }
 
 /**

src/config.js

@@ -102,6 +102,7 @@ export const DEFAULTS = {
   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
+  briefRecentMinutes: 120, // window the capture brief calls already covered
 };
 
 // Written by the installer: every SKILL.md whose description compact regenerates.