hrr-memory 0.5.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.5.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",