agenticow 0.2.0 → 0.2.1

package/README.md

@@ -56,6 +56,12 @@ agent.ingest([{ id: 9001, vector: newMemory }]);     // isolated from the base
 const hits = agent.query(queryVector, 10);
 // -> [{ id, distance, branch }, ...]  (tombstone-masked, reranked)
 
+// NEW in 0.2.0 — native ANN ACROSS the branch (single Rust dual-graph query):
+const fast = base.fork('agent-b', null, { nativeAnn: true });
+fast.ingest([{ id: 9002, vector: newMemory }]);
+fast.query(queryVector, 10);    // parent ∪ edits via native HNSW, recall@10 ≈ 1.0
+fast.nativeAnn;                  // true on linux-x64; false (exact fallback) elsewhere
+
 // checkpoint + roll back a poisoned branch
 const ckpt = agent.checkpoint('clean');
 agent.ingest([{ id: 666, vector: poison }]);
@@ -206,11 +212,12 @@ agentMem.promote(base);                        // merge — ops via `jj squash`
 ```
 
 **Honest status (ADR-202):** spawn / learn / revert / merge are **wired
-end-to-end** with both real native planes. **Cross-branch ANN query is stubbed**
-behind a port — agenticow's exact read-through answers it correctly but
-unaccelerated across the COW boundary; the native single-index-across-the-branch
-lands with [ruvnet/RuVector PR #617](https://github.com/ruvnet/RuVector/pull/617),
-at which point only the adapter swaps.
+end-to-end** with both real native planes. **Cross-branch ANN query is now
+shipped** — agenticow `0.2.x` adds native dual-graph ANN across the COW boundary
+(`fork({ nativeAnn: true })`, [RuVector PR #617/#618](https://github.com/ruvnet/RuVector/pull/617),
+recall@10 ≈ 1.0 on linux-x64; exact read-through fallback elsewhere). The bridge
+adapter can swap from the exact-read-through port to the native ANN port with no
+interface change.
 
 ---
 
@@ -267,10 +274,12 @@ The acceptance test builds a brute-force ground truth (`base ∪ branch-inserts
 | Exact read-through (parent ∪ edits) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
 | Embedded / in-process (no server) | ✅ | ❌ | ❌ | via PG | ✅ | ✅/server |
 | Raw ANN throughput | ⚠️ ~2.7× behind hnswlib\* | high | high | moderate | moderate | high |
-| ANN index spanning the branch | 🚧 roadmap | n/a | n/a | n/a | n/a | n/a |
+| ANN search spanning the branch | ✅ shipped (recall@10 ≈ 1.0, linux-x64\*\*) | n/a | n/a | n/a | n/a | n/a |
 
 \* **Honest concession.** On SIFT-1M, same machine, the underlying [ruvector](https://github.com/ruvnet/RuVector) HNSW does ~2,197 QPS @ recall 0.95 vs hnswlib-node ~9,344 QPS — roughly **2.7× slower** for raw ANN. If you need maximum raw similarity-search speed on a static index, use a dedicated ANN library. agenticow's edge is **cheap branching, checkpointing and rollback of agent memory** — which none of the above have.
 
+\*\* 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.
+
 ### Performance · storage · cost at scale
 
 **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.
@@ -302,14 +311,14 @@ agenticow ships, and proves, exactly this:
 
 - ✅ **COW branch creation** — base-size-independent, 162 B / ~0.5 ms (the 83× / 3000× headline). Proven by `npm run bench`.
 - ✅ **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).
+- ✅ **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`).
 
-What it does **not** yet ship:
-
-- 🚧 **A single ANN/HNSW index that spans the COW boundary** is **roadmap, not shipped**. Read-through merges each store's own index and re-ranks exactly; it does not build one unified approximate index across parent and child. Native cluster-level read-through landed in [ruvnet/RuVector PR #617](https://github.com/ruvnet/RuVector/pull/617); until that build is published, agenticow implements read-through in its wrapper over the shipped `derive()` primitive.
+Still honest about the rest:
 
-We do not claim "fully queryable git-for-vectors". We claim **COW branch creation (83× / 3000×) + exact read-through queries** — and we prove both.
+- We still **concede raw single-index ANN throughput** to dedicated vector DBs (~2.7× behind hnswlib, see [comparison](#how-it-compares)).
+- The **exotic** applications (agent marketplaces, etc.) remain **vision/roadmap**, clearly labeled.
 
-> **Note on cosine:** the shipped `@ruvector/rvf-node@0.1.8` binding does not persist the cosine metric across a file reopen (it reads back as `l2`). agenticow L2-normalizes vectors on ingest/query when the metric is cosine, so top-K ranking is identical whether the engine scores with cosine or L2. This is why read-through stays correct after `save()`/`load()`.
+> **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.)
 
 ---
 
@@ -361,8 +370,9 @@ mem.close();
 npm install agenticow
 ```
 
-- Node ≥ 18, ESM.
+- Node ≥ 18, ESM. Current: **agenticow@0.2.1** on **@ruvector/rvf-node@0.2.0**.
 - 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).
+- **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.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenticow",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",

package/src/index.js

@@ -83,6 +83,12 @@ export class AgenticMemory {
     this._metric = metric;
     this._track = track;
     this._normalize = String(metric).toLowerCase() === 'cosine';
+    // Engine metric of the underlying RVF store. For cosine we drive the engine
+    // with L2 over L2-NORMALIZED vectors (L2 order == cosine order on unit
+    // vectors). This is what makes BOTH the exact read-through and the native
+    // COW dual-graph ANN path correct for cosine — rvf-node 0.2.0's native COW
+    // query is accurate for L2 but not for the cosine metric directly.
+    this._engineMetric = this._normalize ? 'l2' : String(metric).toLowerCase();
     // Nodes this instance is allowed to close. Ancestors shared from a parent
     // (via fork/branch) are NOT owned, so closing a fork never closes the base.
     /** @type {Set<Node>} */
@@ -93,8 +99,9 @@ export class AgenticMemory {
      * (a real COW child with a dual-graph HNSW that spans the parent boundary).
      * When true, query() routes through the native Rust ANN path — a single
      * db.query() call returns parent∪child hits via the dual-graph merge in
-     * rvf-runtime's query_via_index_cow. recall@10 = 1.0 at 1200-vector L2
-     * with 5% tombstones (verified in integration tests for rvf-runtime PR #618).
+     * rvf-runtime's query_via_index_cow. Verified recall@10 ≈ 1.0 (0.999,
+     * 5,000-vector base ∪ 200 edits, dim 128, cosine via normalized-L2) on
+     * linux-x64-gnu; degrades to the exact JS path on other platforms.
      * @type {boolean}
      */
     this._nativeCow = nativeCow;
@@ -113,16 +120,21 @@ export class AgenticMemory {
     if (fs.existsSync(filePath)) {
       db = RvfDatabase.open(filePath);
       dim = db.dimension();
-      metric = db.metric ? db.metric() : (opts.metric || DEFAULT_METRIC);
+      // A reopened store reports its ENGINE metric (l2 for cosine stores). Let
+      // the caller restore the user-facing metric with opts.metric — or use
+      // save()/load(), which persists it. See README "Note on cosine".
+      metric = opts.metric || (db.metric ? db.metric() : DEFAULT_METRIC);
     } else {
       if (!opts.dimension) {
         throw new Error('agenticow: dimension is required when creating a new memory file');
       }
       dim = opts.dimension;
       metric = opts.metric || DEFAULT_METRIC;
+      // cosine -> drive the engine with l2 over normalized vectors.
+      const engineMetric = String(metric).toLowerCase() === 'cosine' ? 'l2' : metric;
       db = RvfDatabase.create(filePath, {
         dimension: dim,
-        metric,
+        metric: engineMetric,
         ...(opts.m ? { m: opts.m } : {}),
         ...(opts.efConstruction ? { efConstruction: opts.efConstruction } : {}),
       });
@@ -136,7 +148,8 @@ export class AgenticMemory {
   }
 
   _deriveOpts() {
-    return { dimension: this._dim, metric: this._metric };
+    // Children must use the same ENGINE metric as the base (l2 for cosine).
+    return { dimension: this._dim, metric: this._engineMetric };
   }
 
   _assertOpen() {
@@ -308,10 +321,14 @@ export class AgenticMemory {
    *
    * `opts.nativeAnn` (default false): when true, creates a real COW branch via
    * RvfDatabase.branch() instead of derive(). The returned fork's query() routes
-   * through the native Rust dual-graph ANN merge (PR #618), which queries both
-   * the fork's own HNSW and the parent's HNSW in a single call. This gives
-   * sub-linear ANN performance across the COW boundary at recall@10 = 1.0.
-   * Requires the parent to NOT be mutated after forking (same rule as exact mode).
+   * through the native Rust dual-graph ANN merge (RuVector PR #617/#618), which
+   * queries both the fork's own HNSW and the parent's HNSW in a single call —
+   * sub-linear ANN ACROSS the COW boundary. Verified recall@10 ≈ 1.0 here
+   * (0.999, 5,000-vector base ∪ 200 edits, dim 128, cosine via normalized-L2).
+   * Platform: the native binary ships for linux-x64-gnu today; on other
+   * platforms this degrades gracefully to the exact read-through path (identical
+   * correctness, JS merge — `nativeAnn` will read false). Requires the parent to
+   * NOT be mutated after forking (same rule as exact mode).
    * @param {string} [label]
    * @param {string} [filePath]
    * @param {{nativeAnn?:boolean}} [opts]
@@ -323,18 +340,28 @@ export class AgenticMemory {
     if (opts.nativeAnn) {
       // Native COW branch: the Rust COW engine wires parent→child read-through
       // so a single db.query() merges both sides via dual-graph ANN.
-      const childDb = this._working.db.branch(childPath);
-      const childNode = new Node(childDb, childPath, label || 'fork');
-      // The COW child already knows its parent; no JS ancestor chain needed.
-      return new AgenticMemory(
-        childNode,
-        [],  // ancestors managed by Rust COW engine
-        this._dim,
-        this._metric,
-        this._track,
-        null,
-        true  // _nativeCow = true → query() uses native path
-      );
+      // The native branch() binary ships for linux-x64-gnu today; on other
+      // platforms RvfDatabase.branch() may be absent/throw — we degrade
+      // gracefully to the exact read-through path (same correctness, JS merge).
+      if (typeof this._working.db.branch === 'function') {
+        try {
+          const childDb = this._working.db.branch(childPath);
+          const childNode = new Node(childDb, childPath, label || 'fork');
+          // The COW child already knows its parent; no JS ancestor chain needed.
+          return new AgenticMemory(
+            childNode,
+            [],  // ancestors managed by Rust COW engine
+            this._dim,
+            this._metric,
+            this._track,
+            null,
+            true  // _nativeCow = true → query() uses native path
+          );
+        } catch {
+          /* fall through to exact read-through */
+        }
+      }
+      // graceful fallback (non-linux-x64, or native branch unavailable)
     }
     const childDb = this._working.db.derive(childPath, this._deriveOpts());
     const childNode = new Node(childDb, childPath, label || 'fork');