hrr-memory 0.3.2 → 0.5.0

package/src/memory.js

@@ -24,6 +24,7 @@ import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { bind, unbind, similarity } from './ops.js';
 import { SymbolTable } from './symbols.js';
 import { Bucket, MAX_BUCKET_SIZE } from './bucket.js';
+import { buildAdjacency, dijkstra, neighbors as getNeighbors } from './traversal.js';
 
 const STOP_WORDS = new Set([
   'what', 'is', 'the', 'a', 'an', 'does', 'do', 'where', 'who', 'how',
@@ -37,6 +38,9 @@ export class HRRMemory {
     this.symbols = new SymbolTable(d);
     this.buckets = new Map();
     this.routing = new Map();
+    this._relIndex = new Map(); // "subject\0relation" → Set<bucket_id>
+    this._adjDirty = true;
+    this._adjacency = null;
   }
 
   _activeBucket(subject) {
@@ -80,7 +84,18 @@ export class HRRMemory {
     const r = this.symbols.get(relation);
     const o = this.symbols.get(object);
     const association = bind(bind(s, r), o);
-    this._activeBucket(subject).storeVector(association, triple);
+    const bucket = this._activeBucket(subject);
+    bucket.storeVector(association, triple);
+
+    // Invalidate adjacency cache
+    this._adjDirty = true;
+
+    // Update relation → shard index
+    const indexKey = triple.subject + '\0' + triple.relation;
+    let set = this._relIndex.get(indexKey);
+    if (!set) { set = new Set(); this._relIndex.set(indexKey, set); }
+    set.add(bucket.name);
+
     return true;
   }
 
@@ -98,17 +113,42 @@ export class HRRMemory {
       if (idx === -1) continue;
       bucket.triples.splice(idx, 1);
       bucket.rebuild(this.symbols);
+
+      // Update relation index: remove bucket if it no longer has this relation
+      const indexKey = s + '\0' + r;
+      const set = this._relIndex.get(indexKey);
+      if (set) {
+        const stillHas = bucket.triples.some(t => t.relation === r);
+        if (!stillHas) {
+          set.delete(ids[i]);
+          if (set.size === 0) this._relIndex.delete(indexKey);
+        }
+      }
+
       if (bucket.count === 0 && ids[i].includes('#')) {
         this.buckets.delete(ids[i]);
         ids.splice(i, 1);
       }
+
+      // Invalidate adjacency cache
+      this._adjDirty = true;
+
       return true;
     }
     return false;
   }
 
   query(subject, relation) {
-    const buckets = this._subjectBuckets(subject);
+    const s = subject.toLowerCase().trim();
+    const r = relation.toLowerCase().trim();
+
+    // Fast-path: use relation index to scan only relevant shards
+    const indexKey = s + '\0' + r;
+    const indexed = this._relIndex.get(indexKey);
+    const buckets = indexed
+      ? [...indexed].map(id => this.buckets.get(id)).filter(Boolean)
+      : this._subjectBuckets(subject); // fallback for pre-index data
+
     if (buckets.length === 0) return { match: null, score: 0, confident: false, bucket: null };
     const probe = bind(this.symbols.get(subject), this.symbols.get(relation));
     let bestName = null, bestScore = -1, bestBucket = null;
@@ -179,6 +219,42 @@ export class HRRMemory {
     return { type: 'miss', query: question };
   }
 
+  // ── Graph Traversal ──────────────────────────────────
+
+  /**
+   * Build or return cached adjacency list.
+   * @returns {Map<string, Array<{relation: string, object: string, weight: number}>>}
+   */
+  _getAdjacency() {
+    if (this._adjDirty || !this._adjacency) {
+      this._adjacency = buildAdjacency(this);
+      this._adjDirty = false;
+    }
+    return this._adjacency;
+  }
+
+  /**
+   * Find shortest path between two entities using Dijkstra's algorithm.
+   * @param {string} from - Starting entity
+   * @param {string} to - Target entity
+   * @param {{ maxHops?: number, relations?: string[] }} [options]
+   * @returns {{ found: boolean, path: Array<{subject: string, relation: string, object: string, weight: number}>, totalWeight: number, hops: number } | null}
+   */
+  traverse(from, to, options = {}) {
+    const adj = this._getAdjacency();
+    return dijkstra(adj, from, to, options);
+  }
+
+  /**
+   * Get direct neighbors of a subject in the knowledge graph.
+   * @param {string} subject
+   * @returns {Array<{relation: string, object: string, weight: number}>}
+   */
+  neighbors(subject) {
+    const adj = this._getAdjacency();
+    return getNeighbors(adj, subject);
+  }
+
   stats() {
     let totalFacts = 0;
     const bucketInfo = [];
@@ -219,6 +295,17 @@ export class HRRMemory {
     for (const [k, v] of Object.entries(data.routing || {})) {
       mem.routing.set(k, Array.isArray(v) ? v : [v]);
     }
+
+    // Rebuild relation index from deserialized triples
+    for (const [bucketId, bucket] of mem.buckets) {
+      for (const t of bucket.triples) {
+        const indexKey = t.subject + '\0' + t.relation;
+        let set = mem._relIndex.get(indexKey);
+        if (!set) { set = new Set(); mem._relIndex.set(indexKey, set); }
+        set.add(bucketId);
+      }
+    }
+
     return mem;
   }
 

package/src/observation.js

@@ -49,6 +49,8 @@ export class ObservationMemory {
   search(relation, object) { return this._hrr.search(relation, object); }
   ask(question) { return this._hrr.ask(question); }
   stats() { return this._hrr.stats(); }
+  traverse(from, to, options) { return this._hrr.traverse(from, to, options); }
+  neighbors(subject) { return this._hrr.neighbors(subject); }
 
   // ── Store (async) ──────────────────────────────────
 

package/src/ops.js

@@ -1,107 +1,107 @@
-/**
- * Core HRR operations — circular convolution, correlation, similarity.
- * All vectors are Float32Array. FFT computed in Float64 for precision.
- */
-
-/** Generate a random unit vector of dimension d (Gaussian, normalized) */
-export function randomVector(d) {
-  const v = new Float32Array(d);
-  for (let i = 0; i < d; i += 2) {
-    const u1 = Math.random(), u2 = Math.random();
-    const r = Math.sqrt(-2 * Math.log(u1));
-    v[i] = r * Math.cos(2 * Math.PI * u2);
-    if (i + 1 < d) v[i + 1] = r * Math.sin(2 * Math.PI * u2);
-  }
-  return normalize(v);
-}
-
-/** Normalize vector to unit length */
-export function normalize(v) {
-  let norm = 0;
-  for (let i = 0; i < v.length; i++) norm += v[i] * v[i];
-  norm = Math.sqrt(norm);
-  if (norm === 0) return v;
-  const out = new Float32Array(v.length);
-  for (let i = 0; i < v.length; i++) out[i] = v[i] / norm;
-  return out;
-}
-
-/** Cosine similarity between two vectors */
-export function similarity(a, b) {
-  let dot = 0, na = 0, nb = 0;
-  for (let i = 0; i < a.length; i++) {
-    dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i];
-  }
-  return dot / (Math.sqrt(na) * Math.sqrt(nb) + 1e-10);
-}
-
-// ── FFT (Cooley-Tukey radix-2) ──
-
-function fft(re, im, inverse) {
-  const n = re.length;
-  for (let i = 1, j = 0; i < n; i++) {
-    let bit = n >> 1;
-    for (; j & bit; bit >>= 1) j ^= bit;
-    j ^= bit;
-    if (i < j) {
-      [re[i], re[j]] = [re[j], re[i]];
-      [im[i], im[j]] = [im[j], im[i]];
-    }
-  }
-  for (let len = 2; len <= n; len <<= 1) {
-    const ang = (inverse ? -1 : 1) * 2 * Math.PI / len;
-    const wRe = Math.cos(ang), wIm = Math.sin(ang);
-    for (let i = 0; i < n; i += len) {
-      let curRe = 1, curIm = 0;
-      for (let j = 0; j < len / 2; j++) {
-        const uRe = re[i+j], uIm = im[i+j];
-        const vRe = re[i+j+len/2]*curRe - im[i+j+len/2]*curIm;
-        const vIm = re[i+j+len/2]*curIm + im[i+j+len/2]*curRe;
-        re[i+j] = uRe+vRe; im[i+j] = uIm+vIm;
-        re[i+j+len/2] = uRe-vRe; im[i+j+len/2] = uIm-vIm;
-        const nr = curRe*wRe - curIm*wIm;
-        curIm = curRe*wIm + curIm*wRe;
-        curRe = nr;
-      }
-    }
-  }
-  if (inverse) {
-    for (let i = 0; i < n; i++) { re[i] /= n; im[i] /= n; }
-  }
-}
-
-function nextPow2(n) { let p = 1; while (p < n) p <<= 1; return p; }
-
-/**
- * Circular convolution (binding): a ⊛ b
- * Creates an association between two vectors.
- * Computed in Float64, returned as Float32.
- */
-export function bind(a, b) {
-  const d = a.length, n = nextPow2(d);
-  const aR = new Float64Array(n), aI = new Float64Array(n);
-  const bR = new Float64Array(n), bI = new Float64Array(n);
-  for (let i = 0; i < d; i++) { aR[i] = a[i]; bR[i] = b[i]; }
-  fft(aR, aI, false); fft(bR, bI, false);
-  const cR = new Float64Array(n), cI = new Float64Array(n);
-  for (let i = 0; i < n; i++) {
-    cR[i] = aR[i]*bR[i] - aI[i]*bI[i];
-    cI[i] = aR[i]*bI[i] + aI[i]*bR[i];
-  }
-  fft(cR, cI, true);
-  const out = new Float32Array(d);
-  for (let i = 0; i < d; i++) out[i] = cR[i];
-  return out;
-}
-
-/**
- * Circular correlation (unbinding): retrieve from association.
- * unbind(key, memory) ≈ the value that was bound with key.
- */
-export function unbind(key, memory) {
-  const d = key.length;
-  const inv = new Float32Array(d);
-  inv[0] = key[0];
-  for (let i = 1; i < d; i++) inv[i] = key[d - i];
-  return bind(inv, memory);
-}
+/**
+ * Core HRR operations — circular convolution, correlation, similarity.
+ * All vectors are Float32Array. FFT computed in Float64 for precision.
+ */
+
+/** Generate a random unit vector of dimension d (Gaussian, normalized) */
+export function randomVector(d) {
+  const v = new Float32Array(d);
+  for (let i = 0; i < d; i += 2) {
+    const u1 = Math.random(), u2 = Math.random();
+    const r = Math.sqrt(-2 * Math.log(u1));
+    v[i] = r * Math.cos(2 * Math.PI * u2);
+    if (i + 1 < d) v[i + 1] = r * Math.sin(2 * Math.PI * u2);
+  }
+  return normalize(v);
+}
+
+/** Normalize vector to unit length */
+export function normalize(v) {
+  let norm = 0;
+  for (let i = 0; i < v.length; i++) norm += v[i] * v[i];
+  norm = Math.sqrt(norm);
+  if (norm === 0) return v;
+  const out = new Float32Array(v.length);
+  for (let i = 0; i < v.length; i++) out[i] = v[i] / norm;
+  return out;
+}
+
+/** Cosine similarity between two vectors */
+export function similarity(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i];
+  }
+  return dot / (Math.sqrt(na) * Math.sqrt(nb) + 1e-10);
+}
+
+// ── FFT (Cooley-Tukey radix-2) ──
+
+function fft(re, im, inverse) {
+  const n = re.length;
+  for (let i = 1, j = 0; i < n; i++) {
+    let bit = n >> 1;
+    for (; j & bit; bit >>= 1) j ^= bit;
+    j ^= bit;
+    if (i < j) {
+      [re[i], re[j]] = [re[j], re[i]];
+      [im[i], im[j]] = [im[j], im[i]];
+    }
+  }
+  for (let len = 2; len <= n; len <<= 1) {
+    const ang = (inverse ? -1 : 1) * 2 * Math.PI / len;
+    const wRe = Math.cos(ang), wIm = Math.sin(ang);
+    for (let i = 0; i < n; i += len) {
+      let curRe = 1, curIm = 0;
+      for (let j = 0; j < len / 2; j++) {
+        const uRe = re[i+j], uIm = im[i+j];
+        const vRe = re[i+j+len/2]*curRe - im[i+j+len/2]*curIm;
+        const vIm = re[i+j+len/2]*curIm + im[i+j+len/2]*curRe;
+        re[i+j] = uRe+vRe; im[i+j] = uIm+vIm;
+        re[i+j+len/2] = uRe-vRe; im[i+j+len/2] = uIm-vIm;
+        const nr = curRe*wRe - curIm*wIm;
+        curIm = curRe*wIm + curIm*wRe;
+        curRe = nr;
+      }
+    }
+  }
+  if (inverse) {
+    for (let i = 0; i < n; i++) { re[i] /= n; im[i] /= n; }
+  }
+}
+
+function nextPow2(n) { let p = 1; while (p < n) p <<= 1; return p; }
+
+/**
+ * Circular convolution (binding): a ⊛ b
+ * Creates an association between two vectors.
+ * Computed in Float64, returned as Float32.
+ */
+export function bind(a, b) {
+  const d = a.length, n = nextPow2(d);
+  const aR = new Float64Array(n), aI = new Float64Array(n);
+  const bR = new Float64Array(n), bI = new Float64Array(n);
+  for (let i = 0; i < d; i++) { aR[i] = a[i]; bR[i] = b[i]; }
+  fft(aR, aI, false); fft(bR, bI, false);
+  const cR = new Float64Array(n), cI = new Float64Array(n);
+  for (let i = 0; i < n; i++) {
+    cR[i] = aR[i]*bR[i] - aI[i]*bI[i];
+    cI[i] = aR[i]*bI[i] + aI[i]*bR[i];
+  }
+  fft(cR, cI, true);
+  const out = new Float32Array(d);
+  for (let i = 0; i < d; i++) out[i] = cR[i];
+  return out;
+}
+
+/**
+ * Circular correlation (unbinding): retrieve from association.
+ * unbind(key, memory) ≈ the value that was bound with key.
+ */
+export function unbind(key, memory) {
+  const d = key.length;
+  const inv = new Float32Array(d);
+  inv[0] = key[0];
+  for (let i = 1; i < d; i++) inv[i] = key[d - i];
+  return bind(inv, memory);
+}

package/src/symbols.js

@@ -1,49 +1,49 @@
-/**
- * Shared symbol table — maps string names to random vectors.
- * Shared across all buckets to save memory.
- */
-
-import { randomVector, similarity } from './ops.js';
-
-export class SymbolTable {
-  constructor(d = 2048) {
-    this.d = d;
-    this.symbols = new Map();
-  }
-
-  get(name) {
-    const key = name.toLowerCase().trim();
-    if (!this.symbols.has(key)) this.symbols.set(key, randomVector(this.d));
-    return this.symbols.get(key);
-  }
-
-  has(name) { return this.symbols.has(name.toLowerCase().trim()); }
-
-  get size() { return this.symbols.size; }
-
-  get bytes() { return this.symbols.size * this.d * 4; }
-
-  nearest(vec, candidates = null, topK = 1) {
-    const source = candidates || this.symbols;
-    const results = [];
-    for (const [name, svec] of source) {
-      results.push({ name, score: similarity(vec, svec) });
-    }
-    results.sort((a, b) => b.score - a.score);
-    return topK === 1 ? results[0] || null : results.slice(0, topK);
-  }
-
-  toJSON() {
-    const out = {};
-    for (const [k, v] of this.symbols) out[k] = Array.from(v);
-    return out;
-  }
-
-  static fromJSON(data, d) {
-    const st = new SymbolTable(d);
-    for (const [k, v] of Object.entries(data)) {
-      st.symbols.set(k, new Float32Array(v));
-    }
-    return st;
-  }
-}
+/**
+ * Shared symbol table — maps string names to random vectors.
+ * Shared across all buckets to save memory.
+ */
+
+import { randomVector, similarity } from './ops.js';
+
+export class SymbolTable {
+  constructor(d = 2048) {
+    this.d = d;
+    this.symbols = new Map();
+  }
+
+  get(name) {
+    const key = name.toLowerCase().trim();
+    if (!this.symbols.has(key)) this.symbols.set(key, randomVector(this.d));
+    return this.symbols.get(key);
+  }
+
+  has(name) { return this.symbols.has(name.toLowerCase().trim()); }
+
+  get size() { return this.symbols.size; }
+
+  get bytes() { return this.symbols.size * this.d * 4; }
+
+  nearest(vec, candidates = null, topK = 1) {
+    const source = candidates || this.symbols;
+    const results = [];
+    for (const [name, svec] of source) {
+      results.push({ name, score: similarity(vec, svec) });
+    }
+    results.sort((a, b) => b.score - a.score);
+    return topK === 1 ? results[0] || null : results.slice(0, topK);
+  }
+
+  toJSON() {
+    const out = {};
+    for (const [k, v] of this.symbols) out[k] = Array.from(v);
+    return out;
+  }
+
+  static fromJSON(data, d) {
+    const st = new SymbolTable(d);
+    for (const [k, v] of Object.entries(data)) {
+      st.symbols.set(k, new Float32Array(v));
+    }
+    return st;
+  }
+}

package/src/traversal.js

@@ -0,0 +1,151 @@
+/**
+ * Graph traversal for HRR Memory using Dijkstra's algorithm.
+ *
+ * Builds an adjacency list from stored triples and finds shortest paths
+ * between entities. Edge weights are derived from HRR confidence scores:
+ * weight = 1 - score, so high-confidence edges are cheaper to traverse.
+ */
+
+/**
+ * Build adjacency list from all triples in HRRMemory.
+ * @param {import('./memory.js').HRRMemory} hrr
+ * @returns {Map<string, Array<{relation: string, object: string, weight: number}>>}
+ */
+export function buildAdjacency(hrr) {
+  const adj = new Map();
+
+  for (const bucket of hrr.buckets.values()) {
+    for (const t of bucket.triples) {
+      // Forward edge: subject → object
+      if (!adj.has(t.subject)) adj.set(t.subject, []);
+      adj.get(t.subject).push({
+        relation: t.relation,
+        object: t.object,
+        weight: edgeWeight(hrr, t.subject, t.relation),
+      });
+
+      // Ensure object exists as a node (even if it has no outgoing edges)
+      if (!adj.has(t.object)) adj.set(t.object, []);
+    }
+  }
+
+  return adj;
+}
+
+/**
+ * Compute edge weight from HRR query confidence.
+ * Falls back to 0.5 (neutral) if query returns no confidence.
+ */
+function edgeWeight(hrr, subject, relation) {
+  const result = hrr.query(subject, relation);
+  if (result && result.confident) {
+    return Math.max(0, 1 - result.score);
+  }
+  // For low-confidence edges, still use score but with a floor
+  if (result && result.score > 0) {
+    return 1 - result.score;
+  }
+  return 0.5;
+}
+
+/**
+ * Dijkstra's shortest path between two entities.
+ *
+ * @param {Map<string, Array<{relation: string, object: string, weight: number}>>} adjacency
+ * @param {string} from - Starting entity
+ * @param {string} to - Target entity
+ * @param {object} [options]
+ * @param {number} [options.maxHops=10] - Maximum hops to search
+ * @param {string[]} [options.relations] - Only follow these relation types
+ * @returns {{ found: boolean, path: Array<{subject: string, relation: string, object: string, weight: number}>, totalWeight: number, hops: number } | null}
+ */
+export function dijkstra(adjacency, from, to, options = {}) {
+  const maxHops = options.maxHops ?? 10;
+  const relFilter = options.relations
+    ? new Set(options.relations.map(r => r.toLowerCase().trim()))
+    : null;
+
+  if (!adjacency.has(from) || !adjacency.has(to)) return null;
+  if (from === to) return { found: true, path: [], totalWeight: 0, hops: 0 };
+
+  // dist.get(node) = best known total weight to reach node
+  const dist = new Map();
+  // prev.get(node) = { from, relation, weight } describing the edge used
+  const prev = new Map();
+  // hopCount.get(node) = number of hops to reach node
+  const hopCount = new Map();
+
+  // Simple priority queue using sorted array (sufficient for knowledge graph sizes)
+  const pq = [];
+
+  dist.set(from, 0);
+  hopCount.set(from, 0);
+  pq.push({ node: from, cost: 0 });
+
+  while (pq.length > 0) {
+    // Extract minimum
+    pq.sort((a, b) => a.cost - b.cost);
+    const { node: current, cost: currentCost } = pq.shift();
+
+    // Skip stale entries
+    if (currentCost > (dist.get(current) ?? Infinity)) continue;
+
+    // Found target
+    if (current === to) break;
+
+    // Check hop limit
+    const hops = hopCount.get(current) ?? 0;
+    if (hops >= maxHops) continue;
+
+    // Explore neighbors
+    const neighbors = adjacency.get(current) || [];
+    for (const edge of neighbors) {
+      if (relFilter && !relFilter.has(edge.relation)) continue;
+
+      const newDist = currentCost + edge.weight;
+      const prevDist = dist.get(edge.object) ?? Infinity;
+
+      if (newDist < prevDist) {
+        dist.set(edge.object, newDist);
+        prev.set(edge.object, { from: current, relation: edge.relation, weight: edge.weight });
+        hopCount.set(edge.object, hops + 1);
+        pq.push({ node: edge.object, cost: newDist });
+      }
+    }
+  }
+
+  if (!dist.has(to) || dist.get(to) === Infinity) return null;
+
+  // Reconstruct path
+  const path = [];
+  let current = to;
+  while (current !== from) {
+    const step = prev.get(current);
+    if (!step) return null;
+    path.unshift({
+      subject: step.from,
+      relation: step.relation,
+      object: current,
+      weight: step.weight,
+    });
+    current = step.from;
+  }
+
+  return {
+    found: true,
+    path,
+    totalWeight: Math.round(dist.get(to) * 1000) / 1000,
+    hops: path.length,
+  };
+}
+
+/**
+ * Get direct neighbors of a subject.
+ *
+ * @param {Map<string, Array<{relation: string, object: string, weight: number}>>} adjacency
+ * @param {string} subject
+ * @returns {Array<{relation: string, object: string, weight: number}>}
+ */
+export function neighbors(adjacency, subject) {
+  return adjacency.get(subject.toLowerCase().trim()) || [];
+}