agenticow 0.1.1 → 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.1.1",
+  "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",
@@ -70,6 +70,6 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@ruvector/rvf-node": "0.1.8"
+    "@ruvector/rvf-node": "^0.2.0"
   }
 }

package/src/index.d.ts

@@ -30,6 +30,22 @@ export interface QueryOptions {
   efSearch?: number;
   /** Candidates to over-fetch per store before exact merge. Default: k*4. */
   overscan?: number;
+  /**
+   * Force the exact JS chain-walk even on a native-COW fork.
+   * Default false (native path used when available).
+   */
+  forceExact?: boolean;
+}
+
+export interface ForkOptions {
+  /**
+   * Use the native Rust COW dual-graph ANN path (PR #618).
+   * When true, fork() calls RvfDatabase.branch() instead of derive(), giving
+   * the returned fork a working node whose query() spans the COW boundary in
+   * a single Rust call. recall@10 = 1.0 at 1200-vector L2 test corpus.
+   * Default: false (exact JS chain-walk).
+   */
+  nativeAnn?: boolean;
 }
 
 export interface QueryHit {
@@ -73,12 +89,17 @@ export type IngestRecord = { id: number; vector: number[] | Float32Array };
 export class AgenticMemory {
   static open(filePath: string, opts?: OpenOptions): AgenticMemory;
   readonly dimension: number;
+  /**
+   * True when this fork was created with `{nativeAnn:true}`.
+   * query() routes through the Rust dual-graph ANN merge (PR #618).
+   */
+  readonly nativeAnn: boolean;
   ingest(records: IngestRecord[]): IngestResult;
   ingest(vectors: Float32Array, ids: number[]): IngestResult;
   delete(ids: number[]): { deleted: number; tombstoned: number };
   query(vector: number[] | Float32Array, k?: number, opts?: QueryOptions): QueryHit[];
   branch(label?: string, filePath?: string): AgenticMemory;
-  fork(label?: string, filePath?: string): AgenticMemory;
+  fork(label?: string, filePath?: string, opts?: ForkOptions): AgenticMemory;
   diff(): MemoryDiff;
   promote(target: AgenticMemory): { ingested: number; deleted: number };
   checkpoint(label?: string): CheckpointDescriptor;

package/src/index.js

@@ -74,7 +74,7 @@ class Node {
 
 export class AgenticMemory {
   /** @private */
-  constructor(workingNode, ancestors, dim, metric, track = true, owned = null) {
+  constructor(workingNode, ancestors, dim, metric, track = true, owned = null, nativeCow = false) {
     /** @type {Node} */
     this._working = workingNode;
     /** @type {Node[]} ancestors newest -> oldest (base last) */
@@ -83,11 +83,28 @@ 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>} */
     this._owned = owned || new Set([workingNode]);
     this._closed = false;
+    /**
+     * True when this instance's working node was created via RvfDatabase.branch()
+     * (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. 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;
   }
 
   /**
@@ -103,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 } : {}),
       });
@@ -126,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() {
@@ -209,10 +232,31 @@ export class AgenticMemory {
   query(vector, k = 10, opts = {}) {
     this._assertOpen();
     const qv = this._normalize ? l2normalize(vector) : toF32(vector);
+    const qopts = opts.efSearch ? { efSearch: opts.efSearch } : undefined;
+
+    // ── Native COW dual-graph ANN path ────────────────────────────────
+    // When this instance was created via fork({nativeAnn:true}) or
+    // branch({nativeAnn:true}), the working node's db is a real COW child
+    // (RvfDatabase.branch()). A single db.query() call transparently queries
+    // both the child's own HNSW and the parent's HNSW, merges candidates with
+    // child-wins semantics, and excludes tombstoned IDs — all in Rust.
+    // Recall@10 = 1.0000 on the PR#618 integration test (1200-vector L2,
+    // 60 new + 20 overrides + 10 tombstones, efSearch=300).
+    if (this._nativeCow && !opts.forceExact) {
+      const hits = this._working.db.query(qv, k, qopts);
+      return hits.map((h) => ({
+        id: h.id,
+        distance: h.distance,
+        branch: this._working.label || this._working.id,
+      }));
+    }
+
+    // ── Exact JS chain-walk (default / fallback) ──────────────────────
+    // For each node in the lineage chain (newest first), query its local
+    // store and merge with child-wins semantics.
     const fetch = Math.max(k, opts.overscan || k * 4);
     const resolved = new Map(); // id -> {id, distance, branch}
     const hidden = new Set(); // ids tombstoned by a nearer descendant
-    const qopts = opts.efSearch ? { efSearch: opts.efSearch } : undefined;
     for (const node of this._chain()) {
       for (const t of node.tombstones) hidden.add(t);
       let hits = [];
@@ -229,6 +273,16 @@ export class AgenticMemory {
     return [...resolved.values()].sort((a, b) => a.distance - b.distance).slice(0, k);
   }
 
+  /**
+   * Whether this instance uses the native Rust COW dual-graph ANN query path.
+   * true => query() routes through rvf-runtime's query_via_index_cow (PR #618).
+   * false => exact JS chain-walk across the lineage.
+   * @type {boolean}
+   */
+  get nativeAnn() {
+    return this._nativeCow;
+  }
+
   /**
    * Create an isolated COW branch (a parallel fork of this memory). O(1) in base
    * size — ~0.5 ms / 162 bytes. The branch sees everything this memory currently
@@ -264,13 +318,51 @@ export class AgenticMemory {
    * per-user branches off one shared base). One derive() per fork — ~0.5 ms /
    * 162 bytes each, O(1) in base size. Read-through isolation holds as long as
    * the parent base stays read-only after forking.
+   *
+   * `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 (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]
    * @returns {AgenticMemory}
    */
-  fork(label, filePath) {
+  fork(label, filePath, opts = {}) {
     this._assertOpen();
     const childPath = filePath || tmpChildPath(this._working.path, label);
+    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.
+      // 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');
     return new AgenticMemory(