@vib795/agent-memory 0.1.14 → 0.2.0

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.
@@ -86,6 +94,44 @@ recursive CTE *is* the graph engine, and `UNION` plus a depth bound is what keep
 - **Constraints are never dropped.** At any cap, in either tier. A constraint is what
   stops an agent burning a retry loop on an approach that was never going to ship.
 
+## Engagements
+
+If you work for more than one client on one machine, knowledge from one of them is
+not the next one's to see. An engagement is a **separate store**, and switching is a
+path change rather than a filter:
+
+```bash
+agent-memory engagement                    # which one is active, and why
+agent-memory engagement list               # all of them, with note counts
+agent-memory engagement use acme           # the fallback for every window
+agent-memory engagement purge acme --yes   # delete that client's store entirely
+```
+
+Pin a client's whole tree instead of remembering to switch. One file at the top of
+it, and every repository beneath is in that engagement:
+
+```bash
+echo acme > ~/clients/acme/.agent-memory-engagement
+```
+
+Resolution order is `AGENT_MEMORY_ENGAGEMENT`, then the nearest marker file walking
+up from where you are, then the machine-wide pointer, then `default`. `doctor` and
+`engagement` both print which one decided it, because the failure worth preventing is
+believing you are in one client's store while writing to another.
+
+**The isolation is structural, not a filter.** Each engagement is its own directory,
+its own markdown and its own index, so `search`, `get` and `tree` cannot reach across
+even by exact id — there is no query to forget. Filtering would have to be remembered
+at fourteen separate read paths, and two of them were already missed before this
+existed.
+
+That also makes removal something you can evidence rather than assert: `purge` deletes
+a directory and reports the count, and refuses without `--yes` after telling you
+exactly what would go.
+
+Everything already captured stays in `default`, at the same path as before. Nothing
+migrates and nothing changes until you create a second engagement.
+
 ## CLI
 
 ```
@@ -336,7 +382,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]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vib795/agent-memory",
-  "version": "0.1.14",
+  "version": "0.2.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/src/cli.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync, rmSync, readdirSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
-import { loadConfig, saveConfig, paths, NOTE_TYPES } from './config.js';
+import {
+  loadConfig, saveConfig, paths, NOTE_TYPES, ENGAGEMENT, ENGAGEMENT_RE, ENGAGEMENT_POINTER,
+  ENGAGEMENT_MARKER, DEFAULT_ENGAGEMENT, STORE_BASE, engagementRoot,
+} from './config.js';
 import { ensureStore, writeNote, normalizeTitle, listNotes } from './store.js';
 import {
   openDb, reindex, searchNodes, getNodeRow, markAccessed, nodeCount, hasFts,
@@ -13,6 +16,7 @@ import { staleness, currentRepo, reviewCandidates, captureGap } from './stalenes
 import { setup as runSetup, unlinkSkills, danglingSkillLinks, SKILLS } from './setup.js';
 import { detectTargets, installableTargets } from './targets.js';
 import { join } from 'node:path';
+import { atomicWrite } from './atomic.js';
 
 /**
  * One process, one answer.
@@ -82,8 +86,11 @@ const USAGE = `agent-memory — durable cross-repo knowledge for coding agents
         [--source <name>] [--repo <name>]
   compact                                dedup, decay, reindex, regenerate
   doctor                                 preflight and health report
+  engagement [show|list|use <name>]      which client store this window writes to
+             [purge <name> --yes]        delete one engagement's store entirely
 
 Add --json to any command for machine-readable output.
+Engagement: ${ENGAGEMENT.name} (${ENGAGEMENT.source})
 Store: ${paths.root}`;
 
 // --- commands ---------------------------------------------------------------
@@ -422,6 +429,10 @@ function cmdDoctor() {
   const checks = [];
   const add = (name, ok, detail) => checks.push({ name, ok, detail });
 
+  // First, because everything below it is a fact about one engagement's store and
+  // reading it against the wrong client is the mistake this is here to prevent.
+  add('engagement', true, `${ENGAGEMENT.name} (${ENGAGEMENT.source})`);
+
   add('node version', nodeVersionOk(), `${process.versions.node} (need >= ${MIN_NODE.join('.')})`);
   if (!nodeVersionOk()) {
     return {
@@ -550,6 +561,154 @@ function cmdDoctor() {
 
 // --- dispatch ---------------------------------------------------------------
 
+/**
+ * Show, switch and purge engagements.
+ *
+ * Each engagement is a whole store on disk, so switching is a path change and
+ * purging is a directory removal. Nothing here filters anything: the isolation is
+ * structural, and a subcommand that got it wrong could not leak across the boundary
+ * even if it tried.
+ */
+function cmdEngagement(opts) {
+  const sub = opts._[0] ?? 'show';
+
+  if (sub === 'show') {
+    return {
+      ok: true,
+      engagement: ENGAGEMENT.name,
+      source: ENGAGEMENT.source,
+      store: paths.root,
+      text: [
+        `engagement: ${ENGAGEMENT.name}`,
+        `decided by: ${ENGAGEMENT.source}`,
+        `store:      ${paths.root}`,
+      ].join('\n'),
+    };
+  }
+
+  if (sub === 'list') {
+    const found = listEngagements();
+    return {
+      ok: true,
+      engagements: found,
+      text: found
+        .map((e) => `${e.name === ENGAGEMENT.name ? '*' : ' '} ${e.name.padEnd(24)} ${e.notes} notes`)
+        .join('\n'),
+    };
+  }
+
+  if (sub === 'use') {
+    const name = opts._[1];
+    if (!name || !ENGAGEMENT_RE.test(name)) return badEngagementName(name);
+    mkdirSync(STORE_BASE, { recursive: true });
+    atomicWrite(ENGAGEMENT_POINTER, `${name}\n`);
+    return {
+      ok: true,
+      engagement: name,
+      store: engagementRoot(name),
+      text: [
+        `engagement: ${name}`,
+        `store:      ${engagementRoot(name)}`,
+        '',
+        'This is the fallback for every window on this machine. To pin one client tree',
+        `instead, put the name in a ${ENGAGEMENT_MARKER} file at the top of it.`,
+      ].join('\n'),
+    };
+  }
+
+  if (sub === 'purge') {
+    const name = opts._[1];
+    if (!name || !ENGAGEMENT_RE.test(name)) return badEngagementName(name);
+    if (name === DEFAULT_ENGAGEMENT) {
+      return {
+        ok: false,
+        error: 'the default engagement cannot be purged',
+        text: 'The default engagement cannot be purged. Delete individual notes instead.',
+      };
+    }
+    const dir = engagementRoot(name);
+    if (!existsSync(dir)) {
+      return { ok: false, error: `no engagement named ${name}`, text: `No engagement named ${name}.` };
+    }
+    const notes = countNotes(dir);
+    if (!opts.yes) {
+      // Deleting a client's captured knowledge is not something to do because a name
+      // was typed. Say exactly what goes, and make the caller ask again.
+      return {
+        ok: false,
+        error: 'purge requires --yes',
+        engagement: name,
+        notes,
+        text: [
+          `This deletes ${notes} note${notes === 1 ? '' : 's'} and the whole store at:`,
+          `  ${dir}`,
+          '',
+          'Nothing else is touched, and this cannot be undone. To go ahead:',
+          `  agent-memory engagement purge ${name} --yes`,
+        ].join('\n'),
+      };
+    }
+    rmSync(dir, { recursive: true, force: true });
+    return {
+      ok: true,
+      engagement: name,
+      notes,
+      removed: dir,
+      // Stated as a fact someone can check, because "we deleted it" is a claim that
+      // eventually has to be evidenced rather than asserted.
+      text: [
+        `Purged engagement ${name}: ${notes} note${notes === 1 ? '' : 's'} removed.`,
+        `${dir} no longer exists.`,
+      ].join('\n'),
+    };
+  }
+
+  return {
+    ok: false,
+    error: `unknown subcommand ${sub}`,
+    text: 'Usage: agent-memory engagement [show|list|use <name>|purge <name> --yes]',
+  };
+}
+
+function badEngagementName(name) {
+  return {
+    ok: false,
+    error: 'invalid engagement name',
+    text: [
+      name ? `"${name}" is not a usable engagement name.` : 'An engagement name is required.',
+      'Names become directory names: lower case, digits and hyphens, up to 64 characters.',
+    ].join('\n'),
+  };
+}
+
+/** Markdown files under a store, counted without opening its index. */
+function countNotes(root) {
+  const dir = join(root, 'notes');
+  if (!existsSync(dir)) return 0;
+  let n = 0;
+  const walk = (d) => {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      if (entry.isDirectory()) walk(join(d, entry.name));
+      else if (entry.name.endsWith('.md')) n += 1;
+    }
+  };
+  walk(dir);
+  return n;
+}
+
+function listEngagements() {
+  const out = [{ name: DEFAULT_ENGAGEMENT, notes: countNotes(engagementRoot(DEFAULT_ENGAGEMENT)) }];
+  const dir = join(STORE_BASE, 'engagements');
+  if (existsSync(dir)) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) out.push({ name: entry.name, notes: countNotes(join(dir, entry.name)) });
+    }
+  }
+  // The active one may not exist on disk yet, and omitting it would read as absent.
+  if (!out.some((e) => e.name === ENGAGEMENT.name)) out.push({ name: ENGAGEMENT.name, notes: 0 });
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
 const COMMANDS = {
   setup: cmdSetup,
   uninstall: cmdUninstall,
@@ -561,6 +720,7 @@ const COMMANDS = {
   write: cmdWrite,
   compact: cmdCompact,
   doctor: cmdDoctor,
+  engagement: cmdEngagement,
 };
 
 function main(argv) {

package/src/config.js

@@ -1,14 +1,81 @@
 import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname, parse as parsePath } from 'node:path';
 import { homedir } from 'node:os';
 import { atomicWrite } from './atomic.js';
 
 // The store lives outside every repository on purpose. That is what makes a note
 // written in one window readable from a window opened on a different project.
-export const STORE_ROOT =
+export const STORE_BASE =
   process.env.AGENT_MEMORY_HOME ||
   join(process.env.USERPROFILE || homedir(), '.agents', 'memory');
 
+export const DEFAULT_ENGAGEMENT = 'default';
+
+/** Where the pointer to the active engagement lives, outside every engagement. */
+export const ENGAGEMENT_POINTER = join(STORE_BASE, '.engagement');
+
+/** Engagement names become directory names, so they have to be safe as one. */
+export const ENGAGEMENT_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/** The file a client tree carries to pin itself to an engagement. */
+export const ENGAGEMENT_MARKER = '.agent-memory-engagement';
+
+/**
+ * Which engagement this process is working in, and how that was decided.
+ *
+ * A consultant runs several clients through one machine, and knowledge from one is
+ * not the next one's to see. The boundary is a separate store per engagement rather
+ * than a column to filter on, because filtering has to be remembered at every read
+ * and there are fourteen of them; two were already missed. A separate directory
+ * cannot be forgotten, and purging one is a directory removal that can be shown to
+ * have happened.
+ *
+ * The marker file is what makes this survive real use: drop one at the root of a
+ * client's tree and every repository beneath it is in that engagement, with nothing
+ * to remember when switching windows.
+ */
+export function resolveEngagement(cwd = process.cwd()) {
+  const env = process.env.AGENT_MEMORY_ENGAGEMENT?.trim();
+  if (env) return { name: env, source: 'AGENT_MEMORY_ENGAGEMENT' };
+
+  let dir = cwd;
+  for (;;) {
+    const marker = join(dir, ENGAGEMENT_MARKER);
+    if (existsSync(marker)) {
+      try {
+        const name = readFileSync(marker, 'utf8').trim().split('\n')[0].trim();
+        if (name) return { name, source: marker };
+      } catch {
+        // An unreadable marker is not a reason to fall back silently to another
+        // client's store. Treat it as unset and let the pointer or default decide.
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir || dir === parsePath(dir).root) break;
+    dir = parent;
+  }
+
+  if (existsSync(ENGAGEMENT_POINTER)) {
+    try {
+      const name = readFileSync(ENGAGEMENT_POINTER, 'utf8').trim();
+      if (name) return { name, source: ENGAGEMENT_POINTER };
+    } catch {
+      /* fall through to the default */
+    }
+  }
+  return { name: DEFAULT_ENGAGEMENT, source: 'default' };
+}
+
+/** The store directory for an engagement. The default one is the base itself. */
+export function engagementRoot(name) {
+  return name === DEFAULT_ENGAGEMENT ? STORE_BASE : join(STORE_BASE, 'engagements', name);
+}
+
+export const ENGAGEMENT = resolveEngagement();
+
+// Resolved once per process, like everything else here. One process, one answer.
+export const STORE_ROOT = engagementRoot(ENGAGEMENT.name);
+
 export const NOTE_TYPES = ['system', 'decision', 'convention', 'constraint'];
 
 export const paths = {