{"id":51280141,"url":"https://github.com/ruvnet/agenticow","last_synced_at":"2026-07-01T02:01:00.136Z","repository":{"id":368030610,"uuid":"1283237512","full_name":"ruvnet/agenticow","owner":"ruvnet","description":"Git for Agent Memory: Copy-On-Write vector branching for embedded multi-agent memory (83x faster, 3000x smaller snapshots)","archived":false,"fork":false,"pushed_at":"2026-06-28T21:20:19.000Z","size":5016,"stargazers_count":27,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T01:22:01.908Z","etag":null,"topics":["agent-memory","ai-agents","checkpoint","copy-on-write","embedded-database","llm","memory","multi-agent","vector-database","vector-search"],"latest_commit_sha":null,"homepage":"https://ruvnet.github.io/agenticow/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ruvnet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-28T17:42:58.000Z","updated_at":"2026-06-30T01:13:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ruvnet/agenticow","commit_stats":null,"previous_names":["ruvnet/agenticow"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ruvnet/agenticow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Fagenticow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Fagenticow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Fagenticow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Fagenticow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruvnet","download_url":"https://codeload.github.com/ruvnet/agenticow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Fagenticow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34989787,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-agents","checkpoint","copy-on-write","embedded-database","llm","memory","multi-agent","vector-database","vector-search"],"created_at":"2026-06-30T01:02:48.322Z","updated_at":"2026-07-01T02:01:00.060Z","avatar_url":"https://github.com/ruvnet.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# agenticow — Git for Agent Memory: Copy-On-Write vector branching (83× faster, 3000× smaller snapshots)\n\n**Branch a base vector memory in ~0.5 ms / 162 bytes — independent of base size.** Exact read-through queries (parent ∪ edits, child wins). Built for embedded multi-agent memory.\n\n[![npm](https://img.shields.io/npm/v/agenticow?color=3fe0c5)](https://www.npmjs.com/package/agenticow)\n[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)\n[![tests](https://img.shields.io/badge/tests-8%2F8%20passing-3fe07a)](./test)\n[![acceptance](https://img.shields.io/badge/acceptance-1000%20branches%20PASS-3fe07a)](#acceptance-the-1000-branch-proof)\n\n**[Website / Demo →](https://ruvnet.github.io/agenticow/)** · **[npm](https://www.npmjs.com/package/agenticow)** · **[Benchmarks](#benchmarks)** · **[Acceptance proof](#acceptance-the-1000-branch-proof)**\n\n![agenticow — Git for Agent Memory](./assets/hero.png)\n\n\u003c/div\u003e\n\n\u003e **agenticow turns memory from a static database into a branchable runtime primitive for agents.**\n\nEvery other vector store makes you **full-copy** the index to snapshot, fork, or checkpoint it. `agenticow` **branches** it — copy-on-write, like Git. Creating a branch costs ~0.5 ms and 162 bytes whether the base holds 10,000 or 1,000,000 vectors. Query a branch and you transparently see `parent ∪ your edits`, with the child winning on id collisions and deletes honored.\n\n```bash\nnpm install agenticow\n```\n\n---\n\n## Why\n\nAgents need memory that branches: a per-user personalization layer, a sandbox to test a risky ingest, a checkpoint before a tool call, a thousand parallel experiments off one shared base. With a normal vector DB each of those is a **full copy** of the whole index. At 1M vectors that is **496 MB and 67 ms** — every time. agenticow makes it **162 bytes and 0.47 ms**, flat.\n\n### Three things it makes cheap\n\n| Use case | What it replaces | Cost with agenticow |\n|---|---|---|\n| 👥 **Parallel agents share one base memory** | N full copies of the index | N × 162 B, N × 0.5 ms |\n| 🧪 **Roll back a poisoned / hallucinated branch** | re-ingest + re-index from backup | drop the branch, ~0.5 ms |\n| 📌 **Zero-cost checkpointing before risky steps** | periodic full snapshots | 162 B + edits-since per checkpoint |\n\n---\n\n## Quick start\n\n```js\nimport { open } from 'agenticow';\n\n// open or create a base memory\nconst base = open('memory.rvf', { dimension: 1536 });\nbase.ingest([{ id: 1, vector: embedding }, /* ... */]);\n\n// branch it for a parallel agent — ~0.5 ms / 162 B, any base size\nconst agent = base.branch('agent-a');\nagent.ingest([{ id: 9001, vector: newMemory }]);     // isolated from the base\n\n// exact read-through: sees base + its own edits, child wins on id collision\nconst hits = agent.query(queryVector, 10);\n// -\u003e [{ id, distance, branch }, ...]  (tombstone-masked, reranked)\n\n// NEW in 0.2.0 — native ANN ACROSS the branch (single Rust dual-graph query):\nconst fast = base.fork('agent-b', null, { nativeAnn: true });\nfast.ingest([{ id: 9002, vector: newMemory }]);\nfast.query(queryVector, 10);    // parent ∪ edits via native HNSW, recall@10 ≈ 1.0\nfast.nativeAnn;                  // true on linux-x64; false (exact fallback) elsewhere\n\n// checkpoint + roll back a poisoned branch\nconst ckpt = agent.checkpoint('clean');\nagent.ingest([{ id: 666, vector: poison }]);\nagent.rollback(ckpt.id);                              // poison gone, clean memory intact\n```\n\n### CLI\n\n```bash\nagenticow init   mem.rvf --dim 128\nagenticow ingest mem.rvf --n 5000\nagenticow branch mem.rvf --as user-42        # cheap per-user personalization\nagenticow query  mem.rvf.user-42.rvf --k 10  # top-K read-through (masked, reranked)\nagenticow diff   mem.rvf.user-42.rvf         # added / overridden / tombstoned ids\nagenticow demo                               # scripted end-to-end walkthrough\nagenticow bench                              # branch-create benchmark\nagenticow acceptance                         # the 1,000-branch proof\n```\n\n| Verb | Use case |\n|---|---|\n| `branch` | per-user / per-repo / per-account personalization off one shared base — *personalization without memory explosion* |\n| `checkpoint` / `rollback` | per-task checkpointing; quarantine a bad/hallucinated ingest and instantly revert |\n| `diff` / `promote` | Git-style memory workflow: agent branch → test → reviewed → production |\n| `query` | top-K read-through with tombstone masking + exact rerank |\n| `fork` (API) | fan out many branches off a static base (1,000 per-user branches in one process) |\n\nA worked script lives in [`examples/parallel-agents.mjs`](./examples/parallel-agents.mjs): fork N branches from a base, ingest + tombstone per branch, query each, roll one back.\n\n---\n\n## Applications\n\nConcrete ways to use COW agent memory — each with a runnable script in\n[`examples/`](./examples). Framing is honest: **practical** = PROVEN (bench +\nacceptance), **platform** = DEMONSTRATED + benchmarked, **exotic** = PoC mechanics\n(cognition out of scope). See the [claim ladder](#claim-ladder).\n\n### 🏭 Flagship production patterns *(runnable + executed)*\n\nFour end-to-end production use cases, all following one paradigm —\n**Branch → Mutate → external-Verify → Promote / Discard**. Selection is **always**\na deterministic **external** verifier (test / regex / checker / distance\nfunction), **never a cheap LM-as-judge** — the scaffolding ablation showed a\nverifier-gated cheap-LM judge picks *worse* than a plain vote (a negative\ngeneration–verification gap), so the gate must be something that can't\nhallucinate. These demonstrate the branching **mechanics** (production-ready\npatterns), not model intelligence. Run all four: `npm run examples:production`.\n\n**Implement right now** (this snippet runs verbatim against the published API —\n`openBase`, `ingest(vec,{text})`, `query(vec,{topK})`, `promote()`, `rollback()`):\n\n```js\nimport { openBase } from 'agenticow';\n\nconst base = openBase('kb.rvf', { dimension: 1536 });\n\n// Branch → Mutate: an untrusted batch lands in an isolated fork, never the base.\nconst sandbox = base.fork('untrusted-doc');\nsandbox.ingest(docEmbedding, { text: 'untrusted document' });\n\n// external-Verify: a deterministic checker (NOT an LM-judge) gates the branch.\nconst hits = sandbox.query(injectionSignature, { topK: 3 });\nconst exploit = hits.some((h) =\u003e h.distance \u003c 0.02);   // distance threshold = the oracle\n\n// Promote / Discard:\nif (exploit) sandbox.rollback();   // discard — base never saw it (blast radius 0)\nelse         sandbox.promote();    // merge the vetted delta into the base\n```\n\n| Use case | External verifier (deterministic) | Measured result |\n|---|---|---|\n| 🛡️ [`red-team-sandbox.mjs`](./examples/red-team-sandbox.mjs) — untrusted-doc ingestion | injection-signature distance probe | exploit→`rollback()` **1.1 ms**, **0** vectors reached base; clean→`promote()` |\n| 🗳️ [`multi-persona-consensus.mjs`](./examples/multi-persona-consensus.mjs) — 5 personas, 1 winner | policy-constraint gate **+** distance-to-rubric score | **4/5** qualified, winner promoted, losers discarded free |\n| ⏪ [`time-travel-debug.mjs`](./examples/time-travel-debug.mjs) — rewind past a latent bug | compiler-style bad-signature scan | rewind to step-10 ckpt **1.1 ms**, **0** steps replayed, 24/24 reachable |\n| 🏢 [`multi-tenant-saas.mjs`](./examples/multi-tenant-saas.mjs) — 1,000 tenant branches | cross-tenant isolation oracle (200 probes) | **0/200** leaks, **2.4 KB**/tenant, **530×** less disk than full copies |\n\n→ outputs + details in [`examples/README.md`](./examples/README.md#-flagship-production-patterns).\n\n### 🟢 Personalization — one base, a branch per user *(practical)*\nGive every user/account/tenant their own memory branch off a shared base. Private\nedits stay isolated; storage is delta-only (KB/user, not a full copy).\n```js\nconst base = open('kb.rvf', { dimension: 1536 });\nconst userMem = base.fork(`user-${userId}`);\nuserMem.ingest([{ id, vector }]);          // private to this user\nuserMem.query(q, 10);                       // reads through to the shared base\n```\n→ [`examples/personalization.mjs`](./examples/personalization.mjs) · [`parallel-agents.mjs`](./examples/parallel-agents.mjs)\n\n### 🟢 Rollback / quarantine — discard a poisoned branch *(practical)*\nAn agent ingests hallucinated or adversarial memories into a sandbox branch.\nDetect it, drop the branch — the base is instantly clean, no re-index.\n```js\nconst sandbox = base.fork('untrusted');\nsandbox.ingest(unvettedVectors);\n// ...detect bad content...\nsandbox.close();                            // discard → base never saw it\n```\n→ [`examples/rollback-quarantine.mjs`](./examples/rollback-quarantine.mjs)\n\n### 🟢 Checkpointing — crash recovery without replay *(practical)*\nCheckpoint memory before each risky step (162 B each). On failure, roll back to\nthe last good checkpoint in ~0.5 ms — earlier steps are not replayed.\n```js\nconst ck = mem.checkpoint('step-30');\n// ...step 31 crashes...\nmem.rollback(ck.id);                         // resume from step 30\n```\n→ [`examples/checkpointing.mjs`](./examples/checkpointing.mjs)\n\n### 🟢 Git-style memory workflow — branch → diff → promote *(practical)*\nTreat memory like code: branch a feature, review the change with `diff()`, and\n`promote()` the vetted delta into production.\n```js\nconst feature = prod.branch('feature');\nfeature.ingest(newFacts);\nfeature.diff();                              // { added, overridden, deleted }\nfeature.promote(prod);                       // merge into production\n```\n→ [`examples/git-workflow.mjs`](./examples/git-workflow.mjs)\n\n### 🟢 Promotion pipeline — agent → sandbox → review → prod *(platform — DEMONSTRATED)*\nA \"memory DevOps\" pipeline: an agent proposes memories in a sandbox branch, a\nreview gate scores them, and only a passing branch is promoted. A rejected branch\nis discarded and never reaches base — with a lineage audit (parent/label/timestamp)\nat each step.\n→ [`examples/promotion-pipeline.mjs`](./examples/promotion-pipeline.mjs)\n\n### 🟢 A/B testing at scale — score variants, promote the winner *(platform — DEMONSTRATED)*\nFork N variant branches off one base, score each, and promote only the winner.\nBenchmarked at 128 variants (fork 1.3 ms/variant, score 0.15 ms/variant, 0.84 KB/variant).\n```js\nconst variants = ids.map((i) =\u003e base.fork(`variant-${i}`));\n// ...score each...\nvariants[best].promote(base);               // keep the winner, drop the rest free\n```\n→ [`examples/ab-branches.mjs`](./examples/ab-branches.mjs) · [`ab-at-scale.mjs`](./examples/ab-at-scale.mjs)\n\n### 🟢 Compliance, lineage \u0026 right-to-erasure *(platform — DEMONSTRATED)*\n`lineage()` gives an auditable parent/label/timestamp trail for every mutation\n(\"why does the agent know X?\"). Per-user data lives in its own branch layer, so\ndropping that layer surgically erases exactly that user's data (GDPR-style).\n→ [`examples/compliance-lineage.mjs`](./examples/compliance-lineage.mjs)\n\n### 🟡 Edge / local-first agents — embedded, no server *(strategic)*\nagenticow runs in-process over a single `.rvf` file — no DB server, no network.\nThousands of cheap branches fit on-device for offline/edge multi-agent memory.\n\n### ⚗️ Cognitive ensembles, evolution \u0026 simulated orgs *(exotic — PoC mechanics)*\nPoCs that demonstrate the branching **mechanics** of advanced patterns — NOT that\nthe branches are intelligent (the judge/fitness is a scoring function, cognition\nis out of scope):\n- **Parallel selves** — an ensemble of personas off one base, a judge picks + promotes the winner → [`examples/parallel-selves.mjs`](./examples/parallel-selves.mjs)\n- **Darwin-on-memory** — a population evolves over generations; storage stays delta-sized → [`examples/memory-evolution.mjs`](./examples/memory-evolution.mjs)\n- **Simulated org** — departmental branches with cross-branch contradiction detection before rollout → [`examples/simulated-org.mjs`](./examples/simulated-org.mjs)\n\n### 🔭 Agent marketplaces \u0026 shared base memories *(exotic — vision, not shipped)*\nA published base memory that many agents branch from, contributing deltas back —\na \"memory package registry\". The branch/promote primitives exist today; the\ndistribution, trust, and merge-policy layer is **roadmap, not shipped**.\n\n---\n\n## MetaHarness usage\n\nagenticow is the **memory plane** of the [`@metaharness/*`](https://www.npmjs.com/org/metaharness)\nagent-harness ecosystem. It pairs with [`@metaharness/jujutsu`](https://www.npmjs.com/package/@metaharness/jujutsu)\n(`v0.1.0`), which wraps [`agentic-jujutsu`](https://www.npmjs.com/package/agentic-jujutsu)\n(a Rust+NAPI Jujutsu `jj` op-log with QuantumDAG coordination, ReasoningBank\ntrajectories, and ML-DSA signing) — the **code/op plane**.\n\n**The dual-state bridge (ADR-202).** A coding agent that explores must branch and\nroll back *two* planes: the **code/ops** it did and the **memory** it learned.\nUsed separately they drift (revert code but keep poisoned memory; promote a\nmemory delta whose ops were never merged). `@metaharness/jujutsu`'s\n`DualStateBridge` ties them 1:1 — one agent ⇒ one op branch + one memory branch —\nmapping four lifecycle verbs onto agenticow:\n\n| Verb | code/op plane (agentic-jujutsu) | memory plane (agenticow) |\n|---|---|---|\n| **spawn** | `jj bookmark create` + start trajectory | `fork()` off the base + `checkpoint('spawn')` |\n| **learn** | finalize trajectory + read op-sequence | embed ops → `ingest()` into the branch |\n| **revert** | `jj undo` | `rollback()` to the spawn checkpoint |\n| **merge** | `jj squash` ops into base | `promote()` the winning delta into the base |\n\nInstall alongside (both planes are **optional peer deps** — the bridge runs\ndegraded/mock-backed if one is absent, per the ADR-150 *removable-augmentation*\nprinciple):\n\n```bash\nnpm install @metaharness/jujutsu agenticow agentic-jujutsu\n```\n\n```js\nimport { open } from 'agenticow';\n// @metaharness/jujutsu wires these two planes behind DualStateBridge:\nconst base = open('reasoning-bank.rvf', { dimension: 1536 });\nconst agentMem = base.fork('agent-007');     // memory branch (spawn)\nagentMem.checkpoint('spawn');\nagentMem.ingest(embeddedTrajectory);          // learn\n// if the trajectory scores poorly:\nagentMem.rollback(/* spawn checkpoint id */); // revert — code revert via `jj undo`\n// if it wins:\nagentMem.promote(base);                        // merge — ops via `jj squash`\n```\n\n**Honest status (ADR-202):** spawn / learn / revert / merge are **wired\nend-to-end** with both real native planes. **Cross-branch ANN query is now\nshipped** — agenticow `0.2.x` adds native dual-graph ANN across the COW boundary\n(`fork({ nativeAnn: true })`, [RuVector PR #617/#618](https://github.com/ruvnet/RuVector/pull/617),\nrecall@10 ≈ 1.0 on linux-x64; exact read-through fallback elsewhere). The bridge\nadapter can swap from the exact-read-through port to the native ANN port with no\ninterface change.\n\n---\n\n## Deployment patterns (what the data says)\n\n**Thesis: smarter *orchestration*, not smarter *execution*.** When you run cheap\nmodels at scale, the lever is *how you spawn, branch, select, and roll back* — not\nsqueezing more \"intelligence\" out of any single run. This isn't a slogan: it's what\na head-to-head scaffolding ablation on FRAMES (cheap models `deepseek-v4-pro` +\n`glm-5.2`, n=50, strict EM, Wilson CIs, reasoning OFF) actually measured. Every\npattern below cites that finding. Full study + reproduce script:\n[`SCAFFOLDING-ABLATION.md`](https://github.com/ruvnet/agent-harness-generator/blob/main/docs/research/scaffolding/SCAFFOLDING-ABLATION.md).\n\n### 1. Fail-fast, shallow branches — not deep self-refine loops\n\nThe ablation showed that *adding reasoning machinery to a cheap model backfires*:\n**Plan-and-Solve −10pp** (deepseek 0.50→0.40) / **−6pp** (glm 0.42→0.36),\n**Reflexion −8pp at 2.85× cost** (8.2→21.4 steps, \"cost without lift\"), and the\n**PS+BoN compound stacks the damage** (deepseek vote 0.48 \u003c plain-BoN 0.56). The\nbase ReAct loop already **saturates around 8–12 steps** — a turn-budget cliff where\nmore steps stop discovering and just give error-compounding more surface area.\n\n**So:** run **2–3-turn tasks**. On failure, don't force the cheap model to\nself-correct — **drop the branch (~0.5 ms rollback) and respawn** with a shifted\nprompt / clean state. agenticow makes failure *free*, so \"throw it away and try a\nfresh independent attempt\" beats \"make it reflect on its mistake.\"\n\n### 2. Scale horizontally — massively parallel personalization\n\nCheap models are at their best on the **first shot**; the ablation found no\nreasoning scaffold buys a cost-justified lift, and the *only* directional gain\n(Self-Consistency, +4–6pp) **saturates by N≈7** and costs ~10× — i.e. the win is in\n*more independent attempts*, not deeper ones. The product win is therefore\n**multi-tenant scale**: agenticow runs **1,000 isolated branches at 943× less disk**\nthan 1,000 full copies (10.5 MB vs 9.69 GB; see [acceptance](#acceptance-the-1000-branch-proof)).\n**Many shallow agents off one base, not one deep agent.**\n\n### 3. Selection must be EXTERNAL + deterministic — never the cheap LM as judge\n\nThe ablation's cleanest negative result: a **verifier-gated LM-judge picks *worse*\nthan a plain majority vote off the same samples** (deepseek **−4pp**, glm **−6pp**) —\na *negative* generation-verification gap. A cheap model judging its own outputs,\nwith no oracle, is a worse selector than counting votes.\n\n**So for promotion / merge (`diff` → `promote`), score branches with an EXTERNAL,\ndeterministic signal:** unit tests, compilers, regex / schema validators, a\nhuman-gate — **not** the cheap model. The branch primitive gives you the isolation;\nthe *gate* must be something that can't hallucinate.\n\n**The nuance — an execution oracle flips this.** That backfire was on FRAMES, which\nhas *no* ground-truth verifier. On **code**, tests are a **zero-cost, near-perfect\nverifier** — so promotion-by-test-verification *is* strong there (the ablation\nexplicitly flags SWE-bench-style execution as the case where the verifier gap goes\npositive). This is exactly the bridge to\n[`@metaharness/jujutsu`](#metaharness-usage): **code branches gated by tests**, where\nthe gate is an execution oracle, not a model.\n\n### 4. Positioning — Infrastructure/DevOps layer, not a cognitive enhancer\n\nagenticow is **Git for agent memory**, not a way to make agents *smarter*. Git\ndoesn't make developers write better code — it lets thousands of them work\nconcurrently, isolate mistakes, roll back, and merge through CI. agenticow is the\nsame shape for cheap-model fleets: it makes running them at scale **governed,\nisolated, auditable, and ~computationally free** (162 B / 0.5 ms branch; instant\nrollback; lineage for right-to-erasure). It does **not** make the models smarter —\nand the data says nothing at the orchestration layer reliably does: RAG was null and\n*every* reasoning scaffold backfired or failed to pay for itself on cheap models.\n**The honest claim is leverage, not intelligence:** infrastructure that turns \"run\n1,000 cheap agents safely\" into a tractable, near-free operation.\n\n---\n\n## How copy-on-write for vectors works\n\n![COW concept](./assets/concept.png)\n\nA branch records **only its own edits** plus a pointer to its parent. Creating one is constant-time and constant-size — **162 bytes** — independent of base size. A query walks the lineage chain (`child → … → base`), merges each store's results, lets the **child win** on any id collision, masks anything the branch **tombstoned**, and re-ranks by exact distance.\n\n---\n\n## Benchmarks\n\nReproduced on an **AMD Ryzen 9 9950X** (32 threads), Node v22, dim 128, cosine, median of 11 runs. Run it yourself: `npx agenticow bench`.\n\n![Benchmarks: branch create vs full copy](./assets/benchmarks.png)\n\n| Base N | Base file | Branch create (p50) | Empty branch | 100-edit branch | Full copy (p50) | Speedup | Smaller |\n|-------:|----------:|--------------------:|-------------:|----------------:|----------------:|--------:|--------:|\n| 10,000 | 5.0 MB | 519 µs | **162 B** | 51.4 KB | 373 µs | 1× | 32,102× |\n| 100,000 | 49.6 MB | 463 µs | **162 B** | 51.4 KB | 5.83 ms | 13× | 321,037× |\n| 1,000,000 | 496.3 MB | **472 µs** | **162 B** | 51.4 KB | 67.14 ms | **142×** | **3,212,443×** |\n\nBranch delta is a pure function of edit count (~520 B / edited vector) with **zero dependence on base size**. At a 10k base a raw `copyFile` is already sub-millisecond, so the COW win shows up — and widens — at scale. The original [RVF COW proof](https://github.com/ruvnet/RuVector) reports the conservative **83× / 3000×** figures (0.78 ms vs 64.7 ms; 162 B vs 496 MB); the reproduction above is consistent and, on this machine, better on speed.\n\n---\n\n## Acceptance: the 1,000-branch proof\n\n`npm run acceptance` (or `agenticow acceptance`) runs the full spec and reports real numbers. Latest run, **AMD Ryzen 9 9950X**, base = 20,000 vectors, dim 128:\n\n| Measurement | Result |\n|---|---|\n| **Branches forked** | **1,000** off one base (median **0.487 ms/fork**, 4.5 s total) |\n| **Top-10 correctness** | **recall@10 = 100%**, exact-order match 100% (120 sampled queries vs brute-force ground truth) |\n| **Tombstone masking** | **PASS** — 0 tombstoned ids leaked into results |\n| **Rollback latency** | **p50 = 0.571 ms** (min 0.48 / max 1.01), ~constant |\n| **Storage vs delta** | 1,000 branches = **10.5 MB total** (10.8 KB/branch) vs **9.69 GB** for 1,000 full copies → **943× less disk**; total branch storage is **1.06× the base** (grows with delta, not base) |\n| **Verdict** | **PASS ✓** |\n\nThe acceptance test builds a brute-force ground truth (`base ∪ branch-inserts − tombstones`, reranked by cosine distance) and asserts the read-through top-K matches it. If a 1,000-branch fork ever hits a real fd/memory/time limit, the test reports the max that worked plus the scaling curve — the 1,000 is not faked. Results are written to [`bench/acceptance-results.json`](./bench/acceptance-results.json).\n\n---\n\n## How it compares\n\n![Comparison vs Pinecone / Milvus / pgvector / Chroma / Qdrant](./assets/comparison.png)\n\n| Capability | agenticow | Pinecone | Milvus | pgvector | Chroma | Qdrant |\n|---|:---:|:---:|:---:|:---:|:---:|:---:|\n| Native COW branch of the index | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| O(1)-in-base branch create | ✅ 162 B | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Snapshot mechanism | COW delta | full copy | full copy | SQL dump | full copy | full copy |\n| Exact read-through (parent ∪ edits) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Embedded / in-process (no server) | ✅ | ❌ | ❌ | via PG | ✅ | ✅/server |\n| Raw ANN throughput | ⚠️ ~6.3× behind hnswlib @ 1M\\* | high | high | moderate | moderate | high |\n| ANN search spanning the branch | ✅ shipped (recall@10 ≈ 1.0, linux-x64\\*\\*) | n/a | n/a | n/a | n/a | n/a |\n\n\\* **Honest concession (deliberate trade).** On a measured SIFT-1M benchmark (same machine, matched recall@10 ≈ 0.97), the underlying [ruvector](https://github.com/ruvnet/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 ~2.7× figure was a 100K-vector synthetic set that fit in L3 cache; the gap widens at 1M-vector scale. This is by design: agenticow deliberately 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). The bigger the raw-speed gap, the clearer the \"different tool for a different job\" message. Future levers to narrow it (graph-quality shrink-heuristic + stack-local heaps) are on the **ruvector-engine roadmap**, not agenticow's pitch. If you need maximum raw similarity-search speed on a static index, use a dedicated ANN library.\n\n\\*\\* Native ANN-across-branch (`fork({ nativeAnn: true })`) ships for **linux-x64-gnu** today; other platforms degrade gracefully to exact read-through. The raw-ANN-speed concession above still applies to the underlying engine.\n\n### Performance · storage · cost at scale\n\n**Scenario: 1,000 branches over a 1M-vector base** (dim 128, ~496 MB base). agenticow figures are **measured** on an AMD Ryzen 9 9950X; competitor figures are **published / estimated** (sources below) and labeled as such — not fabricated.\n\n| Approach | Branch / snapshot create | Per-branch storage | Query latency (ANN) | Cost @ 1,000 branches | Native COW / rollback |\n|---|---|---|---|---|---|\n| **agenticow (COW)** | 0.47 ms / 162 B *(measured, flat to 1M)* | ~10.8 KB *(measured)* | ~6.3× behind hnswlib @ 1M *(measured\\*)* | ~507 MB local · **~$0** infra (embedded) *(measured†)* | ✅ instant (p50 0.57 ms) |\n| Naive full-copy | 67 ms / 496 MB *(measured @1M)* | full base (~496 MB) | = source engine | ~484 GB local *(measured ×N)* | ❌ |\n| Pinecone (serverless) | no native branch — full re-upsert | full copy (managed) | fast (core strength) | ~484 GB ≈ **$160/mo** storage + units *(est.¹)* | ❌ |\n| Milvus | snapshot = full copy / reindex | full copy | fast (core strength) | ~484 GB resident → large cluster, **$$$/mo** *(est.²)* | ❌ |\n| Qdrant | snapshot = full copy | full copy | fast (core strength) | ~484 GB → managed/self-host, **$$$/mo** *(est.³)* | ❌ |\n| pgvector | SQL dump + reindex | full copy | moderate | ~484 GB in Postgres *(est.)* | ❌ |\n| Chroma | full collection copy | full copy | moderate | ~484 GB local/managed *(est.)* | ❌ |\n| lakeFS / DVC | fast metadata branch *(their strength)* | file-level delta (cheap) | n/a — not a vector engine | cheap branching, but you still build/serve the ANN index yourself *(published)* | ✅ data/files · ❌ vector index |\n\n**Takeaway:** agenticow wins 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 — use those when single-index query throughput is the priority, and agenticow when you need cheap branching, checkpointing, and rollback of agent memory.\n\n\u003csub\u003e\\* SIFT-1M same-machine (above). † base ~496 MB + 1,000 × ~10.8 KB ≈ 507 MB, in-process. ¹ est. from [pinecone.io/pricing](https://www.pinecone.io/pricing/) (~$0.33/GB-mo storage, excl. read/write units). ² est. from [zilliz.com/pricing](https://zilliz.com/pricing). ³ est. from [qdrant.tech/pricing](https://qdrant.tech/pricing/). Competitor figures are published/estimated; only agenticow's are measured.\u003c/sub\u003e\n\nThe [live site](https://ruvnet.github.io/agenticow/#bench) is mobile-friendly (responsive layout, horizontally-scrollable tables):\n\n\u003cimg src=\"./assets/mobile-hero.png\" width=\"280\" alt=\"agenticow on mobile (375px width)\" /\u003e\n\n---\n\n## Honest scope\n\nagenticow ships, and proves, exactly this:\n\n- ✅ **COW branch creation** — base-size-independent, 162 B / ~0.5 ms (the 83× / 3000× headline). Proven by `npm run bench`.\n- ✅ **Exact read-through queries** — point lookup / flat-scan merge returning `parent ∪ edits`, child wins on collisions, deletes honored. Proven by `npm run acceptance` (recall@10 = 100%, masking PASS).\n- ✅ **Native ANN search ACROSS the COW boundary** — *now shipped* (was roadmap). `fork(label, file, { nativeAnn: true })` creates a real `RvfDatabase.branch()` whose `query()` runs a single Rust dual-graph HNSW merge over parent ∪ child ([RuVector PR #617/#618](https://github.com/ruvnet/RuVector/pull/617)). **Verified recall@10 ≈ 1.0 (0.999)** here — 5,000-vector base ∪ 200 edits, dim 128, default cosine — vs a brute-force ground truth. **Platform caveat:** the native binary ships for **linux-x64-gnu** today; darwin / win / linux-arm64 are pending a CI cross-compile and **degrade gracefully to the exact read-through path** (identical correctness, JS merge — `mem.nativeAnn` reads `false`).\n\nStill honest about the rest:\n\n- We still **concede raw single-index ANN throughput** to dedicated vector DBs — ~6.3× behind a dedicated flat-index engine like hnswlib at 1M-vector scale (matched recall@10 ≈ 0.97; ~2.7× on small in-cache sets). It's a **deliberate trade** — agenticow competes on memory versioning/isolation/rollback, not raw search speed (see [comparison](#how-it-compares)).\n- The **exotic** applications (agent marketplaces, etc.) remain **vision/roadmap**, clearly labeled.\n\n\u003e **Note on cosine.** rvf-node does not persist the cosine metric across a file reopen, and its native COW dual-graph query is accurate for **L2**, not for the cosine metric directly. agenticow therefore drives the underlying engine with **L2 over L2-normalized vectors** when you ask for cosine (the default) — L2 order equals cosine order on unit vectors. This makes **both** the exact read-through **and** the native ANN path correct for cosine, and is why results survive `save()`/`load()`. (Reopening a cosine store via plain `open()` reports the engine metric `l2`; pass `{ metric: 'cosine' }` or use `save()`/`load()` to preserve the user-facing metric.)\n\n---\n\n## Claim ladder\n\nWhere agenticow is today, and where it's going — labeled honestly, each tier backed by **runnable, executed** code.\n\n| Tier | Claim | Status |\n|---|---|---|\n| **Practical** | Cheap, base-independent branch / checkpoint / rollback of vector memory (162 B / ~0.5 ms); exact read-through with tombstone masking. | ✅ **PROVEN** — `npm run bench` + `npm run acceptance` (1,000 branches, recall@10 = 100%) |\n| **Platform** | A \"memory DevOps\" layer — promotion pipelines, compliance/lineage \u0026 right-to-erasure, A/B at scale for multi-agent infrastructure. | ✅ **DEMONSTRATED + benchmarked** — `examples/{promotion-pipeline,compliance-lineage,ab-at-scale}.mjs`; ops bench `npm run bench:ladder`: fork **464 µs**, score **133 µs**, promote **897 µs**, contradiction-check **~1M pairs/s**, **0.84 KB/branch** |\n| **Exotic** | A substrate for evolving / competing cognitive branches — parallel \"selves\", Darwin-on-memory, simulated orgs with contradiction detection. | ⚗️ **PoC-feasible** — `examples/{parallel-selves,memory-evolution,simulated-org}.mjs` demonstrate the branching **mechanics** (shared base, isolated deltas, judge + promote, contradiction scan). The cognitive **quality** of a branch is **out of scope** — the judge/fitness is a scoring function, not validated AI cognition. |\n\nRun the tier examples: `npm run examples` (all) · `npm run examples:platform` · `npm run examples:exotic`.\n\n---\n\n## API\n\n```ts\nimport { open, AgenticMemory } from 'agenticow';\n\nconst mem = open(path, { dimension, metric?, track? });  // metric default \"cosine\"\n\nmem.ingest([{ id, vector }])           // or ingest(Float32Array, ids) for speed\nmem.query(vector, k?, { efSearch?, overscan? })  // exact read-through, child wins\nmem.delete(ids)                        // COW tombstone (hides ancestor ids)\n\nmem.branch(label?)                     // isolated COW fork (auto-isolates the parent)\nmem.fork(label?)                       // lightweight fork off a static/read-only base\nmem.checkpoint(label?)                 // freeze a restore point, keep working\nmem.rollback(checkpointId?)            // discard edits since a checkpoint\n\nmem.diff()                             // { added, overridden, deleted }\nmem.promote(target)                    // replay this branch's edits into target\n\nmem.lineage(); mem.status();           // introspection\nmem.save(manifestPath); AgenticMemory.load(manifestPath)  // persist / reopen the chain\nmem.close();\n```\n\n- **`branch()`** auto-isolates: it freezes the current state and re-points the parent to a fresh child, so neither side sees the other's later writes — safe when you keep writing to both.\n- **`fork()`** is one `derive()` with no re-pointing — ideal for fanning out many branches off a base you won't mutate again (the 1,000-branch case).\n\n---\n\n## Install \u0026 requirements\n\n```bash\nnpm install agenticow\n```\n\n- Node ≥ 18, ESM. Current: **agenticow@0.2.1** on **@ruvector/rvf-node@0.2.0**.\n- Depends on [`@ruvector/rvf-node`](https://www.npmjs.com/package/@ruvector/rvf-node) (prebuilt native binding for linux-x64/arm64, darwin-x64/arm64, win32-x64).\n- **Native ANN across the branch** (`fork({ nativeAnn: true })`) requires the native COW binary, which ships for **linux-x64-gnu** today. On other platforms it degrades gracefully to the exact read-through path — same correctness, `mem.nativeAnn === false`. The exact path (the default) works on every platform.\n\n---\n\n## Keywords\n\nagent memory · vector database branching · copy-on-write · COW vector store · multi-agent memory · embedded vector DB · memory checkpointing · vector branching · git for vectors · AI agent memory · LLM memory · vector snapshot · rollback · checkpoint\n\n---\n\n## License\n\nMIT © [ruvnet](https://github.com/ruvnet). Built on [ruvector](https://github.com/ruvnet/RuVector) RVF.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruvnet%2Fagenticow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruvnet%2Fagenticow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruvnet%2Fagenticow/lists"}