@vib795/agent-memory 0.6.4 → 0.7.0

package/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 |
@@ -427,15 +430,31 @@ GitHub, and it is the path to use behind a proxy that blocks or quarantines npm:
 
 ```bash
 git clone https://github.com/vib795/agent-memory.git
-npm install -g ./agent-memory
+cd agent-memory && npm pack
+npm install -g ./vib795-agent-memory-*.tgz
 agent-memory setup
 ```
 
-**Do not install from the git URL directly.** `npm install -g <git-url>` does not
+**Pack first; do not install the directory.** `npm install -g ./agent-memory` looks
+equivalent and is not: npm links the global install to that folder rather than copying
+it, which shows up as an arrow in `npm list -g`:
+
+```
+`-- @vib795/agent-memory@0.6.5 -> .\..\..\..\agent-memory
+```
+
+Move or delete the clone afterwards and the global install points at nothing — the same
+breakage as the git-URL case below, arriving later and harder to trace. Installing a
+packed tarball copies, so the clone becomes disposable. Verified on npm 11.x.
+
+**Do not install from the git URL directly either.** `npm install -g <git-url>` does not
 work for this package: npm resolves a git install through
 `~/.npm/_cacache/tmp/git-clone*` and then removes that directory, leaving the global
-install pointing at a path that no longer exists. Cloning first avoids npm's git
-handling entirely. Verified on npm 11.18.
+install pointing at a path that no longer exists. Verified on npm 11.18.
+
+**And run the installed binary, not the checkout.** Skill links resolve relative to the
+code that creates them, so `npm run setup` inside a clone aims every link at that clone.
+Use `agent-memory setup`, which runs the copy npm installed.
 
 Every release is mirrored to **GitHub Packages**. Treat that as redundancy rather
 than a second front door: GitHub Packages requires authentication even for public
@@ -534,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/package.json

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

package/skills/handoff/SKILL.md

@@ -129,6 +129,12 @@ repos:
 agent: copilot | claude-code
 ---
 
+> **If the repository you are reading this in is not listed under `repos:` above, you are
+> replicating this work, not continuing it.** Follow Execution protocol, re-derive every
+> path, branch name and version from the repository you are actually in, and read Next
+> action as a record of what happened elsewhere rather than as an instruction. Do not open
+> the repository this was written in.
+
 ## Orientation
 
 3 to 5 sentences. What this thread is trying to accomplish and where it stands.
@@ -193,7 +199,9 @@ These separate a useful handoff from a readable paragraph that still leaves ques
 3. Never quote or paraphrase the transcript. Record conclusions, not the path to them.
 4. Anchor claims to a file path or a decision number. "We refactored the service
    layer" is a failure. "`src/services/order.ts:42` now returns `Result<T>` instead
-   of throwing" is not.
+   of throwing" is not. When the thread spans more than one repository, name the repo
+   alongside the path: an unqualified path in a two-repo thread is a path the reader
+   goes looking for in the wrong tree, and finding it there is worse than not finding it.
 5. Record only what the conversation actually established. Prefix anything you
    inferred with `inferred:` so the next agent knows to verify it.
 6. Never inline a diff or a patch. List changed files with one line each.
@@ -296,8 +304,15 @@ request, which is the only reason this step belongs here rather than in its own
 - Zero durable knowledge is a valid outcome. Writing nothing beats writing noise.
 <!-- extraction-rules:end -->
 
-Your Decisions table and Constraints section are usually already the durable part.
-The Current task state section never is.
+Your Decisions table, Constraints section and **Execution protocol** are usually already
+the durable part. Write the protocol as a `convention`: it is the section a second
+repository actually needs, and the one most easily lost, because a sequence of steps
+reads like status even when it describes how every run of this kind is done. A handoff
+that records the protocol while the graph does not still leaves the next repository
+guessing — the handoff is read once, by whoever was handed the path, and the graph is
+what `/recall` reaches for afterwards.
+
+The Current task state section never is durable.
 
 ### Write it (ONE terminal call)
 

package/skills/recall/SKILL.md

@@ -62,6 +62,11 @@ and what a regex does badly.
 - Pick 1 to 3 ids. More than 3 means the question is really several questions.
 - Always include a `constraint` that touches the subject, even when the user did not
   ask about limits. Constraints are what stop an approach that cannot ship.
+- When the question is about **doing** the work rather than understanding it, also
+  include the `convention` that governs how that kind of work is executed. A constraint
+  tells you which steps are forbidden; only a procedure tells you what order the allowed
+  ones go in. Branch choreography and deploy ordering live here, and they are what a
+  second repository gets wrong when nobody surfaces them.
 - Nothing in the tree looks relevant → go to Step 4.
 
 ---

package/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 -->

package/src/cli.js

@@ -10,12 +10,15 @@ 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';
 import { detectTargets, installableTargets } from './targets.js';
-import { join, dirname } from 'node:path';
+import { join, dirname, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { atomicWrite } from './atomic.js';
 import { redactNodeForExport, buildReceipt, renderReceipt } from './pii.js';
 
@@ -29,6 +32,41 @@ import { redactNodeForExport, buildReceipt, renderReceipt } from './pii.js';
 
 const MIN_NODE = [22, 5];
 
+/**
+ * Where this process is actually running from, and what version it is.
+ *
+ * "What am I running" is the first question in every install problem and used to need
+ * `npm list -g` to answer, which reports what npm believes rather than what is on PATH.
+ * These read the package next to the running code, so they answer for the copy that
+ * will actually execute.
+ */
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..');
+}
+
+function installedVersion() {
+  try {
+    return JSON.parse(readFileSync(join(packageRoot(), 'package.json'), 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Whether the running code lives outside any `node_modules` tree.
+ *
+ * `npm install -g <folder>` links rather than copies, so a global install can be a
+ * pointer at a checkout the user will eventually tidy away — and skill links, which
+ * resolve relative to this file, follow it there. Node resolves symlinks before it sets
+ * `import.meta.url`, so the link itself is already invisible from in here; what stays
+ * visible, and is the thing that actually matters, is that the code is not sitting in an
+ * installed package. Running from a working copy is legitimate, so this reports the
+ * condition rather than failing on it.
+ */
+function runningFromWorkingCopy() {
+  return !packageRoot().split(sep).includes('node_modules');
+}
+
 function parseArgs(argv) {
   const opts = { _: [] };
   for (let i = 0; i < argv.length; i++) {
@@ -85,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
@@ -93,6 +132,8 @@ const USAGE = `agent-memory — durable cross-repo knowledge for coding agents
   engagement [show|list|use <name>]      which client store this window writes to
              [purge <name> --yes]        delete one engagement's store entirely
 
+  --version                              this version, and the path it runs from
+
 Add --json to any command for machine-readable output.
 Engagement: ${ENGAGEMENT.name} (${ENGAGEMENT.source})
 Store: ${paths.root}`;
@@ -179,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.',
     );
   }
@@ -248,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];
@@ -443,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`
@@ -460,6 +519,25 @@ function cmdDoctor() {
   // reading it against the wrong client is the mistake this is here to prevent.
   add('engagement', true, `${ENGAGEMENT.name} (${ENGAGEMENT.source})`);
 
+  // Second, because "which version is this" preceded every other question in the one
+  // install failure this tool has actually been debugged through, and answering it
+  // needed a separate npm command that reports what npm believes rather than what ran.
+  add('version', true, `${installedVersion()} at ${packageRoot()}`);
+
+  // Skill links point at whatever copy of the code creates them. When that copy is a
+  // working directory rather than an installed package, deleting the directory dangles
+  // every link at once — which is exactly how this tool's own skill links were lost.
+  // Reported, not failed: running from a checkout is a normal thing to do deliberately.
+  add(
+    'runs from an installed package',
+    true,
+    runningFromWorkingCopy()
+      ? `no — working copy at ${packageRoot()}; skill links will point here, so moving or ` +
+        'deleting it breaks them. For a durable install: `npm pack` then ' +
+        '`npm install -g <tgz>`, and re-run setup.'
+      : 'yes',
+  );
+
   add('node version', nodeVersionOk(), `${process.versions.node} (need >= ${MIN_NODE.join('.')})`);
   if (!nodeVersionOk()) {
     return {
@@ -496,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(
@@ -583,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 ---------------------------------------------------------------
@@ -917,6 +1000,7 @@ const COMMANDS = {
   init: cmdInit,
   index: cmdIndex,
   tree: cmdTree,
+  brief: cmdBrief,
   get: cmdGet,
   search: cmdSearch,
   write: cmdWrite,
@@ -933,6 +1017,12 @@ function main(argv) {
     process.stdout.write(`${USAGE}\n`);
     return 0;
   }
+  if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
+    // Prints the path as well as the number. A version alone cannot tell you that the
+    // binary on PATH belongs to a different install than the one you just upgraded.
+    process.stdout.write(`${installedVersion()}\n${packageRoot()}\n`);
+    return 0;
+  }
   const fn = COMMANDS[cmd];
   if (!fn) {
     process.stderr.write(`Unknown command ${JSON.stringify(cmd)}.\n\n${USAGE}\n`);

package/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,
+  };
 }
 
 /**

package/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.

package/src/digest.js

@@ -1,4 +1,5 @@
-import { loadConfig } from './config.js';
+import { loadConfig, NOTE_TYPES } from './config.js';
+import { captureGap, currentRepo } from './staleness.js';
 
 /**
  * Two-tier routing.
@@ -12,6 +13,11 @@ import { loadConfig } from './config.js';
  *
  * 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 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.
  */
 
 // Never dropped from either tier. A constraint is what stops an agent from burning
@@ -126,6 +132,111 @@ export function buildDigest(db, { cfg = loadConfig() } = {}) {
   return out;
 }
 
+// The routing clause for `remember`, and the mirror of USE_WHEN. It carries both the
+// asked form and the unasked one, because the unasked one is the entire reason this
+// description is regenerated at all: a memory that only grows when someone remembers
+// to grow it stays thin. Never dropped, for the same reason USE_WHEN is never dropped.
+const CAPTURE_WHEN =
+  'Use when the user says remember this, save this or note this down — and invoke it ' +
+  'unasked the moment a decision settles, a constraint surfaces, a root cause is ' +
+  'found or a convention is agreed.';
+
+const NUDGE_GENERIC = 'Capture durable project knowledge into a cross-repo memory graph.';
+
+/**
+ * Notes that speak for this repository, counted the way `captureGap` scopes them.
+ *
+ * A node with no repos is global and applies everywhere, so it counts here; a node
+ * claiming other repos does not. This mirrors `captureGap`'s filter deliberately —
+ * two different answers to "does this note cover me" in one description would be a
+ * bug the reader could see.
+ */
+function repoScopedCount(db, repo, type = null) {
+  // Bound in SQL order: the type predicate precedes the repo one in the statement.
+  return db
+    .prepare(`
+      SELECT COUNT(*) AS c
+        FROM nodes n
+       WHERE n.archived = 0 ${type ? 'AND n.type = ?' : ''}
+         AND (NOT EXISTS (SELECT 1 FROM node_repos r WHERE r.node_id = n.id)
+              OR EXISTS (SELECT 1 FROM node_repos r WHERE r.node_id = n.id AND r.repo = ?))
+    `)
+    .get(...(type ? [type, repo] : [repo])).c;
+}
+
+/**
+ * Tier 1, second occupant: the `remember` skill description.
+ *
+ * `captureGap` has known since 0.5 how far a repository has moved with nothing written
+ * down in it, and that answer went only to `doctor` — a command a person runs on
+ * purpose, which is precisely the person who did not need telling. The signal never
+ * reached the one reader who could act on it mid-conversation. This routes it to the
+ * surface that is already loaded into every turn.
+ *
+ * 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; "remember to capture things" is wallpaper it stops seeing by the third
+ * turn. The distinction is the whole design: code supplies the timing signal, the model
+ * still decides whether anything durable actually happened.
+ *
+ * It goes quiet on a covered repository. A description that nags at a store which is
+ * already current teaches the reader to discount the line, and then it is worth nothing
+ * on the day it has something to say.
+ *
+ * Scoping caveat, stated because it is visible in the output: the gap is per repository
+ * and `compact` runs wherever the user happens to be, so this describes the repo where
+ * compaction last ran. That is why every variant names the repo out loud — a reader in
+ * a different tree can see the mismatch rather than act on a number that is not theirs.
+ * `maybeCompact` re-points it on the next write, so it self-corrects with use.
+ */
+export function buildCaptureNudge(db, { cfg = loadConfig(), cwd = process.cwd(), repo, gap } = {}) {
+  const g = gap !== undefined ? gap : captureGap(db, { cwd, cfg, repo });
+
+  const compose = (head) => {
+    const out = head ? `${head} ${CAPTURE_WHEN}` : `${NUDGE_GENERIC} ${CAPTURE_WHEN}`;
+    // Nothing here is a list, so there is no elastic middle to shed one item at a
+    // time. Over the cap, drop the whole head rather than truncate mid-sentence: a
+    // description that stops in the middle of a number reads as corrupted, and the
+    // routing clause is the part that must survive either way.
+    return out.length > cfg.digestChars ? `${NUDGE_GENERIC} ${CAPTURE_WHEN}` : out;
+  };
+
+  // Outside a repository there is no gap to report and no repo to name. Say what the
+  // skill is for and stop, rather than inventing a number.
+  if (!g) return compose(null);
+
+  // Never captured in this repository. `captureGap` counts only notes carrying a
+  // `captured_sha`, so this is its answer to "has anyone written anything down here",
+  // 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.
+  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,
+    );
+  }
+
+  // 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}.`);
+
+  // 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
+  // the thing most likely to save a future session a wasted retry loop.
+  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 — ` +
+        '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.`);
+}
+
 /**
  * Tier 2: the routing tree, scoped.
  *
@@ -207,3 +318,167 @@ export function renderTree(result) {
   if (result.gap?.note) out.push(result.gap.note);
   return out.join('\n');
 }
+
+/**
+ * What each type is for, shown only where one is missing.
+ *
+ * Taken from the table in the remember skill so there is one wording, not two that
+ * drift. Printed against a zero count it answers the question the count raises: not
+ * "you have none of these" but "here is what one would have said".
+ */
+const TYPE_HINT = {
+  constraint: 'what the environment or the org forbids',
+  decision: 'what was chosen, why, and what was rejected',
+  convention: 'how this codebase does something, and the gotcha',
+  system: 'how a thing works, anchored to a path:line',
+};
+
+/** Notes per type under the same scoping the tree uses, zeros included. */
+function typeCounts(db, repo) {
+  const rows = repo
+    ? db
+        .prepare(`
+          SELECT n.type AS type, 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.scope = 'global' OR r.repo = ?)
+           GROUP BY n.type
+        `)
+        .all(repo)
+    : db.prepare('SELECT type, COUNT(*) AS c FROM nodes WHERE archived = 0 GROUP BY type').all();
+
+  // Seeded from NOTE_TYPES so a type with no rows reports 0 rather than going absent.
+  // The absent ones are the entire point of this section.
+  const counts = new Map(NOTE_TYPES.map((t) => [t, 0]));
+  for (const r of rows) counts.set(r.type, r.c);
+  return counts;
+}
+
+/**
+ * Ids written recently enough that capturing them again would be a duplicate.
+ *
+ * The skill already forbids re-capturing a juncture that came up twice in one
+ * conversation, and that rule currently depends on the model remembering across a
+ * long turn. This makes it data instead.
+ *
+ * Recency is a proxy and is labelled as one: the CLI has no notion of a session, and
+ * inventing one would mean tracking state this tool deliberately does not keep. A
+ * window wide enough to cover the working session is the honest approximation.
+ */
+function recentlyCaptured(db, repo, cfg, now) {
+  // 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');
+  const rows = repo
+    ? db
+        .prepare(`
+          SELECT DISTINCT n.id AS id, n.updated AS updated
+            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 = ?)
+           ORDER BY n.updated DESC, n.id
+        `)
+        .all(cutoff, repo)
+    : db
+        .prepare(`
+          SELECT id, updated FROM nodes
+           WHERE archived = 0 AND updated >= ? ORDER BY updated DESC, id
+        `)
+        .all(cutoff);
+  return rows.map((r) => r.id);
+}
+
+/**
+ * Tier 2 of the capture pipeline: what `remember` reads before it composes.
+ *
+ * The mirror of `buildTree`, scoped for a writer rather than a reader. Without it the
+ * skill composes blind, and blind composition has three failure modes this answers
+ * directly: it rewords a note that already exists (dedup is by exact content hash, so
+ * a paraphrase becomes a second node), it invents an `edges[].dst` id that never
+ * connects because a missing dst is legal, and it cannot see which type the store is
+ * missing at the one moment it is about to write something.
+ *
+ * One call, inside a turn that was already paid for. That economy is why the brief is
+ * a command the skill runs rather than anything loaded standing — and it matters more
+ * on Copilot, where a second round trip is a second premium request.
+ *
+ * The list is `buildTree`'s, deliberately: two answers to "which notes speak for this
+ * repo" in one tool would be a bug the reader could see.
+ */
+export function buildBrief(db, { repo, cwd = process.cwd(), cfg = loadConfig(), gap, now = Date.now() } = {}) {
+  const here = repo === undefined ? currentRepo(cwd) : repo;
+  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);
+
+  return {
+    repo: here,
+    gap: g,
+    tree,
+    counts: Object.fromEntries(counts),
+    missing: NOTE_TYPES.filter((t) => counts.get(t) === 0),
+    recent: recentlyCaptured(db, here, cfg, now),
+    recentMinutes: cfg.briefRecentMinutes,
+    total: tree.total,
+  };
+}
+
+export function renderBrief(result) {
+  const { repo, gap, tree, counts, missing, recent, recentMinutes } = result;
+  const scope = 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
+  // has moved 300 commits since anyone wrote anything is burying its own headline.
+  // Composed from the gap fields rather than reusing \`gap.note\` verbatim: that string
+  // names the repo, and the header already has, so borrowing it stutters.
+  const state = !repo
+    ? `${tree.total} notes in the store`
+    : gap?.note && gap.notes === 0
+      ? `nothing captured here yet, over ${gap.commits} commits of history`
+      : gap?.note
+        ? `${gap.commits} commits since anything was captured here`
+        : `${tree.total} note${tree.total === 1 ? '' : 's'} here, capture is current`;
+  const out = [`# capture brief: ${scope} — ${state}`];
+
+  if (tree.lines.length) {
+    out.push('', 'already known here — write the gap, not these');
+    const width = tree.lines.reduce((w, e) => Math.max(w, e.id.length), 0);
+    for (const e of tree.lines) {
+      out.push(`${e.type.padEnd(10)} ${e.id.padEnd(width)}  ${e.title}${e.archived ? ' (archived)' : ''}`);
+    }
+    // Never silent. A truncated list that reads as the whole store is how a duplicate
+    // gets written against a note that was there the entire time.
+    if (tree.omitted.length) {
+      out.push(`${tree.omitted.length} more not shown, run agent-memory tree --all`);
+    }
+    out.push('', 'These ids are real. Use them as an `edges[].dst` or `supersedes` target;');
+    out.push('an id you invent is accepted and then never connects to anything.');
+  }
+
+  if (missing.length) {
+    out.push('', 'nothing captured yet in these types');
+    const width = missing.reduce((w, t) => Math.max(w, t.length), 0);
+    for (const t of missing) out.push(`  ${t.padEnd(width)}  ${TYPE_HINT[t]}`);
+  }
+
+  const present = Object.entries(counts).filter(([, c]) => c > 0);
+  if (present.length) {
+    out.push('', `counts: ${present.map(([t, c]) => `${t} ${c}`).join(', ')}`);
+  }
+
+  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.
+    out.push(
+      '',
+      `captured in the last ${recentMinutes} minutes, so already covered: ${recent.join(', ')}`,
+    );
+  }
+
+  if (!tree.lines.length && !recent.length) {
+    out.push('', 'The store holds nothing for this repository yet. Anything durable is new.');
+  }
+  return out.join('\n');
+}

package/src/setup.js

@@ -200,14 +200,27 @@ export function unlinkSkills() {
   return { removed, kept };
 }
 
+/**
+ * Skills whose description `compact` regenerates from store state.
+ *
+ * `recall` advertises what the store knows. `remember` advertises what it is missing,
+ * which is the only form of that signal that reaches the model at the moment capture is
+ * worth doing — `captureGap` had computed it since 0.5 and sent it only to `doctor`, a
+ * command run by the one person who did not need telling.
+ *
+ * `handoff` is deliberately absent: it describes itself, and there is no store-derived
+ * state that would make its description more useful than the one it ships with.
+ */
+export const REGENERATED = ['recall', 'remember'];
+
 /**
  * Install into every agent present on this machine, then build the store.
  *
- * Only `recall` is registered for description regeneration. `compact` overwrites the
- * description of every path it is given, and handoff and remember describe
- * themselves; registering all three would replace two good descriptions with a third.
- * Copies and prompt files register their own path, because rewriting the packaged
- * original would never reach them.
+ * Only the skills in `REGENERATED` are registered, and `compact` now picks the text per
+ * skill rather than writing one digest to every path it is given. That is what makes
+ * registering a second skill safe; before it, doing so would have replaced a good
+ * description with a description of the wrong thing. Copies and prompt files register
+ * their own path, because rewriting the packaged original would never reach them.
  */
 export function setup({ compactFn } = {}) {
   const targets = installableTargets();
@@ -241,9 +254,11 @@ export function setup({ compactFn } = {}) {
   }
 
   const skillPaths = [
-    join(packagedSkillsDir(), 'recall', 'SKILL.md'),
-    ...copies.filter((c) => c.name === 'recall').map((c) => join(c.path, 'SKILL.md')),
-    ...installed.filter((i) => i.mode === 'prompt' && i.name === 'recall').map((i) => i.path),
+    ...REGENERATED.map((name) => join(packagedSkillsDir(), name, 'SKILL.md')),
+    ...copies.filter((c) => REGENERATED.includes(c.name)).map((c) => join(c.path, 'SKILL.md')),
+    ...installed
+      .filter((i) => i.mode === 'prompt' && REGENERATED.includes(i.name))
+      .map((i) => i.path),
   ];
   // Drop registrations whose file is gone before adding the current ones. Renaming
   // the checkout, moving it, or reinstalling under a different prefix each leave a