@vib795/agent-memory 0.2.0 → 0.3.1

package/README.md

@@ -94,6 +94,36 @@ 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.
 
+## Carrying knowledge between machines
+
+Client work usually lives in its own environment, and when the engagement ends the
+environment goes with it. What should survive is the part that was never the
+client's — the constraints your org imposes, the conventions you follow, what you
+have learned about working under them. What must not survive is their architecture.
+
+```bash
+agent-memory export --out carry.json     # global scope only, by default
+agent-memory import carry.json --dry-run # see what would land
+agent-memory import carry.json
+```
+
+**The default is the safe one.** `export` emits `scope: global` notes and nothing
+else, so a note tied to a client repository cannot leave by forgetting a flag.
+Taking one is possible — `--scope all` — but it takes saying so.
+
+Two things are deliberately dropped on the way through:
+
+- **`captured_sha` is not carried.** It names a commit that exists in one repository
+  on one machine. Carried across, it would either read as current forever or claim
+  the history was rewritten; a staleness signal you cannot check is worse than none.
+- **`source` becomes `import`.** How a note was originally captured describes an
+  environment that no longer exists. Here the honest answer to where it came from is
+  that someone brought it in, and an audit should be able to tell which notes those
+  are.
+
+Importing the same file twice updates rather than duplicates, so re-running after a
+change is safe.
+
 ## Engagements
 
 If you work for more than one client on one machine, knowledge from one of them is
@@ -132,6 +162,17 @@ 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.
 
+**Two things sit outside the boundary, deliberately.** Skill installation is shared,
+because every engagement reads the same three skill files and registering them per
+engagement would leave the description stale after a switch. Handoff files are shared
+too — they live in `~/.agents/handoffs`, not in a store — so `purge` does not remove
+them and says so every time rather than letting "the store is gone" be mistaken for
+"their context is gone".
+
+Most people need none of this. If each client already gives you a separate machine,
+that boundary is stronger than anything here, and the default engagement is all you
+will ever touch.
+
 ## CLI
 
 ```

package/package.json

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

@@ -15,7 +15,7 @@ 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 } from 'node:path';
+import { join, dirname } from 'node:path';
 import { atomicWrite } from './atomic.js';
 
 /**
@@ -86,6 +86,9 @@ 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
+  export [--scope global|repo|all]       knowledge worth carrying to another machine
+         [--out <file>]                  defaults to global scope only
+  import <file> [--dry-run]              bring an export in, provenance intact
   engagement [show|list|use <name>]      which client store this window writes to
              [purge <name> --yes]        delete one engagement's store entirely
 
@@ -561,6 +564,151 @@ function cmdDoctor() {
 
 // --- dispatch ---------------------------------------------------------------
 
+const EXPORT_SCOPES = ['global', 'repo', 'all'];
+
+/**
+ * Take the knowledge that is yours to take.
+ *
+ * Client work tends to live in its own environment, and when the engagement ends the
+ * environment goes with it. What should survive is what was never the client's: your
+ * conventions, the constraints an org imposes, the way you have learned to work.
+ * What must not survive is their architecture.
+ *
+ * So this defaults to global scope and nothing else. Exporting a client's notes is
+ * possible, because sometimes it is legitimately yours to move, but it takes saying
+ * so out loud rather than forgetting a flag.
+ *
+ * `captured_sha` is deliberately dropped. It names a commit that does not exist
+ * anywhere else, and a staleness signal that cannot be checked is worse than none:
+ * it would either read as current forever or claim the history was rewritten.
+ */
+function cmdExport(opts) {
+  const scope = opts.scope === true ? 'global' : (opts.scope ?? 'global');
+  if (!EXPORT_SCOPES.includes(scope)) {
+    return {
+      ok: false,
+      error: `scope must be one of ${EXPORT_SCOPES.join('|')}`,
+      text: `--scope must be one of ${EXPORT_SCOPES.join(', ')}. Default is global.`,
+    };
+  }
+
+  const all = listNotes().filter((n) => !n.__error && n.id);
+  const active = opts['include-archived'] ? all : all.filter((n) => !n.archived);
+  const picked = active.filter((n) => {
+    const s = n.scope || (n.repos?.length ? 'repo' : 'global');
+    return scope === 'all' || s === scope;
+  });
+
+  const nodes = picked.map((n) => ({
+    id: n.id,
+    type: n.type,
+    title: n.title,
+    body: n.body,
+    scope: n.scope || (n.repos?.length ? 'repo' : 'global'),
+    repos: n.repos ?? [],
+    confidence: n.confidence ?? 'observed',
+    supersedes: n.supersedes ?? null,
+    edges: n.edges ?? [],
+    source: n.source ?? 'manual',
+  }));
+
+  const payload = `${JSON.stringify({ nodes }, null, 2)}\n`;
+  if (typeof opts.out === 'string') {
+    atomicWrite(opts.out, payload);
+    return {
+      ok: true,
+      exported: nodes.length,
+      scope,
+      out: opts.out,
+      text: `Exported ${nodes.length} ${scope}-scope note${nodes.length === 1 ? '' : 's'} to ${opts.out}.`,
+    };
+  }
+  // Straight to stdout so it pipes, with the count on stderr where it will not
+  // corrupt the document.
+  process.stderr.write(`${nodes.length} ${scope}-scope notes\n`);
+  return { ok: true, exported: nodes.length, scope, nodes, text: payload.trimEnd() };
+}
+
+/**
+ * Bring exported knowledge into this environment.
+ *
+ * Separate from `write` because `write` stamps the current repository and commit onto
+ * whatever it is given, which is right for capture and wrong for this: it would
+ * relabel another environment's knowledge as having been observed here.
+ */
+function cmdImport(opts) {
+  const file = opts._[0] ?? opts.from;
+  if (!file || file === true || (file !== '-' && !existsSync(file))) {
+    return {
+      ok: false,
+      error: 'import requires a file, or - to read stdin',
+      text: 'Usage: agent-memory import <file>   (or - to read stdin)',
+    };
+  }
+
+  let incoming;
+  try {
+    incoming = readNodesFrom(file);
+  } catch (err) {
+    return { ok: false, error: `unreadable JSON: ${err.message}`, text: `Unreadable JSON: ${err.message}` };
+  }
+
+  const db = openDb();
+  const existing = new Set(db.prepare('SELECT id FROM nodes').all().map((r) => r.id));
+
+  if (opts['dry-run']) {
+    db.close();
+    const lines = incoming.map(
+      (n) => `${existing.has(n.id) ? 'would update' : 'would create'} ${n.id} [${n.type}]`,
+    );
+    return {
+      ok: true,
+      dryRun: true,
+      count: incoming.length,
+      text: [...lines, '', 'Nothing written. Re-run without --dry-run to apply.'].join('\n'),
+    };
+  }
+
+  const written = [];
+  const failed = [];
+  const warnings = [];
+  for (const raw of incoming) {
+    // Nothing from this environment is stamped on: no repo, no commit. An imported
+    // note claims only what it claimed where it was written.
+    // Stamped `import`, not the source it carried. How it was captured describes an
+    // environment that no longer exists; here, the honest answer to where this came
+    // from is that someone brought it in, and an audit should be able to see which.
+    const node = { ...raw, source: 'import' };
+    delete node.captured_sha;
+    try {
+      const res = writeNote(node);
+      written.push({ id: res.node.id, type: res.node.type, created: res.created });
+      if (res.findings.length) {
+        warnings.push(
+          `${res.node.id}: redacted ${res.findings.map((f) => `${f.count}x ${f.kind}`).join(', ')}`,
+        );
+      }
+    } catch (err) {
+      failed.push({ id: raw?.id ?? null, errors: err.errors ?? [err.message] });
+    }
+  }
+
+  reindex(db);
+  db.close();
+
+  return {
+    ok: failed.length === 0,
+    imported: written.length,
+    failed,
+    warnings,
+    text: [
+      ...written.map((w) => `${w.created ? 'created' : 'updated'} ${w.id} [${w.type}]`),
+      ...warnings.map((w) => `warning: ${w}`),
+      ...failed.map((f) => `failed ${f.id}: ${f.errors.join('; ')}`),
+    ].join('\n'),
+  };
+}
+
 /**
  * Show, switch and purge engagements.
  *
@@ -659,6 +807,11 @@ function cmdEngagement(opts) {
       text: [
         `Purged engagement ${name}: ${notes} note${notes === 1 ? '' : 's'} removed.`,
         `${dir} no longer exists.`,
+        '',
+        // Said every time, because the gap between "the store is gone" and "their
+        // knowledge is gone" is exactly the assumption someone would make here.
+        'Handoff files are not part of an engagement store and were not touched.',
+        `Review ${join(dirname(STORE_BASE), 'handoffs')} yourself.`,
       ].join('\n'),
     };
   }
@@ -721,6 +874,8 @@ const COMMANDS = {
   compact: cmdCompact,
   doctor: cmdDoctor,
   engagement: cmdEngagement,
+  export: cmdExport,
+  import: cmdImport,
 };
 
 function main(argv) {

package/src/config.js

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join, dirname, parse as parsePath } from 'node:path';
 import { homedir } from 'node:os';
 import { atomicWrite } from './atomic.js';
@@ -85,6 +85,8 @@ export const paths = {
   db: join(STORE_ROOT, 'index.db'),
   routing: join(STORE_ROOT, 'ROUTING.md'),
   config: join(STORE_ROOT, 'config.json'),
+  // Machine-scoped keys live beside every engagement rather than inside one.
+  machineConfig: join(STORE_BASE, 'config.json'),
   typeDir: (type) => join(STORE_ROOT, 'notes', type),
   archiveTypeDir: (type) => join(STORE_ROOT, 'notes', 'archive', type),
 };
@@ -107,24 +109,41 @@ export const DEFAULTS = {
 // from a checkout or copied into place, and both are legitimate installs.
 export const LIST_KEYS = ['skillPaths'];
 
-export function loadConfig() {
-  if (!existsSync(paths.config)) return { ...DEFAULTS, skillPaths: [] };
+/** A malformed config must not take the store down. Absent and unreadable are equal. */
+function readJson(file) {
+  if (!existsSync(file)) return {};
   try {
-    const raw = JSON.parse(readFileSync(paths.config, 'utf8'));
-    const merged = { ...DEFAULTS, skillPaths: [] };
-    for (const [k, v] of Object.entries(raw)) {
-      if (k in DEFAULTS && typeof v === 'number' && Number.isFinite(v) && v > 0) merged[k] = v;
-      if (LIST_KEYS.includes(k) && Array.isArray(v)) {
-        merged[k] = v.filter((s) => typeof s === 'string' && s.trim());
-      }
-    }
-    return merged;
+    return JSON.parse(readFileSync(file, 'utf8'));
   } catch {
-    // A malformed config must not take the store down. Defaults are always valid.
-    return { ...DEFAULTS, skillPaths: [] };
+    return {};
   }
 }
 
+/**
+ * Config comes from two files, split by what each key actually describes.
+ *
+ * Where the skills are installed is a fact about this machine. Every engagement
+ * shares one set of skill files, so registering them per engagement meant `compact`
+ * had nothing to regenerate after a switch and the recall description kept
+ * advertising the previous engagement's topics — into the agent's context, which is
+ * the worst place for it. Caps like the digest size really are per-store, and stay
+ * there. For the default engagement both files are the same path and nothing moves.
+ */
+export function loadConfig() {
+  const merged = { ...DEFAULTS, skillPaths: [] };
+
+  for (const [k, v] of Object.entries(readJson(paths.config))) {
+    if (k in DEFAULTS && typeof v === 'number' && Number.isFinite(v) && v > 0) merged[k] = v;
+  }
+  const machine = readJson(paths.machineConfig);
+  for (const k of LIST_KEYS) {
+    if (Array.isArray(machine[k])) {
+      merged[k] = machine[k].filter((s) => typeof s === 'string' && s.trim());
+    }
+  }
+  return merged;
+}
+
 /**
  * Merge a patch into config.json.
  *
@@ -136,24 +155,37 @@ export function loadConfig() {
  * cannot quietly become permanent state.
  */
 export function saveConfig(patch) {
-  const current = existsSync(paths.config)
-    ? (() => {
-        try {
-          return JSON.parse(readFileSync(paths.config, 'utf8'));
-        } catch {
-          return {};
-        }
-      })()
-    : {};
-
-  const next = { ...current };
+  const sameFile = paths.config === paths.machineConfig;
+  const caps = readJson(paths.config);
+  const machine = sameFile ? caps : readJson(paths.machineConfig);
+
+  let capsDirty = false;
+  let machineDirty = false;
   for (const [k, v] of Object.entries(patch || {})) {
-    if (k in DEFAULTS && typeof v === 'number' && Number.isFinite(v) && v > 0) next[k] = v;
+    if (k in DEFAULTS && typeof v === 'number' && Number.isFinite(v) && v > 0) {
+      caps[k] = v;
+      capsDirty = true;
+    }
     if (LIST_KEYS.includes(k) && Array.isArray(v)) {
-      next[k] = [...new Set(v.filter((s) => typeof s === 'string' && s.trim()))].sort();
+      machine[k] = [...new Set(v.filter((s) => typeof s === 'string' && s.trim()))].sort();
+      machineDirty = true;
     }
   }
 
-  atomicWrite(paths.config, `${JSON.stringify(next, null, 2)}\n`);
-  return next;
+  if (sameFile) {
+    if (capsDirty || machineDirty) {
+      mkdirSync(dirname(paths.config), { recursive: true });
+      atomicWrite(paths.config, `${JSON.stringify(caps, null, 2)}\n`);
+    }
+    return { ...caps };
+  }
+  if (capsDirty) {
+    mkdirSync(dirname(paths.config), { recursive: true });
+    atomicWrite(paths.config, `${JSON.stringify(caps, null, 2)}\n`);
+  }
+  if (machineDirty) {
+    mkdirSync(dirname(paths.machineConfig), { recursive: true });
+    atomicWrite(paths.machineConfig, `${JSON.stringify(machine, null, 2)}\n`);
+  }
+  return { ...caps, ...Object.fromEntries(LIST_KEYS.map((k) => [k, machine[k]]).filter(([, v]) => v)) };
 }