hrr-memory 0.4.0 → 0.5.1

package/README.md

@@ -105,6 +105,25 @@ mem.addObservation({
 });
 ```
 
+## Graph Traversal
+
+Dijkstra's shortest path between entities, with edge weights derived from HRR confidence scores.
+
+```js
+mem.store('alice', 'works_at', 'acme');
+mem.store('acme', 'uses', 'aws');
+mem.store('aws', 'runs', 'ec2');
+
+mem.traverse('alice', 'ec2');
+// { found: true, hops: 3, totalWeight: 0.12,
+//   path: [{ relation: 'works_at', subject: 'alice', object: 'acme' }, ...] }
+
+mem.neighbors('acme');
+// [{ relation: 'uses', object: 'aws', weight: 0.04 }, ...]
+```
+
+Adjacency is lazily built and cached — rebuilt automatically after `store()` or `forget()`.
+
 ## Performance
 
 | Facts | Accuracy | Query time | RAM |
@@ -128,6 +147,8 @@ Auto-sharding kicks in at 25 facts per subject. Accuracy stays at 100% across sh
 | `search(r?, o?)` | `Triple[]` | Find triples by relation and/or object. |
 | `ask(question)` | `AskResult` | Natural language query with stop-word handling. |
 | `stats()` | `Stats` | Memory usage, bucket info, fact counts. |
+| `traverse(from, to, opts?)` | `PathResult` | Dijkstra shortest path between entities. |
+| `neighbors(subject)` | `Neighbor[]` | Directly connected entities. |
 | `save(path)` | `void` | Persist to JSON file. |
 | `HRRMemory.load(path)` | `HRRMemory` | Load from JSON file. |
 
@@ -149,6 +170,28 @@ All HRRMemory methods are delegated (query, querySubject, search, ask, stats).
 | `save(hrrPath, obsPath)` | `void` | Persist both stores. |
 | `ObservationMemory.load(hrrPath, obsPath, opts)` | `ObservationMemory` | Load both stores. |
 
+### Graph Traversal
+
+Find paths through the knowledge graph using Dijkstra's algorithm. Edge weights are derived from HRR confidence (`1 - score`), so high-confidence connections are preferred.
+
+```js
+mem.store('sherlock', 'depends_on', 'postgres');
+mem.store('postgres', 'runs_on', 'docker');
+mem.store('docker', 'uses', 'linux');
+
+mem.traverse('sherlock', 'linux');
+// { found: true, hops: 3, totalWeight: 0.12, path: [...] }
+
+mem.neighbors('sherlock');
+// [{ relation: 'depends_on', object: 'postgres', weight: 0.03 }]
+
+// Limit search depth or filter by relation type
+mem.traverse('sherlock', 'linux', { maxHops: 5 });
+mem.traverse('sherlock', 'linux', { relations: ['depends_on', 'runs_on'] });
+```
+
+Adjacency is lazily built and cached, automatically invalidated on `store`/`forget`.
+
 ### Standalone Components
 
 Each layer works independently:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hrr-memory",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Holographic Reduced Representations for structured agent memory. Structured facts, temporal awareness, conflict detection, and belief synthesis. Zero dependencies.",
   "type": "module",
   "main": "src/index.js",
@@ -13,7 +13,7 @@
     "types/"
   ],
   "scripts": {
-    "test": "node --test test/memory.test.js test/timeline.test.js test/conflict.test.js test/prompt.test.js test/integration.test.js",
+    "test": "node --test test/memory.test.js test/timeline.test.js test/conflict.test.js test/prompt.test.js test/integration.test.js test/traversal.test.js",
     "bench": "node bench/benchmark.js",
     "bench:obs": "node bench/benchmark-obs.js"
   },

package/src/index.js

@@ -17,6 +17,7 @@ export { HRRMemory } from './memory.js';
 export { SymbolTable } from './symbols.js';
 export { Bucket } from './bucket.js';
 export { bind, unbind, similarity, randomVector, normalize } from './ops.js';
+export { buildAdjacency, dijkstra, neighbors } from './traversal.js';
 
 // Observation layer
 export { ObservationMemory, ObservationParseError } from './observation.js';

package/src/memory.js

@@ -1,275 +1,321 @@
-/**
- * HRRMemory — auto-sharded holographic memory store.
- *
- * Stores (subject, relation, object) triples in sharded buckets.
- * Each bucket holds max 25 facts. When full, a new overflow bucket
- * is created automatically. Queries scan all buckets for a subject.
- *
- * Symbol vectors are shared across all buckets.
- * All values are lowercased on store. If you need case-sensitive values,
- * normalize them yourself before calling store().
- *
- * @typedef {{ match: string|null, score: number, confident: boolean, bucket: string|null }} QueryResult
- * @typedef {{ relation: string, object: string }} Fact
- * @typedef {{ subject: string, relation: string, object: string }} Triple
- * @typedef {{ type: 'direct', match: string, score: number, confident: boolean, subject: string, relation: string, bucket: string|null }} DirectAskResult
- * @typedef {{ type: 'subject', subject: string, facts: Fact[] }} SubjectAskResult
- * @typedef {{ type: 'search', term: string, results: Triple[] }} SearchAskResult
- * @typedef {{ type: 'miss', query: string }} MissAskResult
- * @typedef {DirectAskResult | SubjectAskResult | SearchAskResult | MissAskResult} AskResult
- * @typedef {{ dimensions: number, maxBucketSize: number, symbols: number, buckets: number, subjects: number, totalFacts: number, ramBytes: number, ramMB: number, perBucket: Array<{name: string, facts: number, full: boolean}> }} Stats
- */
-
-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';
-
-const STOP_WORDS = new Set([
-  'what', 'is', 'the', 'a', 'an', 'does', 'do', 'where', 'who', 'how',
-  'which', 'of', 'for', 'in', 'at', 'to', 'my', 'your', 'their', 'has',
-  'have', 'was', 'were', 'are', 'been',
-]);
-
-export class HRRMemory {
-  constructor(d = 2048) {
-    this.d = d;
-    this.symbols = new SymbolTable(d);
-    this.buckets = new Map();
-    this.routing = new Map();
-    this._relIndex = new Map(); // "subject\0relation" → Set<bucket_id>
-  }
-
-  _activeBucket(subject) {
-    const key = subject.toLowerCase().trim();
-    const ids = this.routing.get(key);
-    if (ids) {
-      const lastId = ids[ids.length - 1];
-      const last = this.buckets.get(lastId);
-      if (!last.isFull) return last;
-      const newId = key + '#' + ids.length;
-      const nb = new Bucket(newId, this.d);
-      this.buckets.set(newId, nb);
-      ids.push(newId);
-      return nb;
-    }
-    const b = new Bucket(key, this.d);
-    this.buckets.set(key, b);
-    this.routing.set(key, [key]);
-    return b;
-  }
-
-  _subjectBuckets(subject) {
-    const ids = this.routing.get(subject.toLowerCase().trim()) || [];
-    return ids.map(id => this.buckets.get(id)).filter(Boolean);
-  }
-
-  store(subject, relation, object) {
-    const triple = {
-      subject: subject.toLowerCase().trim(),
-      relation: relation.toLowerCase().trim(),
-      object: object.toLowerCase().trim(),
-    };
-    for (const b of this._subjectBuckets(subject)) {
-      if (b.triples.some(t =>
-        t.subject === triple.subject &&
-        t.relation === triple.relation &&
-        t.object === triple.object
-      )) return false;
-    }
-    const s = this.symbols.get(subject);
-    const r = this.symbols.get(relation);
-    const o = this.symbols.get(object);
-    const association = bind(bind(s, r), o);
-    const bucket = this._activeBucket(subject);
-    bucket.storeVector(association, triple);
-
-    // 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;
-  }
-
-  forget(subject, relation, object) {
-    const s = subject.toLowerCase().trim();
-    const r = relation.toLowerCase().trim();
-    const o = object.toLowerCase().trim();
-    const ids = this.routing.get(s);
-    if (!ids) return false;
-    for (let i = 0; i < ids.length; i++) {
-      const bucket = this.buckets.get(ids[i]);
-      const idx = bucket.triples.findIndex(t =>
-        t.subject === s && t.relation === r && t.object === o
-      );
-      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);
-      }
-      return true;
-    }
-    return false;
-  }
-
-  query(subject, relation) {
-    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;
-    for (const bucket of buckets) {
-      if (bucket.count === 0) continue;
-      const result = unbind(probe, bucket.memory);
-      for (const t of bucket.triples) {
-        const score = similarity(result, this.symbols.get(t.object));
-        if (score > bestScore) {
-          bestScore = score;
-          bestName = t.object;
-          bestBucket = bucket.name;
-        }
-      }
-    }
-    return {
-      match: bestName,
-      score: Math.round(bestScore * 1000) / 1000,
-      confident: bestScore > 0.1,
-      bucket: bestBucket,
-    };
-  }
-
-  querySubject(subject) {
-    const key = subject.toLowerCase().trim();
-    const facts = [];
-    for (const bucket of this._subjectBuckets(subject)) {
-      for (const t of bucket.triples) {
-        if (t.subject === key) facts.push({ relation: t.relation, object: t.object });
-      }
-    }
-    return facts;
-  }
-
-  search(relation, object) {
-    const results = [];
-    const rel = relation ? relation.toLowerCase().trim() : null;
-    const obj = object ? object.toLowerCase().trim() : null;
-    for (const [_, bucket] of this.buckets) {
-      for (const t of bucket.triples) {
-        if (rel && t.relation !== rel) continue;
-        if (obj && t.object !== obj) continue;
-        results.push(t);
-      }
-    }
-    return results;
-  }
-
-  ask(question) {
-    const parts = question.toLowerCase().trim()
-      .replace(/[?.,!]/g, '')
-      .replace(/'s\b/g, '')
-      .replace(/-/g, '_')
-      .split(/\s+/)
-      .filter(w => !STOP_WORDS.has(w) && w.length > 0);
-    for (let i = 0; i < parts.length - 1; i++) {
-      const result = this.query(parts[i], parts[i + 1]);
-      if (result.confident) return { type: 'direct', ...result, subject: parts[i], relation: parts[i + 1] };
-    }
-    for (const word of parts) {
-      const facts = this.querySubject(word);
-      if (facts.length > 0) return { type: 'subject', subject: word, facts };
-    }
-    for (const word of parts) {
-      const results = this.search(null, word);
-      if (results.length > 0) return { type: 'search', term: word, results };
-    }
-    return { type: 'miss', query: question };
-  }
-
-  stats() {
-    let totalFacts = 0;
-    const bucketInfo = [];
-    for (const [_, b] of this.buckets) {
-      totalFacts += b.count;
-      bucketInfo.push({ name: b.name, facts: b.count, full: b.isFull });
-    }
-    const symBytes = this.symbols.size * this.d * 4;
-    const bktBytes = this.buckets.size * this.d * 4;
-    return {
-      dimensions: this.d,
-      maxBucketSize: MAX_BUCKET_SIZE,
-      symbols: this.symbols.size,
-      buckets: this.buckets.size,
-      subjects: this.routing.size,
-      totalFacts,
-      ramBytes: symBytes + bktBytes,
-      ramMB: Math.round((symBytes + bktBytes) / 1024 / 1024 * 10) / 10,
-      perBucket: bucketInfo,
-    };
-  }
-
-  toJSON() {
-    const buckets = {};
-    for (const [k, v] of this.buckets) buckets[k] = v.toJSON();
-    const routing = {};
-    for (const [k, v] of this.routing) routing[k] = v;
-    return { version: 3, d: this.d, symbols: this.symbols.toJSON(), buckets, routing };
-  }
-
-  static fromJSON(data) {
-    const d = data.d || 2048;
-    const mem = new HRRMemory(d);
-    mem.symbols = SymbolTable.fromJSON(data.symbols || {}, d);
-    for (const [k, v] of Object.entries(data.buckets || {})) {
-      mem.buckets.set(k, Bucket.fromJSON(v, d));
-    }
-    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;
-  }
-
-  save(filePath) {
-    writeFileSync(filePath, JSON.stringify(this.toJSON()));
-  }
-
-  static load(filePath, d = 2048) {
-    if (!existsSync(filePath)) return new HRRMemory(d);
-    try { return HRRMemory.fromJSON(JSON.parse(readFileSync(filePath, 'utf8'))); }
-    catch { return new HRRMemory(d); }
-  }
-}
+/**
+ * HRRMemory — auto-sharded holographic memory store.
+ *
+ * Stores (subject, relation, object) triples in sharded buckets.
+ * Each bucket holds max 25 facts. When full, a new overflow bucket
+ * is created automatically. Queries scan all buckets for a subject.
+ *
+ * Symbol vectors are shared across all buckets.
+ * All values are lowercased on store. If you need case-sensitive values,
+ * normalize them yourself before calling store().
+ *
+ * @typedef {{ match: string|null, score: number, confident: boolean, bucket: string|null }} QueryResult
+ * @typedef {{ relation: string, object: string }} Fact
+ * @typedef {{ subject: string, relation: string, object: string }} Triple
+ * @typedef {{ type: 'direct', match: string, score: number, confident: boolean, subject: string, relation: string, bucket: string|null }} DirectAskResult
+ * @typedef {{ type: 'subject', subject: string, facts: Fact[] }} SubjectAskResult
+ * @typedef {{ type: 'search', term: string, results: Triple[] }} SearchAskResult
+ * @typedef {{ type: 'miss', query: string }} MissAskResult
+ * @typedef {DirectAskResult | SubjectAskResult | SearchAskResult | MissAskResult} AskResult
+ * @typedef {{ dimensions: number, maxBucketSize: number, symbols: number, buckets: number, subjects: number, totalFacts: number, ramBytes: number, ramMB: number, perBucket: Array<{name: string, facts: number, full: boolean}> }} Stats
+ */
+
+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',
+  'which', 'of', 'for', 'in', 'at', 'to', 'my', 'your', 'their', 'has',
+  'have', 'was', 'were', 'are', 'been',
+]);
+
+export class HRRMemory {
+  constructor(d = 2048) {
+    this.d = d;
+    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) {
+    const key = subject.toLowerCase().trim();
+    const ids = this.routing.get(key);
+    if (ids) {
+      const lastId = ids[ids.length - 1];
+      const last = this.buckets.get(lastId);
+      if (!last.isFull) return last;
+      const newId = key + '#' + ids.length;
+      const nb = new Bucket(newId, this.d);
+      this.buckets.set(newId, nb);
+      ids.push(newId);
+      return nb;
+    }
+    const b = new Bucket(key, this.d);
+    this.buckets.set(key, b);
+    this.routing.set(key, [key]);
+    return b;
+  }
+
+  _subjectBuckets(subject) {
+    const ids = this.routing.get(subject.toLowerCase().trim()) || [];
+    return ids.map(id => this.buckets.get(id)).filter(Boolean);
+  }
+
+  store(subject, relation, object) {
+    const triple = {
+      subject: subject.toLowerCase().trim(),
+      relation: relation.toLowerCase().trim(),
+      object: object.toLowerCase().trim(),
+    };
+    for (const b of this._subjectBuckets(subject)) {
+      if (b.triples.some(t =>
+        t.subject === triple.subject &&
+        t.relation === triple.relation &&
+        t.object === triple.object
+      )) return false;
+    }
+    const s = this.symbols.get(subject);
+    const r = this.symbols.get(relation);
+    const o = this.symbols.get(object);
+    const association = bind(bind(s, r), o);
+    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;
+  }
+
+  forget(subject, relation, object) {
+    const s = subject.toLowerCase().trim();
+    const r = relation.toLowerCase().trim();
+    const o = object.toLowerCase().trim();
+    const ids = this.routing.get(s);
+    if (!ids) return false;
+    for (let i = 0; i < ids.length; i++) {
+      const bucket = this.buckets.get(ids[i]);
+      const idx = bucket.triples.findIndex(t =>
+        t.subject === s && t.relation === r && t.object === o
+      );
+      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 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;
+    for (const bucket of buckets) {
+      if (bucket.count === 0) continue;
+      const result = unbind(probe, bucket.memory);
+      for (const t of bucket.triples) {
+        const score = similarity(result, this.symbols.get(t.object));
+        if (score > bestScore) {
+          bestScore = score;
+          bestName = t.object;
+          bestBucket = bucket.name;
+        }
+      }
+    }
+    return {
+      match: bestName,
+      score: Math.round(bestScore * 1000) / 1000,
+      confident: bestScore > 0.1,
+      bucket: bestBucket,
+    };
+  }
+
+  querySubject(subject) {
+    const key = subject.toLowerCase().trim();
+    const facts = [];
+    for (const bucket of this._subjectBuckets(subject)) {
+      for (const t of bucket.triples) {
+        if (t.subject === key) facts.push({ relation: t.relation, object: t.object });
+      }
+    }
+    return facts;
+  }
+
+  search(relation, object) {
+    const results = [];
+    const rel = relation ? relation.toLowerCase().trim() : null;
+    const obj = object ? object.toLowerCase().trim() : null;
+    for (const [_, bucket] of this.buckets) {
+      for (const t of bucket.triples) {
+        if (rel && t.relation !== rel) continue;
+        if (obj && t.object !== obj) continue;
+        results.push(t);
+      }
+    }
+    return results;
+  }
+
+  ask(question) {
+    const parts = question.toLowerCase().trim()
+      .replace(/[?.,!]/g, '')
+      .replace(/'s\b/g, '')
+      .replace(/-/g, '_')
+      .split(/\s+/)
+      .filter(w => !STOP_WORDS.has(w) && w.length > 0);
+    for (let i = 0; i < parts.length - 1; i++) {
+      const result = this.query(parts[i], parts[i + 1]);
+      if (result.confident) return { type: 'direct', ...result, subject: parts[i], relation: parts[i + 1] };
+    }
+    for (const word of parts) {
+      const facts = this.querySubject(word);
+      if (facts.length > 0) return { type: 'subject', subject: word, facts };
+    }
+    for (const word of parts) {
+      const results = this.search(null, word);
+      if (results.length > 0) return { type: 'search', term: word, results };
+    }
+    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 = [];
+    for (const [_, b] of this.buckets) {
+      totalFacts += b.count;
+      bucketInfo.push({ name: b.name, facts: b.count, full: b.isFull });
+    }
+    const symBytes = this.symbols.size * this.d * 4;
+    const bktBytes = this.buckets.size * this.d * 4;
+    return {
+      dimensions: this.d,
+      maxBucketSize: MAX_BUCKET_SIZE,
+      symbols: this.symbols.size,
+      buckets: this.buckets.size,
+      subjects: this.routing.size,
+      totalFacts,
+      ramBytes: symBytes + bktBytes,
+      ramMB: Math.round((symBytes + bktBytes) / 1024 / 1024 * 10) / 10,
+      perBucket: bucketInfo,
+    };
+  }
+
+  toJSON() {
+    const buckets = {};
+    for (const [k, v] of this.buckets) buckets[k] = v.toJSON();
+    const routing = {};
+    for (const [k, v] of this.routing) routing[k] = v;
+    return { version: 3, d: this.d, symbols: this.symbols.toJSON(), buckets, routing };
+  }
+
+  static fromJSON(data) {
+    const d = data.d || 2048;
+    const mem = new HRRMemory(d);
+    mem.symbols = SymbolTable.fromJSON(data.symbols || {}, d);
+    for (const [k, v] of Object.entries(data.buckets || {})) {
+      mem.buckets.set(k, Bucket.fromJSON(v, d));
+    }
+    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;
+  }
+
+  save(filePath) {
+    writeFileSync(filePath, JSON.stringify(this.toJSON()));
+  }
+
+  static load(filePath, d = 2048) {
+    if (!existsSync(filePath)) return new HRRMemory(d);
+    try { return HRRMemory.fromJSON(JSON.parse(readFileSync(filePath, 'utf8'))); }
+    catch { return new HRRMemory(d); }
+  }
+}

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/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()) || [];
+}