agenticow 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenticow",
-  "version": "0.1.1",
+  "version": "0.2.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",
@@ -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) */
@@ -88,6 +88,16 @@ export class AgenticMemory {
     /** @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. recall@10 = 1.0 at 1200-vector L2
+     * with 5% tombstones (verified in integration tests for rvf-runtime PR #618).
+     * @type {boolean}
+     */
+    this._nativeCow = nativeCow;
   }
 
   /**
@@ -209,10 +219,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 +260,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 +305,37 @@ 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 (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).
    * @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.
+      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
+      );
+    }
     const childDb = this._working.db.derive(childPath, this._deriveOpts());
     const childNode = new Node(childDb, childPath, label || 'fork');
     return new AgenticMemory(