hrr-memory 0.3.0 → 0.3.1

package/README.md

@@ -0,0 +1,179 @@
+# hrr-memory
+
+**Structured fact recall for AI agents. Sub-2ms queries, zero dependencies.**
+
+hrr-memory stores facts as `(subject, relation, object)` triples using Holographic Reduced Representations and retrieves them instantly — no vector database, no embeddings API. Includes built-in temporal awareness, conflict detection, and LLM-driven belief synthesis.
+
+## Install
+
+```bash
+npm install hrr-memory
+```
+
+## Quick Demo
+
+```js
+import { HRRMemory } from 'hrr-memory';
+
+const mem = new HRRMemory();
+
+mem.store('alice', 'lives_in', 'paris');
+mem.store('alice', 'works_at', 'acme');
+mem.store('bob', 'lives_in', 'tokyo');
+
+mem.query('alice', 'lives_in');  // { match: 'paris', confident: true }
+mem.query('bob', 'lives_in');    // { match: 'tokyo', confident: true }
+
+mem.querySubject('alice');
+// [{ relation: 'lives_in', object: 'paris' },
+//  { relation: 'works_at', object: 'acme' }]
+
+mem.ask("What is alice's timezone?");
+// Direct lookup with stop-word stripping and natural language handling
+
+mem.save('memory.json');
+```
+
+## Why Not Just RAG?
+
+| Query type | RAG | hrr-memory |
+|---|---|---|
+| "What is Alice's timezone?" | Returns paragraphs, maybe | Returns `cet` in <1ms |
+| "Find notes about deployment" | Ranked chunks | Not suited — use RAG |
+| "What changed about Alice?" | No built-in tracking | Conflict detection + timeline |
+
+Use both. HRR for structured facts, RAG for semantic search.
+
+## Observation Layer
+
+Track how knowledge evolves over time. ObservationMemory wraps HRRMemory with a timeline, automatic conflict detection, and belief synthesis.
+
+```js
+import { HRRMemory, ObservationMemory } from 'hrr-memory';
+
+const hrr = new HRRMemory();
+const mem = new ObservationMemory(hrr);
+
+await mem.store('alice', 'interested_in', 'rust');
+await mem.store('alice', 'interested_in', 'payments');
+
+mem.flags();
+// [{ subject: 'alice', oldObject: 'rust', newObject: 'payments', similarity: 0.05 }]
+
+mem.history('alice');
+// [{ ts: ..., op: 'store', object: 'rust' },
+//  { ts: ..., op: 'store', object: 'payments', conflict: { oldObject: 'rust' } }]
+```
+
+Conflict detection is algebraic — it compares HRR symbol vectors using cosine similarity. Low similarity between old and new values means a belief change, which gets flagged automatically.
+
+## Point-in-Time Queries
+
+Symbolic replay of the timeline. Fast and cheap — no HRR rebuild.
+
+```js
+mem.at(lastWeek).facts('alice', 'interested_in');
+// ['rust']  — what we knew then
+
+mem.at(Date.now()).facts('alice', 'interested_in');
+// ['rust', 'payments']  — what we know now
+```
+
+## LLM Consolidation
+
+Flags accumulate until you consolidate them. The library builds the prompt; you bring the LLM.
+
+```js
+const mem = new ObservationMemory(hrr, {
+  executor: (prompt) => callYourLLM(prompt),
+});
+
+// After conflicting stores...
+const observations = await mem.consolidate();
+// [{ subject: 'alice', observation: 'Interest shifted from Rust to payments',
+//    evidence: [...], confidence: 'high' }]
+```
+
+Or skip the LLM and write observations directly:
+
+```js
+mem.addObservation({
+  subject: 'alice',
+  observation: 'Interest shifted from Rust to payments',
+  evidence: [{ ts: 1711234567890, triple: ['alice', 'interested_in', 'rust'] }],
+  confidence: 'high',
+});
+```
+
+## Performance
+
+| Facts | Accuracy | Query time | RAM |
+|---|---|---|---|
+| 100 | 100% | <1ms | 0.1 MB |
+| 1,000 | 100% | 1.5ms | 4 MB |
+| 10,000 | 100% | 1.8ms | 86 MB |
+
+Auto-sharding kicks in at 25 facts per subject. Accuracy stays at 100% across shards.
+
+## API
+
+### HRRMemory (core)
+
+| Method | Returns | Description |
+|---|---|---|
+| `store(s, r, o)` | `boolean` | Store a triple. Returns false if duplicate. |
+| `forget(s, r, o)` | `boolean` | Remove a triple. |
+| `query(s, r)` | `QueryResult` | Retrieve the object for a subject+relation pair. |
+| `querySubject(s)` | `Fact[]` | All facts about a subject. |
+| `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. |
+| `save(path)` | `void` | Persist to JSON file. |
+| `HRRMemory.load(path)` | `HRRMemory` | Load from JSON file. |
+
+### ObservationMemory (observation layer)
+
+All HRRMemory methods are delegated (query, querySubject, search, ask, stats).
+
+| Method | Returns | Description |
+|---|---|---|
+| `await store(s, r, o)` | `boolean` | Store with timeline recording and conflict detection. |
+| `await forget(s, r, o)` | `boolean` | Forget with timeline recording. |
+| `history(s, r?)` | `TimelineEntry[]` | Temporal history, oldest first. |
+| `at(ts).facts(s, r?)` | `string[]` | Point-in-time symbolic query. |
+| `flags()` | `ConflictFlag[]` | Unflushed conflict flags. |
+| `clearFlags(subject)` | `void` | Clear flags for a subject. |
+| `observations(s?)` | `Observation[]` | Synthesized beliefs, newest first. |
+| `addObservation(obs)` | `Observation` | Store observation directly (no LLM). |
+| `await consolidate()` | `Observation[]` | LLM-driven synthesis of flagged changes. |
+| `save(hrrPath, obsPath)` | `void` | Persist both stores. |
+| `ObservationMemory.load(hrrPath, obsPath, opts)` | `ObservationMemory` | Load both stores. |
+
+### Standalone Components
+
+Each layer works independently:
+
+```js
+import { Timeline, ConflictDetector, defaultPrompt } from 'hrr-memory';
+```
+
+## TypeScript
+
+Full type definitions included. All interfaces and classes are exported from `types/index.d.ts`.
+
+## Ecosystem
+
+- **[openclaw-hrr-memory](https://github.com/Joncik91/openclaw-hrr-memory)** — OpenClaw plugin for agent fact recall
+
+## Migration from hrr-memory-obs
+
+The `hrr-memory-obs` package is deprecated. All its exports are now part of `hrr-memory`:
+
+```diff
+- import { ObservationMemory } from 'hrr-memory-obs';
++ import { ObservationMemory } from 'hrr-memory';
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hrr-memory",
-  "version": "0.3.0",
+  "version": "0.3.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",