agenticow 0.1.0

package/bench/bench.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+// agenticow benchmark — reproduces the COW branch-CREATE advantage honestly.
+//
+// What this measures (and what it does NOT):
+//   - COW branch CREATE: time + on-disk delta size to derive() a branch off a
+//     base of N vectors. This is the headline, base-size-INDEPENDENT primitive.
+//   - Naive FULL COPY: time + bytes to byte-copy the whole base .rvf file (the
+//     baseline every other vector store forces you into for a snapshot).
+//   - Speed/size ratios at each base size.
+//
+// Honest caveats (printed in the footer):
+//   - This benchmarks branch CREATION, not query throughput.
+//   - Branch delta = O(edits), 162 B empty + ~520 B/edited-vector, independent
+//     of base size. Full copy = O(base file).
+//   - ANN query that spans the COW boundary is NOT benchmarked (roadmap). The
+//     shipped read-through is exact (parent ∪ edits) and lives in the lib layer.
+//
+// Usage:
+//   node bench/bench.js                 # 10k + 100k (fast, default)
+//   SIZES=10000,100000,1000000 node bench/bench.js   # include the 1M row (slow)
+//   DIM=128 node bench/bench.js
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import pkg from '@ruvector/rvf-node';
+
+const { RvfDatabase } = pkg;
+
+const DIM = Number(process.env.DIM || 128);
+const METRIC = 'cosine';
+const SIZES = (process.env.SIZES || '10000,100000')
+  .split(',')
+  .map((s) => parseInt(s.trim(), 10))
+  .filter(Boolean);
+const REPEAT = Number(process.env.REPEAT || 11); // odd -> clean median
+const EDIT_COUNTS = [0, 10, 100, 1000];
+
+const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agenticow-bench-'));
+
+function rndVec() {
+  const v = new Float32Array(DIM);
+  for (let i = 0; i < DIM; i++) v[i] = Math.random() * 2 - 1;
+  return v;
+}
+function median(xs) {
+  const s = [...xs].sort((a, b) => a - b);
+  return s[Math.floor(s.length / 2)];
+}
+function fmtBytes(b) {
+  if (b < 1024) return `${b} B`;
+  if (b < 1024 * 1024) return `${(b / 1024).toFixed(1)} KB`;
+  return `${(b / 1024 / 1024).toFixed(1)} MB`;
+}
+function fmtMs(ms) {
+  return ms < 1 ? `${(ms * 1000).toFixed(0)} µs` : `${ms.toFixed(2)} ms`;
+}
+
+function buildBase(n) {
+  const basePath = path.join(workDir, `base-${n}.rvf`);
+  fs.rmSync(basePath, { force: true });
+  const db = RvfDatabase.create(basePath, { dimension: DIM, metric: METRIC });
+  const BATCH = 10000;
+  let done = 0;
+  while (done < n) {
+    const m = Math.min(BATCH, n - done);
+    const flat = new Float32Array(m * DIM);
+    const ids = new Array(m);
+    for (let i = 0; i < m; i++) {
+      flat.set(rndVec(), i * DIM);
+      ids[i] = done + i;
+    }
+    db.ingestBatch(flat, ids);
+    done += m;
+  }
+  db.close();
+  return basePath;
+}
+
+// COW branch CREATE: median latency over REPEAT derives, plus delta size for
+// each edit count.
+function benchBranchCreate(basePath) {
+  const base = RvfDatabase.open(basePath);
+  const lat = [];
+  for (let r = 0; r < REPEAT; r++) {
+    const childPath = path.join(workDir, `br-${r}-${Math.random().toString(36).slice(2)}.rvf`);
+    const t0 = performance.now();
+    const child = base.derive(childPath, { dimension: DIM, metric: METRIC });
+    const t1 = performance.now();
+    lat.push(t1 - t0);
+    child.close();
+    fs.rmSync(childPath, { force: true });
+  }
+  // delta sizes by edit count (apply edits to a fresh branch each time)
+  const sizes = {};
+  for (const ec of EDIT_COUNTS) {
+    const childPath = path.join(workDir, `brsize-${ec}.rvf`);
+    fs.rmSync(childPath, { force: true });
+    const child = base.derive(childPath, { dimension: DIM, metric: METRIC });
+    if (ec > 0) {
+      const flat = new Float32Array(ec * DIM);
+      const ids = new Array(ec);
+      for (let i = 0; i < ec; i++) {
+        flat.set(rndVec(), i * DIM);
+        ids[i] = 1_000_000_000 + i; // new ids -> pure additions
+      }
+      child.ingestBatch(flat, ids);
+    }
+    child.close();
+    sizes[ec] = fs.statSync(childPath).size;
+    fs.rmSync(childPath, { force: true });
+  }
+  base.close();
+  return { latency: median(lat), sizes };
+}
+
+// Naive FULL COPY baseline: byte-copy the whole base file (what a snapshot costs
+// without COW). Median over REPEAT copies.
+function benchFullCopy(basePath) {
+  const baseSize = fs.statSync(basePath).size;
+  const lat = [];
+  for (let r = 0; r < REPEAT; r++) {
+    const dst = path.join(workDir, `copy-${r}.rvf`);
+    const t0 = performance.now();
+    fs.copyFileSync(basePath, dst);
+    const t1 = performance.now();
+    lat.push(t1 - t0);
+    fs.rmSync(dst, { force: true });
+  }
+  return { latency: median(lat), size: baseSize };
+}
+
+function main() {
+  console.log('agenticow — COW branch-create benchmark');
+  console.log('='.repeat(72));
+  console.log(`machine : ${os.cpus()[0].model.trim()} (${os.cpus().length} threads)`);
+  console.log(`node    : ${process.version}   platform: ${process.platform}-${process.arch}`);
+  console.log(`vectors : dim=${DIM}  metric=${METRIC}  median of ${REPEAT} runs`);
+  console.log('='.repeat(72));
+
+  const rows = [];
+  for (const n of SIZES) {
+    process.stdout.write(`\nbuilding base of ${n.toLocaleString()} vectors ... `);
+    const basePath = buildBase(n);
+    const baseSize = fs.statSync(basePath).size;
+    console.log(`${fmtBytes(baseSize)}`);
+    const branch = benchBranchCreate(basePath);
+    const copy = benchFullCopy(basePath);
+    const speedup = copy.latency / branch.latency;
+    const shrink = copy.size / branch.sizes[0];
+    rows.push({ n, baseSize, branch, copy, speedup, shrink });
+    fs.rmSync(basePath, { force: true });
+    console.log(
+      `  branch create : ${fmtMs(branch.latency)}  (empty delta ${fmtBytes(branch.sizes[0])})`
+    );
+    console.log(`  full copy     : ${fmtMs(copy.latency)}  (${fmtBytes(copy.size)})`);
+    console.log(
+      `  => ${speedup.toFixed(0)}x faster, ${Math.round(shrink).toLocaleString()}x smaller`
+    );
+  }
+
+  // Markdown table
+  console.log('\n\nResults table (Markdown)');
+  console.log('-'.repeat(72));
+  console.log(
+    '| Base N | Base file | Branch create (p50) | Empty branch | 100-edit branch | Full copy (p50) | Speedup | Shrink |'
+  );
+  console.log(
+    '|-------:|----------:|--------------------:|-------------:|----------------:|----------------:|--------:|-------:|'
+  );
+  for (const r of rows) {
+    console.log(
+      `| ${r.n.toLocaleString()} | ${fmtBytes(r.baseSize)} | ${fmtMs(r.branch.latency)} | ${fmtBytes(
+        r.branch.sizes[0]
+      )} | ${fmtBytes(r.branch.sizes[100])} | ${fmtMs(r.copy.latency)} | ${r.speedup.toFixed(
+        0
+      )}x | ${Math.round(r.shrink).toLocaleString()}x |`
+    );
+  }
+
+  // Delta-size-vs-edits (should be flat across base sizes)
+  console.log('\nBranch delta size by edit count (independent of base size):');
+  console.log('| Edits | ' + rows.map((r) => `${r.n.toLocaleString()}`).join(' | ') + ' |');
+  console.log('|------:|' + rows.map(() => '----------:').join('|') + '|');
+  for (const ec of EDIT_COUNTS) {
+    console.log(
+      `| ${ec} | ` + rows.map((r) => fmtBytes(r.branch.sizes[ec])).join(' | ') + ' |'
+    );
+  }
+
+  console.log('\nHonest notes:');
+  console.log('  - Measures branch CREATION (derive), not query throughput.');
+  console.log('  - Branch delta = O(edits), ~520 B/edited vector, flat in base size.');
+  console.log('  - Full copy = O(base file). The COW advantage widens with base size.');
+  console.log('  - Exact read-through (parent ∪ edits, child wins) is in the lib layer;');
+  console.log('    a single ANN index spanning the COW boundary is roadmap, not shipped.');
+
+  // JSON for the site/README
+  const out = path.join(process.cwd(), 'bench', 'results.json');
+  try {
+    fs.writeFileSync(
+      out,
+      JSON.stringify(
+        {
+          machine: os.cpus()[0].model.trim(),
+          threads: os.cpus().length,
+          node: process.version,
+          dim: DIM,
+          metric: METRIC,
+          repeat: REPEAT,
+          date: new Date().toISOString(),
+          rows: rows.map((r) => ({
+            n: r.n,
+            baseSize: r.baseSize,
+            branchCreateMs: r.branch.latency,
+            emptyBranchBytes: r.branch.sizes[0],
+            edit100Bytes: r.branch.sizes[100],
+            fullCopyMs: r.copy.latency,
+            fullCopyBytes: r.copy.size,
+            speedup: r.speedup,
+            shrink: r.shrink,
+            sizesByEdits: r.branch.sizes,
+          })),
+        },
+        null,
+        2
+      )
+    );
+    console.log(`\nwrote ${out}`);
+  } catch (e) {
+    console.log(`\n(could not write results.json: ${e.message})`);
+  }
+
+  fs.rmSync(workDir, { recursive: true, force: true });
+}
+
+main();

package/bin/agenticow.js

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+// agenticow CLI — Git for Agent Memory.
+//
+// Stateful verbs operate on a memory file (e.g. memory.rvf) plus a sibling
+// lineage manifest (memory.rvf.agenticow.json) that tracks the COW chain.
+//
+//   agenticow init   <file> --dim <n>           create a base memory
+//   agenticow ingest <file> --n <n>             ingest n random vectors (demo data)
+//   agenticow branch <file> --as <label>        COW-fork the memory (per-user/per-repo)
+//   agenticow checkpoint <file> --as <label>    freeze a restore point
+//   agenticow rollback  <file>                  discard edits since last checkpoint
+//   agenticow diff   <file>                     show added / overridden / tombstoned ids
+//   agenticow promote <branchFile> <intoFile>   merge a branch's edits into a base
+//   agenticow query  <file> --k <k>             top-K read-through (tombstone-masked, reranked)
+//   agenticow lineage <file>                    show the COW chain
+//
+//   agenticow demo          scripted end-to-end walkthrough
+//   agenticow bench         COW branch-create benchmark (SIZES env to add 1M)
+//   agenticow acceptance    1,000-branch acceptance proof (BASE/BRANCHES env)
+//   agenticow help          this help
+
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const LIB = path.join(ROOT, 'src', 'index.js');
+
+const C = { r: '\x1b[0m', b: '\x1b[1m', d: '\x1b[2m', c: '\x1b[36m', g: '\x1b[32m', y: '\x1b[33m', m: '\x1b[35m', red: '\x1b[31m' };
+const col = (k, s) => `${C[k]}${s}${C.r}`;
+
+function manifestFor(file) { return `${file}.agenticow.json`; }
+function rndVec(dim) { return Float32Array.from({ length: dim }, () => Math.random() * 2 - 1); }
+
+function parseArgs(argv) {
+  const pos = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) { flags[argv[i].slice(2)] = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true; }
+    else pos.push(argv[i]);
+  }
+  return { pos, flags };
+}
+
+function help() {
+  console.log(`
+${col('b', 'agenticow')} — ${col('c', 'Git for Agent Memory')}
+Copy-on-write vector branching: branch a base memory in ~0.5 ms / 162 bytes,
+regardless of base size. Exact read-through (parent ∪ edits, child wins).
+
+${col('b', 'Stateful verbs')} (operate on <file> + its lineage manifest)
+  init       <file> --dim <n>            create a base memory
+  ingest     <file> --n <n>              ingest n random demo vectors
+  branch     <file> --as <label>         COW-fork (per-user / per-repo personalization)
+  checkpoint <file> --as <label>         freeze a restore point
+  rollback   <file>                      discard edits since last checkpoint
+  diff       <file>                      added / overridden / tombstoned ids
+  promote    <branchFile> <intoFile>     merge a branch's edits into a base
+  query      <file> --k <k>              top-K read-through (tombstone-masked, reranked)
+  lineage    <file>                      show the COW chain
+
+${col('b', 'Showcases')}
+  demo                                   scripted end-to-end walkthrough
+  bench                                  branch-create benchmark
+  acceptance                             1,000-branch acceptance proof
+  help                                   this help
+
+${col('b', 'Example')}
+  agenticow init mem.rvf --dim 128
+  agenticow ingest mem.rvf --n 5000
+  agenticow branch mem.rvf --as user-42      ${col('d', '# cheap personalization')}
+  agenticow query  mem.rvf.user-42.rvf --k 10
+`);
+}
+
+function runChild(script, env) {
+  const res = spawnSync(process.execPath, [path.join(ROOT, 'bench', script)], { stdio: 'inherit', env: { ...process.env, ...env } });
+  process.exit(res.status || 0);
+}
+
+async function lib() { return import(LIB); }
+
+async function cmdInit(pos, flags) {
+  const { open } = await lib();
+  const file = pos[0];
+  const dim = Number(flags.dim || 128);
+  if (!file) throw new Error('usage: agenticow init <file> --dim <n>');
+  const mem = open(file, { dimension: dim, metric: flags.metric || 'cosine' });
+  mem.save(manifestFor(file));
+  mem.close();
+  console.log(`${col('g', '✓')} created base memory ${col('c', file)} (dim ${dim})`);
+}
+
+async function loadMem(file) {
+  const { AgenticMemory, open } = await lib();
+  const man = manifestFor(file);
+  if (fs.existsSync(man)) return { mem: AgenticMemory.load(man), man };
+  if (fs.existsSync(file)) { const mem = open(file); return { mem, man }; }
+  throw new Error(`no such memory: ${file} (run: agenticow init ${file} --dim <n>)`);
+}
+
+async function cmdIngest(pos, flags) {
+  const file = pos[0];
+  const n = Number(flags.n || 100);
+  const { mem, man } = await loadMem(file);
+  const dim = mem.dimension;
+  const flat = new Float32Array(n * dim);
+  const ids = [];
+  const base = Number(flags.startId || Math.floor(Math.random() * 1e6));
+  for (let i = 0; i < n; i++) { flat.set(rndVec(dim), i * dim); ids.push(base + i); }
+  const res = mem.ingest(flat, ids);
+  mem.save(man);
+  mem.close();
+  console.log(`${col('g', '✓')} ingested ${col('g', res.accepted)} vectors into ${col('c', file)} (ids ${base}..${base + n - 1})`);
+}
+
+async function cmdBranch(pos, flags) {
+  const file = pos[0];
+  const label = flags.as || 'branch';
+  const { mem, man } = await loadMem(file);
+  const childPath = flags.out || path.join(path.dirname(file), `${path.basename(file).replace(/\.rvf$/, '')}.${label}.rvf`);
+  const t0 = performance.now();
+  const br = mem.fork(label, childPath);
+  const ms = performance.now() - t0;
+  const bytes = fs.statSync(childPath).size;
+  br.save(manifestFor(childPath));
+  mem.save(man); // base unchanged by fork, but keep manifest fresh
+  br.close(); mem.close();
+  console.log(`${col('g', '✓')} branched ${col('c', file)} -> ${col('m', childPath)}`);
+  console.log(`  ${col('g', ms.toFixed(3) + ' ms')} / ${col('g', bytes + ' B')} (O(1) in base size)`);
+}
+
+async function cmdCheckpoint(pos, flags) {
+  const file = pos[0];
+  const { mem, man } = await loadMem(file);
+  const ck = mem.checkpoint(flags.as || undefined);
+  mem.save(man);
+  mem.close();
+  console.log(`${col('g', '✓')} checkpoint ${col('m', ck.label)} (id ${ck.id.slice(0, 12)}…, depth ${ck.depth}, 162 B)`);
+}
+
+async function cmdRollback(pos, flags) {
+  const file = pos[0];
+  const { mem, man } = await loadMem(file);
+  const t0 = performance.now();
+  const r = mem.rollback(flags.to || undefined);
+  const ms = performance.now() - t0;
+  mem.save(man);
+  mem.close();
+  console.log(`${col('g', '✓')} rolled back to ${col('m', r.restoredTo.slice(0, 12) + '…')} in ${col('g', ms.toFixed(3) + ' ms')} (depth ${r.depth})`);
+}
+
+async function cmdDiff(pos) {
+  const file = pos[0];
+  const { mem } = await loadMem(file);
+  const d = mem.diff();
+  mem.close();
+  console.log(`${col('b', 'diff')} ${col('c', file)} vs parent`);
+  console.log(`  ${col('g', '+ added     ')} ${d.added.length} ids ${d.added.length ? col('d', '[' + d.added.slice(0, 8).join(', ') + (d.added.length > 8 ? ', …' : '') + ']') : ''}`);
+  console.log(`  ${col('y', '~ overridden')} ${d.overridden.length} ids ${d.overridden.length ? col('d', '[' + d.overridden.slice(0, 8).join(', ') + (d.overridden.length > 8 ? ', …' : '') + ']') : ''}`);
+  console.log(`  ${col('red', '- deleted   ')} ${d.deleted.length} ids ${d.deleted.length ? col('d', '[' + d.deleted.slice(0, 8).join(', ') + (d.deleted.length > 8 ? ', …' : '') + ']') : ''}`);
+}
+
+async function cmdPromote(pos) {
+  const [branchFile, intoFile] = pos;
+  if (!branchFile || !intoFile) throw new Error('usage: agenticow promote <branchFile> <intoFile>');
+  const br = await loadMem(branchFile);
+  const target = await loadMem(intoFile);
+  const r = br.mem.promote(target.mem);
+  target.mem.save(target.man);
+  br.mem.close(); target.mem.close();
+  console.log(`${col('g', '✓')} promoted ${col('m', branchFile)} -> ${col('c', intoFile)}: ` +
+    `${col('g', r.ingested)} vectors merged, ${col('red', r.deleted)} tombstoned`);
+}
+
+async function cmdQuery(pos, flags) {
+  const file = pos[0];
+  const k = Number(flags.k || 10);
+  const { mem } = await loadMem(file);
+  // random probe (CLI is for demonstrating the read-through path)
+  const q = rndVec(mem.dimension);
+  const hits = mem.query(q, k);
+  mem.close();
+  console.log(`${col('b', `top-${k} read-through`)} for ${col('c', file)} (tombstone-masked, reranked)`);
+  for (const h of hits) {
+    console.log(`  id ${col('g', String(h.id).padStart(10))}  dist ${col('y', h.distance.toFixed(4))}  ${col('d', 'from ' + h.branch)}`);
+  }
+}
+
+async function cmdLineage(pos) {
+  const file = pos[0];
+  const { mem } = await loadMem(file);
+  const chain = mem.lineage();
+  mem.close();
+  console.log(`${col('b', 'lineage')} ${col('c', file)} (working → base)`);
+  chain.forEach((n, i) => {
+    const arm = i === chain.length - 1 ? '└─' : '├─';
+    console.log(`  ${arm} ${col('m', n.role.padEnd(10))} ${col('d', n.id.slice(0, 12) + '…')}  ${n.label || ''}  ${n.tombstones ? col('red', n.tombstones + ' tombstones') : ''}`);
+  });
+}
+
+async function demo() {
+  const { open } = await lib();
+  const DIM = 32;
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agenticow-demo-'));
+  const rnd = () => rndVec(DIM);
+  const line = () => console.log(col('d', '─'.repeat(64)));
+  console.log(`\n${col('b', 'agenticow demo')} — ${col('c', 'Git for Agent Memory')}\n`);
+
+  line(); console.log(col('b', '1. Build a shared base memory (5,000 vectors)'));
+  const base = open(path.join(dir, 'base.rvf'), { dimension: DIM });
+  const N = 5000; const vecs = new Float32Array(N * DIM); const ids = [];
+  for (let i = 0; i < N; i++) { vecs.set(rnd(), i * DIM); ids.push(i); }
+  base.ingest(vecs, ids);
+  console.log(`   base: ${col('g', base.status().totalVectors)} vectors, ${col('g', (base.status().fileSize / 1024 / 1024).toFixed(1) + ' MB')}`);
+
+  line(); console.log(col('b', '2. Per-user personalization — one branch per user (cheap)'));
+  const t0 = performance.now();
+  const users = ['alice', 'bob', 'carol'].map((u) => base.fork(u));
+  const ms = (performance.now() - t0) / users.length;
+  console.log(`   3 user branches in ${col('g', (performance.now() - t0).toFixed(2) + ' ms')} ` +
+    `(${col('g', ms.toFixed(3) + ' ms')}/user, ${col('g', '162 B')}/user)`);
+  console.log(`   ${col('d', 'personalization without the memory explosion of N full copies')}`);
+
+  line(); console.log(col('b', '3. Read-through — each user sees the shared base + own edits'));
+  const probe = vecs.slice(42 * DIM, 43 * DIM);
+  const h = users[0].query(probe, 1)[0];
+  console.log(`   alice queries base vector #42 -> id=${col('g', h.id)} dist=${col('g', h.distance.toFixed(4))} from ${col('m', h.branch)}`);
+  users[1].ingest([{ id: 900001, vector: rnd() }]);
+  const d = users[1].diff();
+  console.log(`   bob adds a private memory -> diff: ${col('g', '+' + d.added.length)} added, ${col('red', '-' + d.deleted.length)} deleted`);
+
+  line(); console.log(col('b', '4. Quarantine a bad ingest — checkpoint + instant rollback'));
+  const ck = users[2].checkpoint('clean');
+  console.log(`   checkpoint '${col('m', ck.label)}' (${col('g', '162 B')})`);
+  const poison = rnd();
+  for (let i = 0; i < 50; i++) users[2].ingest([{ id: 800000 + i, vector: rnd() }]);
+  users[2].ingest([{ id: 666666, vector: poison }]);
+  console.log(`   injected 51 hallucinated vectors -> present: ${col('y', users[2].query(poison, 1)[0].id === 666666)}`);
+  const tr = performance.now();
+  users[2].rollback(ck.id);
+  console.log(`   rollback in ${col('g', (performance.now() - tr).toFixed(2) + ' ms')} -> ` +
+    `poison present: ${col('g', users[2].query(poison, 5).map((x) => x.id).includes(666666))}`);
+
+  line(); console.log(col('b', '5. Git-style workflow — promote a reviewed branch to production'));
+  const prod = open(path.join(dir, 'prod.rvf'), { dimension: DIM });
+  prod.ingest([{ id: 1, vector: rnd() }]);
+  const feature = prod.fork('feature');
+  feature.ingest([{ id: 5001, vector: rnd() }, { id: 5002, vector: rnd() }]);
+  const r = feature.promote(prod);
+  console.log(`   reviewed branch promoted -> ${col('g', r.ingested)} vectors merged into production`);
+
+  line();
+  console.log(`\n${col('g', '✓')} branch / checkpoint / promote are O(1) in base size.`);
+  console.log(`${col('g', '✓')} read-through is exact: parent ∪ edits, child wins, tombstones masked.`);
+  console.log(`${col('d', 'Run')} ${col('c', 'agenticow acceptance')} ${col('d', 'for the 1,000-branch proof.')}\n`);
+
+  base.close(); prod.close(); feature.close(); users.forEach((u) => u.close());
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const cmd = (pos.shift() || 'help').toLowerCase();
+const run = async () => {
+  switch (cmd) {
+    case 'init': return cmdInit(pos, flags);
+    case 'ingest': return cmdIngest(pos, flags);
+    case 'branch': return cmdBranch(pos, flags);
+    case 'checkpoint': return cmdCheckpoint(pos, flags);
+    case 'rollback': return cmdRollback(pos, flags);
+    case 'diff': return cmdDiff(pos, flags);
+    case 'promote': return cmdPromote(pos, flags);
+    case 'query': return cmdQuery(pos, flags);
+    case 'lineage': return cmdLineage(pos, flags);
+    case 'demo': return demo();
+    case 'bench': return runChild('bench.js', {});
+    case 'acceptance': return runChild('acceptance.js', {});
+    default: return help();
+  }
+};
+run().catch((e) => { console.error(col('red', 'error: ') + e.message); process.exit(1); });

package/examples/parallel-agents.mjs

@@ -0,0 +1,64 @@
+// examples/parallel-agents.mjs
+// Worked example: fork N branches off one base, ingest + tombstone per branch,
+// query each branch (exact read-through), and roll one branch back.
+//
+//   node examples/parallel-agents.mjs
+//
+// This is the same shape as the acceptance test, at small scale, so you can read
+// it top to bottom.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { open } from 'agenticow'; // or '../src/index.js' from inside this repo
+
+const DIM = 64;
+const N_AGENTS = 8;
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agenticow-example-'));
+const rnd = () => Float32Array.from({ length: DIM }, () => Math.random() * 2 - 1);
+
+// 1. Build one shared base memory.
+const base = open(path.join(dir, 'base.rvf'), { dimension: DIM });
+const BASE_N = 2000;
+const flat = new Float32Array(BASE_N * DIM);
+const ids = [];
+for (let i = 0; i < BASE_N; i++) { flat.set(rnd(), i * DIM); ids.push(i); }
+base.ingest(flat, ids);
+console.log(`base: ${base.status().totalVectors} vectors, ${(base.status().fileSize / 1024).toFixed(0)} KB`);
+
+// 2. Fork N agent branches off the (now read-only) base. Each is ~162 B / ~0.5 ms.
+const agents = [];
+for (let a = 0; a < N_AGENTS; a++) {
+  const br = base.fork(`agent-${a}`);
+  // each agent ingests private memories + tombstones a couple of base vectors
+  br.ingest([
+    { id: 1_000_000 + a * 10 + 1, vector: rnd() },
+    { id: 1_000_000 + a * 10 + 2, vector: rnd() },
+  ]);
+  br.delete([a, a + 100]); // hide two base vectors from this agent's view
+  agents.push(br);
+}
+console.log(`forked ${agents.length} agent branches off the shared base`);
+
+// 3. Query each branch — exact read-through (base ∪ edits − tombstones).
+for (let a = 0; a < N_AGENTS; a++) {
+  const top = agents[a].query(rnd(), 5);
+  const fromBase = top.filter((h) => h.id < BASE_N).length;
+  const fromBranch = top.length - fromBase;
+  console.log(`agent-${a}: top-5 = ${fromBase} base + ${fromBranch} private  (e.g. id ${top[0].id} @ ${top[0].distance.toFixed(3)})`);
+}
+
+// 4. Roll one agent back to a clean checkpoint after a bad ingest.
+const victim = agents[0];
+const ck = victim.checkpoint('clean');
+const halluc = rnd();
+victim.ingest([{ id: 9_999_999, vector: halluc }]); // "hallucinated" memory
+console.log(`agent-0 before rollback: hallucination present = ${victim.query(halluc, 1)[0].id === 9_999_999}`);
+victim.rollback(ck.id);
+console.log(`agent-0 after rollback:  hallucination present = ${victim.query(halluc, 5).map((h) => h.id).includes(9_999_999)} (base intact)`);
+
+// cleanup
+base.close();
+agents.forEach((a) => a.close());
+fs.rmSync(dir, { recursive: true, force: true });
+console.log('done.');

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "agenticow",
+  "version": "0.1.0",
+  "description": "Git for Agent Memory: Copy-On-Write vector branching for embedded multi-agent memory. Branch a base memory in ~0.5ms / 162 bytes regardless of base size — 83x faster, 3000x smaller than full-copy snapshots. Exact read-through queries (parent ∪ edits, child wins).",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "bin": {
+    "agenticow": "bin/agenticow.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "bench/bench.js",
+    "bench/acceptance.js",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "bench": "node bench/bench.js",
+    "acceptance": "node bench/acceptance.js",
+    "demo": "node bin/agenticow.js demo",
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "agent-memory",
+    "vector-database",
+    "vector-database-branching",
+    "copy-on-write",
+    "cow",
+    "cow-vector-store",
+    "multi-agent-memory",
+    "embedded-vector-db",
+    "memory-checkpointing",
+    "vector-branching",
+    "git-for-vectors",
+    "rvf",
+    "ruvector",
+    "ai-agents",
+    "llm-memory",
+    "vector-snapshot",
+    "rollback",
+    "checkpoint"
+  ],
+  "author": "ruvnet",
+  "license": "MIT",
+  "homepage": "https://ruvnet.github.io/agenticow/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ruvnet/agenticow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ruvnet/agenticow/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@ruvector/rvf-node": "0.1.8"
+  }
+}