agenticow
Git for Agent Memory

What is copy-on-write for vectors?

Every other vector store makes you full-copy the index to snapshot or fork it. agenticow branches it.

Three things it makes cheap

All three are O(1) in base size today.

Deployment patterns — what the data says

Smarter orchestration, not smarter execution. Each pattern cites a head-to-head scaffolding ablation on cheap models (FRAMES, deepseek-v4-pro + glm-5.2, n=50, strict EM, reasoning OFF) — SCAFFOLDING-ABLATION.md.

Flagship production patterns — runnable + executed

Four end-to-end use cases, one paradigm: Branch → Mutate → external-Verify → Promote / Discard. Selection is always a deterministic external verifier (test / regex / checker / distance) — never a cheap LM-as-judge (the ablation showed that's a negative selector). These show the branching mechanics, not model intelligence. Numbers below are real measured output (AMD Ryzen 9 9950X, Node v22). Run all: npm run examples:production.

import { openBase } from 'agenticow';

const base = openBase('kb.rvf', { dimension: 1536 });
const sandbox = base.fork('untrusted-doc');           // Branch
sandbox.ingest(docEmbedding, { text: 'untrusted doc' }); // Mutate
const hits = sandbox.query(injectionSignature, { topK: 3 });
const exploit = hits.some(h => h.distance < 0.02);   // external-Verify (deterministic)
if (exploit) sandbox.rollback();  // Discard — base never poisoned (blast radius 0)
else         sandbox.promote();   // Promote — vetted delta merged into base

Benchmarks — branch create vs full copy

Reproduced on an AMD Ryzen 9 9950X (32 threads), Node v22, dim 128, cosine, median of 11 runs. Run it yourself: npx agenticow bench

Branch delta is a pure function of edit count (~520 B/edited vector) with zero dependence on base size. At small bases a raw copyFile is already sub-millisecond, so the COW win shows up — and widens — at scale.

Multi-approach comparison — performance · storage · cost

Scenario: 1,000 branches over a 1M-vector base (dim 128, ~496 MB base). green = measured on agenticow (AMD Ryzen 9 9950X); other approaches are amber = published / estimated with sources cited — not fabricated.

Takeaway: agenticow wins decisively on branch-create speed, per-branch storage, and multi-branch cost — and is the only option with native COW branching + instant rollback of a live vector memory. It concedes raw ANN search speed to the dedicated vector DBs (Pinecone / Qdrant / Milvus); use those when single-index query throughput is the priority, and agenticow when you need cheap branching, checkpointing, and rollback of agent memory.

* SIFT-1M same-machine (matched recall@10 ≈ 0.97): ruvector HNSW is ~6.3× behind a dedicated flat-index engine like hnswlib-node at 1M-vector scale (~2.7× on small in-cache sets; the earlier ~2.7× was a 100K-vector synthetic set that fit in L3 cache). Deliberate trade — agenticow competes on memory versioning/isolation/rollback, not raw search speed; narrowing levers (graph-quality shrink-heuristic + stack-local heaps) are on the ruvector-engine roadmap. † agenticow base (~496 MB) + 1,000 × ~10.8 KB ≈ 507 MB; runs in-process, no managed infra. ¹ Pinecone serverless storage est. from pinecone.io/pricing (~$0.33/GB-month) — storage only, excludes read/write units. ² Milvus / Zilliz Cloud est. from zilliz.com/pricing (RAM-resident, cluster-sized). ³ Qdrant est. from qdrant.tech/pricing. All competitor figures are published/estimated and labeled as such; only agenticow's are measured here.

How it compares

agenticow is the only one with native copy-on-write branching of the vector index. We concede raw ANN throughput honestly — pick the right tool for the job.

*On a measured SIFT-1M benchmark (same machine, matched recall@10 ≈ 0.97), the underlying ruvector HNSW is ~6.3× behind a dedicated flat-index engine like hnswlib at 1M-vector scale (~2.7× on small in-cache sets — the earlier figure was a 100K-vector synthetic set that fit in L3 cache; the gap widens at 1M). This is a deliberate trade: agenticow does not compete on raw single-index search throughput — its unique capability is memory versioning, isolation, and lifecycle governance for multi-tenant agent fleets (1,000 parallel isolated reversible branches at ~0.5 ms/fork, which no flat ANN engine offers). Future levers to narrow the gap (graph-quality shrink-heuristic + stack-local heaps) are on the ruvector-engine roadmap, not agenticow's pitch. If you need maximum raw ANN speed on a static index, use a dedicated ANN library. Native ANN-across-branch (fork({nativeAnn:true})) ships for linux-x64-gnu today; other platforms degrade gracefully to exact read-through.

Usage

One small API. ESM, Node ≥ 18.

import { open } from 'agenticow';

// open or create a base memory
const base = open('memory.rvf', { dimension: 1536 });
base.ingest([{ id: 1, vector: embedding }, /* ... */]);

// branch it for a parallel agent — ~0.5 ms / 162 B, any base size
const agent = base.branch('agent-a');
agent.ingest([{ id: 9001, vector: newMemory }]); // isolated

// exact read-through: sees the base + its own edits, child wins on collision
const hits = agent.query(queryVector, 10);

// NEW 0.2.0 — native ANN ACROSS the branch (single Rust dual-graph query)
const fast = base.fork('agent-b', null, { nativeAnn: true });
fast.query(queryVector, 10); // parent ∪ edits via native HNSW, recall@10 ≈ 1.0

// checkpoint + rollback a poisoned branch
const ckpt = agent.checkpoint('clean');
agent.ingest([{ id: 666, vector: poison }]);
agent.rollback(ckpt.id);  // poison gone, clean memory intact

Runnable examples

One per use case, in examples/ — node examples/X.mjs or npm run examples. Deterministic output (seeded RNG).

Claim ladder — runnable, executed, benchmarked

Every tier is backed by code you can run. PROVEN = bench + acceptance · DEMONSTRATED = executed + benchmarked · PoC = mechanics shown, cognition out of scope.

Run: npm run examples · npm run examples:platform · npm run examples:exotic · npm run bench:ladder. Numbers measured on AMD Ryzen 9 9950X, base=5,000, dim=64.