hrr-memory 0.2.0 → 0.3.1

package/README.md

@@ -1,12 +1,8 @@
 # hrr-memory
 
-**Your AI agent already has RAG. Now give it instant fact recall.**
+**Structured fact recall for AI agents. Sub-2ms queries, zero dependencies.**
 
-hrr-memory stores structured facts as `(subject, relation, object)` triples and retrieves them in under 2 milliseconds — no vector database, no embeddings API, no dependencies. It complements RAG, not replaces it.
-
-<p align="center">
-  <img src="assets/hrr-diagram.svg" alt="How HRR Memory Works" width="800" />
-</p>
+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
 
@@ -14,7 +10,7 @@ hrr-memory stores structured facts as `(subject, relation, object)` triples and
 npm install hrr-memory
 ```
 
-## 30-Second Demo
+## Quick Demo
 
 ```js
 import { HRRMemory } from 'hrr-memory';
@@ -25,39 +21,158 @@ 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.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' }]
+// [{ 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 | RAG | hrr-memory |
-|-------|-----|------------|
+| Query type | RAG | hrr-memory |
+|---|---|---|
 | "What is Alice's timezone?" | Returns paragraphs, maybe | Returns `cet` in <1ms |
-| "Find notes about deployment" | Ranked chunks | Can't — not a triple |
+| "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' } }]
+```
 
-Use both. HRR for structured facts, RAG for semantic search. [See the architecture guide →](docs/architecture.md)
+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 | RAM |
-|-------|----------|-------|-----|
+| 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 |
 
-## Documentation
+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
 
-- **[Getting Started](docs/getting-started.md)** — installation, first facts, persistence
-- **[API Reference](docs/api.md)** — every method, parameter, and return type
-- **[Architecture](docs/architecture.md)** — how HRR works, auto-sharding, RAG integration
-- **[Performance](docs/performance.md)** — benchmarks, scaling limits, tuning
+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
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hrr-memory",
-  "version": "0.2.0",
-  "description": "Holographic Reduced Representations for structured agent memory. Zero dependencies. Complements RAG with algebraic fact queries.",
+  "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",
   "exports": {
@@ -13,8 +13,9 @@
     "types/"
   ],
   "scripts": {
-    "test": "node --test test/memory.test.js",
-    "bench": "node bench/benchmark.js"
+    "test": "node --test test/memory.test.js test/timeline.test.js test/conflict.test.js test/prompt.test.js test/integration.test.js",
+    "bench": "node bench/benchmark.js",
+    "bench:obs": "node bench/benchmark-obs.js"
   },
   "keywords": [
     "hrr",
@@ -38,7 +39,13 @@
     "associative-memory",
     "semantic-memory",
     "ai-agent",
-    "no-dependencies"
+    "no-dependencies",
+    "observation",
+    "belief-tracking",
+    "temporal",
+    "conflict-detection",
+    "timeline",
+    "knowledge-evolution"
   ],
   "author": "Jounes",
   "license": "MIT",

package/src/bucket.js

@@ -16,20 +16,14 @@ export class Bucket {
     this.triples = [];
   }
 
-  /** Add a pre-computed association vector */
   storeVector(association, triple) {
     for (let i = 0; i < this.d; i++) this.memory[i] += association[i];
     this.count++;
     this.triples.push(triple);
   }
 
-  /** Whether the bucket has reached max capacity */
   get isFull() { return this.count >= MAX_BUCKET_SIZE; }
 
-  /**
-   * Rebuild the memory vector from remaining triples.
-   * Called after removing a triple — can't subtract cleanly due to superposition noise.
-   */
   rebuild(symbols) {
     this.memory = new Float32Array(this.d);
     for (const t of this.triples) {
@@ -42,7 +36,6 @@ export class Bucket {
     this.count = this.triples.length;
   }
 
-  /** Serialize */
   toJSON() {
     return {
       name: this.name,
@@ -52,7 +45,6 @@ export class Bucket {
     };
   }
 
-  /** Deserialize */
   static fromJSON(data, d) {
     const b = new Bucket(data.name, d);
     b.memory = new Float32Array(data.memory);

package/src/conflict.js

@@ -0,0 +1,50 @@
+/**
+ * ConflictDetector — algebraic conflict detection using HRR symbol vectors.
+ *
+ * @typedef {{ ts: number, subject: string, relation: string, newObject: string, oldObject: string, similarity: number }} ConflictFlag
+ */
+
+import { similarity } from './ops.js';
+
+export class ConflictDetector {
+  constructor(hrr, threshold = 0.3) {
+    this._hrr = hrr;
+    this._threshold = threshold;
+    this._knownPairs = new Set(); // track subject+relation pairs we've seen
+  }
+
+  /**
+   * Record that a (subject, relation) pair has been stored.
+   * Call this after a successful store so future checks know to run the query.
+   */
+  track(subject, relation) {
+    this._knownPairs.add(`${subject}\0${relation}`);
+  }
+
+  check(subject, relation, object, ts) {
+    const s = subject.toLowerCase().trim();
+    const r = relation.toLowerCase().trim();
+
+    // Fast path: if we've never stored this pair, no conflict possible.
+    // Skip the expensive HRR query entirely.
+    if (!this._knownPairs.has(`${s}\0${r}`)) return null;
+
+    const existing = this._hrr.query(subject, relation);
+    if (!existing.confident) return null;
+
+    const oldVec = this._hrr.symbols.get(existing.match);
+    const newVec = this._hrr.symbols.get(object.toLowerCase().trim());
+    const sim = similarity(oldVec, newVec);
+
+    if (sim >= this._threshold) return null;
+
+    return {
+      ts: ts ?? Date.now(),
+      subject: subject.toLowerCase().trim(),
+      relation: relation.toLowerCase().trim(),
+      newObject: object.toLowerCase().trim(),
+      oldObject: existing.match,
+      similarity: Math.round(sim * 1000) / 1000,
+    };
+  }
+}

package/src/index.js

@@ -2,17 +2,24 @@
  * hrr-memory — Holographic Reduced Representations for structured agent memory.
  *
  * Zero dependencies. Pure JS. Float32 storage. Auto-sharding.
+ * Includes observation layer: temporal awareness, conflict detection, belief synthesis.
  *
  * Usage:
- *   import { HRRMemory } from 'hrr-memory';
- *   const mem = new HRRMemory();
- *   mem.store('alice', 'lives_in', 'paris');
+ *   import { HRRMemory, ObservationMemory } from 'hrr-memory';
+ *   const hrr = new HRRMemory();
+ *   const mem = new ObservationMemory(hrr);
+ *   await mem.store('alice', 'lives_in', 'paris');
  *   mem.query('alice', 'lives_in'); // → { match: 'paris', score: 0.3, confident: true }
- *
- * Based on Plate (1994): "Distributed Representations and Nested Compositional Structure"
  */
 
+// Core
 export { HRRMemory } from './memory.js';
 export { SymbolTable } from './symbols.js';
 export { Bucket } from './bucket.js';
 export { bind, unbind, similarity, randomVector, normalize } from './ops.js';
+
+// Observation layer
+export { ObservationMemory, ObservationParseError } from './observation.js';
+export { Timeline, SymbolicProxy } from './timeline.js';
+export { ConflictDetector } from './conflict.js';
+export { defaultPrompt } from './prompt.js';

package/src/memory.js

@@ -32,67 +32,43 @@ const STOP_WORDS = new Set([
 ]);
 
 export class HRRMemory {
-  /**
-   * Create a new HRR memory store.
-   * @param {number} d - Vector dimensions (default 2048). Higher = more capacity per bucket.
-   */
   constructor(d = 2048) {
     this.d = d;
     this.symbols = new SymbolTable(d);
     this.buckets = new Map();
-    this.routing = new Map();  // subject → [bucket_id, ...]
+    this.routing = new Map();
   }
 
-  // ── Bucket management ──────────────────────────────
-
-  /** Get the active (non-full) bucket for a subject, splitting if needed */
   _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;
-
-      // Overflow: create new bucket
       const newId = key + '#' + ids.length;
       const nb = new Bucket(newId, this.d);
       this.buckets.set(newId, nb);
       ids.push(newId);
       return nb;
     }
-
-    // First bucket for this subject
     const b = new Bucket(key, this.d);
     this.buckets.set(key, b);
     this.routing.set(key, [key]);
     return b;
   }
 
-  /** Get all buckets for a subject */
   _subjectBuckets(subject) {
     const ids = this.routing.get(subject.toLowerCase().trim()) || [];
     return ids.map(id => this.buckets.get(id)).filter(Boolean);
   }
 
-  // ── Store ──────────────────────────────────────────
-
-  /**
-   * Store a fact as a (subject, relation, object) triple.
-   * @param {string} subject - The entity (e.g., 'alice')
-   * @param {string} relation - The attribute (e.g., 'lives_in')
-   * @param {string} object - The value (e.g., 'paris')
-   * @returns {boolean} true if stored, false if duplicate
-   */
   store(subject, relation, object) {
     const triple = {
       subject: subject.toLowerCase().trim(),
       relation: relation.toLowerCase().trim(),
       object: object.toLowerCase().trim(),
     };
-
-    // Dedup across all subject buckets
     for (const b of this._subjectBuckets(subject)) {
       if (b.triples.some(t =>
         t.subject === triple.subject &&
@@ -100,45 +76,28 @@ export class HRRMemory {
         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);
-
     this._activeBucket(subject).storeVector(association, triple);
     return true;
   }
 
-  // ── Forget ─────────────────────────────────────────
-
-  /**
-   * Remove a fact from memory.
-   * Rebuilds the affected bucket's memory vector from remaining triples.
-   * @param {string} subject
-   * @param {string} relation
-   * @param {string} object
-   * @returns {boolean} true if found and removed, false if not found
-   */
   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);
-
-      // Clean up empty overflow buckets
       if (bucket.count === 0 && ids[i].includes('#')) {
         this.buckets.delete(ids[i]);
         ids.splice(i, 1);
@@ -148,26 +107,14 @@ export class HRRMemory {
     return false;
   }
 
-  // ── Query ──────────────────────────────────────────
-
-  /**
-   * Query: given subject and relation, retrieve the object.
-   * @param {string} subject
-   * @param {string} relation
-   * @returns {{ match: string|null, score: number, confident: boolean, bucket: string|null }}
-   */
   query(subject, relation) {
     const buckets = this._subjectBuckets(subject);
     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);
-
-      // Optimized: only scan object symbols in this bucket
       for (const t of bucket.triples) {
         const score = similarity(result, this.symbols.get(t.object));
         if (score > bestScore) {
@@ -177,7 +124,6 @@ export class HRRMemory {
         }
       }
     }
-
     return {
       match: bestName,
       score: Math.round(bestScore * 1000) / 1000,
@@ -186,11 +132,6 @@ export class HRRMemory {
     };
   }
 
-  /**
-   * Get all known facts about a subject (symbolic, exact).
-   * @param {string} subject
-   * @returns {Array<{ relation: string, object: string }>}
-   */
   querySubject(subject) {
     const key = subject.toLowerCase().trim();
     const facts = [];
@@ -202,12 +143,6 @@ export class HRRMemory {
     return facts;
   }
 
-  /**
-   * Search across all buckets for triples matching a relation and/or object.
-   * @param {string|null} relation - Filter by relation (null = any)
-   * @param {string|null} object - Filter by object value (null = any)
-   * @returns {Array<{ subject: string, relation: string, object: string }>}
-   */
   search(relation, object) {
     const results = [];
     const rel = relation ? relation.toLowerCase().trim() : null;
@@ -222,51 +157,28 @@ export class HRRMemory {
     return results;
   }
 
-  /**
-   * Free-form query: strips stop words and possessives, then tries subject+relation pairs,
-   * subject lookup, and cross-bucket search in that order.
-   * @param {string} question - Natural language question (e.g., "What is alice's timezone?")
-   * @returns {AskResult} One of: DirectAskResult, SubjectAskResult, SearchAskResult, or MissAskResult
-   * @example
-   * mem.store('alice', 'timezone', 'cet');
-   * mem.ask("What is alice's timezone?"); // → { type: 'direct', match: 'cet', ... }
-   * mem.ask('alice');                      // → { type: 'subject', facts: [...] }
-   */
   ask(question) {
     const parts = question.toLowerCase().trim()
       .replace(/[?.,!]/g, '')
-      .replace(/'s\b/g, '')     // possessive: alice's → alice
-      .replace(/-/g, '_')       // lives-in → lives_in
+      .replace(/'s\b/g, '')
+      .replace(/-/g, '_')
       .split(/\s+/)
       .filter(w => !STOP_WORDS.has(w) && w.length > 0);
-
-    // Try consecutive word pairs as subject+relation
     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] };
     }
-
-    // Try each word as a subject
     for (const word of parts) {
       const facts = this.querySubject(word);
       if (facts.length > 0) return { type: 'subject', subject: word, facts };
     }
-
-    // Search across all buckets for any matching object
     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 ──────────────────────────────────────────
-
-  /**
-   * Get memory statistics: dimensions, bucket count, total facts, RAM usage.
-   * @returns {Stats}
-   */
   stats() {
     let totalFacts = 0;
     const bucketInfo = [];
@@ -289,12 +201,6 @@ export class HRRMemory {
     };
   }
 
-  // ── Persistence ────────────────────────────────────
-
-  /**
-   * Serialize the entire memory store to a plain object.
-   * @returns {{ version: number, d: number, symbols: object, buckets: object, routing: object }}
-   */
   toJSON() {
     const buckets = {};
     for (const [k, v] of this.buckets) buckets[k] = v.toJSON();
@@ -303,11 +209,6 @@ export class HRRMemory {
     return { version: 3, d: this.d, symbols: this.symbols.toJSON(), buckets, routing };
   }
 
-  /**
-   * Deserialize from a plain object (as produced by toJSON).
-   * @param {object} data - Serialized memory data
-   * @returns {HRRMemory}
-   */
   static fromJSON(data) {
     const d = data.d || 2048;
     const mem = new HRRMemory(d);
@@ -321,20 +222,10 @@ export class HRRMemory {
     return mem;
   }
 
-  /**
-   * Save the memory store to a JSON file.
-   * @param {string} filePath - Path to write the JSON file
-   */
   save(filePath) {
     writeFileSync(filePath, JSON.stringify(this.toJSON()));
   }
 
-  /**
-   * Load a memory store from a JSON file. Returns a new empty store if the file doesn't exist.
-   * @param {string} filePath - Path to the JSON file
-   * @param {number} [d=2048] - Vector dimensions (used only if creating new store)
-   * @returns {HRRMemory}
-   */
   static load(filePath, d = 2048) {
     if (!existsSync(filePath)) return new HRRMemory(d);
     try { return HRRMemory.fromJSON(JSON.parse(readFileSync(filePath, 'utf8'))); }

package/src/observation.js

@@ -0,0 +1,284 @@
+/**
+ * ObservationMemory — composition wrapper around HRRMemory.
+ *
+ * Adds timeline recording, conflict detection, and observation consolidation
+ * on top of HRRMemory's triple store.
+ *
+ * @typedef {{ id: string, subject: string, observation: string, evidence: Array<{ ts: number, triple: [string, string, string] }>, confidence: 'high' | 'medium' | 'low', supersedes: string[], createdAt: number }} Observation
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { HRRMemory } from './memory.js';
+import { Timeline } from './timeline.js';
+import { ConflictDetector } from './conflict.js';
+import { defaultPrompt } from './prompt.js';
+
+export class ObservationParseError extends Error {
+  constructor(message, raw) {
+    super(message);
+    this.name = 'ObservationParseError';
+    this.raw = raw;
+  }
+}
+
+export class ObservationMemory {
+  constructor(hrr, options = {}) {
+    this._hrr = hrr;
+    this._executor = options.executor || null;
+    this._autoConsolidateAfter = options.autoConsolidateAfter ?? null;
+    this._promptFn = options.promptFn || defaultPrompt;
+    this._timeline = new Timeline();
+    this._conflict = new ConflictDetector(hrr, options.conflictThreshold ?? 0.3);
+    this._flags = [];
+    this._observations = [];
+    this._obsCounter = 0;
+    this._consolidating = false;
+    this._meta = {
+      createdAt: Date.now(),
+      lastConsolidation: null,
+      totalStores: 0,
+      totalForgets: 0,
+      totalConsolidations: 0,
+    };
+  }
+
+  // ── Delegated methods ──────────────────────────────
+
+  query(subject, relation) { return this._hrr.query(subject, relation); }
+  querySubject(subject) { return this._hrr.querySubject(subject); }
+  search(relation, object) { return this._hrr.search(relation, object); }
+  ask(question) { return this._hrr.ask(question); }
+  stats() { return this._hrr.stats(); }
+
+  // ── Store (async) ──────────────────────────────────
+
+  async store(subject, relation, object) {
+    const ts = Date.now();
+    const s = subject.toLowerCase().trim();
+    const r = relation.toLowerCase().trim();
+    const o = object.toLowerCase().trim();
+
+    // Check for conflict BEFORE storing (so query sees old state)
+    const flag = this._conflict.check(s, r, o, ts);
+
+    // Delegate to HRR
+    const stored = this._hrr.store(subject, relation, object);
+
+    // Only record timeline entry if actually stored (not a duplicate)
+    if (stored) {
+      const entry = { ts, subject: s, relation: r, object: o, op: 'store' };
+      if (flag) {
+        entry.conflict = { oldObject: flag.oldObject, similarity: flag.similarity };
+        this._flags.push(flag);
+      }
+      this._timeline.append(entry);
+      this._meta.totalStores++;
+
+      // Track this pair so future stores trigger conflict checks
+      this._conflict.track(s, r);
+
+      // Auto-consolidation
+      if (this._autoConsolidateAfter && this._flags.length >= this._autoConsolidateAfter) {
+        await this.consolidate();
+      }
+    }
+
+    return stored;
+  }
+
+  // ── Forget (async) ─────────────────────────────────
+
+  async forget(subject, relation, object) {
+    const ts = Date.now();
+    const s = subject.toLowerCase().trim();
+    const r = relation.toLowerCase().trim();
+    const o = object.toLowerCase().trim();
+
+    const forgotten = this._hrr.forget(subject, relation, object);
+
+    if (forgotten) {
+      this._timeline.append({ ts, subject: s, relation: r, object: o, op: 'forget' });
+      this._meta.totalForgets++;
+    }
+
+    return forgotten;
+  }
+
+  // ── Timeline ───────────────────────────────────────
+
+  history(subject, relation) { return this._timeline.history(subject, relation); }
+  at(ts) { return this._timeline.at(ts); }
+
+  // ── Flags ──────────────────────────────────────────
+
+  flags() { return [...this._flags]; }
+
+  // ── Observations ───────────────────────────────────
+
+  observations(subject) {
+    let obs = [...this._observations];
+    if (subject) {
+      obs = obs.filter(o => o.subject === subject.toLowerCase().trim());
+    }
+    return obs.sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  /**
+   * Add an observation directly (without calling an LLM).
+   * Use this when an external agent has already synthesized the observation.
+   * @param {{ subject: string, observation: string, evidence: Array<{ ts: number, triple: [string, string, string] }>, confidence: 'high' | 'medium' | 'low', supersedes?: string[] }} obs
+   * @returns {Observation}
+   */
+  addObservation({ subject, observation, evidence, confidence, supersedes = [] }) {
+    const obs = {
+      id: `obs_${String(++this._obsCounter).padStart(3, '0')}`,
+      subject: subject.toLowerCase().trim(),
+      observation,
+      evidence,
+      confidence,
+      supersedes,
+      createdAt: Date.now(),
+    };
+    this._observations.push(obs);
+    return obs;
+  }
+
+  /**
+   * Clear conflict flags for a specific subject.
+   * @param {string} subject
+   */
+  clearFlags(subject) {
+    const s = subject.toLowerCase().trim();
+    this._flags = this._flags.filter(f => f.subject !== s);
+  }
+
+  async consolidate() {
+    if (!this._executor) {
+      throw new Error('No executor configured. Pass executor in ObservationMemory options.');
+    }
+    if (this._flags.length === 0) return [];
+    if (this._consolidating) return [];
+
+    this._consolidating = true;
+    try {
+      // Gather timeline entries for flagged subjects
+      const subjects = new Set(this._flags.map(f => f.subject));
+      const entries = [];
+      for (const s of subjects) {
+        entries.push(...this._timeline.history(s));
+      }
+
+      // Gather existing observations for flagged subjects
+      const existingObservations = this._observations
+        .filter(o => subjects.has(o.subject))
+        .map(o => ({ id: o.id, subject: o.subject, observation: o.observation, confidence: o.confidence }));
+
+      // Build prompt
+      const input = { entries, flags: [...this._flags], existingObservations };
+      const prompt = this._promptFn(input);
+
+      // Call LLM
+      const raw = await this._executor(prompt);
+
+      // Parse response
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        throw new ObservationParseError('Executor returned invalid JSON', raw);
+      }
+
+      if (!parsed.observations || !Array.isArray(parsed.observations)) {
+        throw new ObservationParseError('Response missing "observations" array', raw);
+      }
+
+      // Validate and store observations
+      const allTimestamps = new Set(this._timeline.all().map(e => e.ts));
+      const allObsIds = new Set(this._observations.map(o => o.id));
+      const newObs = [];
+
+      for (const raw of parsed.observations) {
+        // Require fields
+        if (!raw.subject || !raw.observation || !raw.evidence || !raw.confidence) continue;
+
+        // Filter evidence to valid timestamps
+        const validEvidence = (Array.isArray(raw.evidence) ? raw.evidence : [])
+          .filter(e => e.ts && allTimestamps.has(e.ts) && Array.isArray(e.triple));
+
+        if (validEvidence.length === 0) continue;
+
+        // Filter supersedes to valid IDs
+        const validSupersedes = (Array.isArray(raw.supersedes) ? raw.supersedes : [])
+          .filter(id => allObsIds.has(id));
+
+        const obs = {
+          id: `obs_${String(++this._obsCounter).padStart(3, '0')}`,
+          subject: raw.subject,
+          observation: raw.observation,
+          evidence: validEvidence,
+          confidence: raw.confidence,
+          supersedes: validSupersedes,
+          createdAt: Date.now(),
+        };
+
+        this._observations.push(obs);
+        allObsIds.add(obs.id);
+        newObs.push(obs);
+      }
+
+      // Clear flags
+      this._flags = [];
+      this._meta.lastConsolidation = Date.now();
+      this._meta.totalConsolidations++;
+
+      return newObs;
+    } finally {
+      this._consolidating = false;
+    }
+  }
+
+  // ── Persistence ────────────────────────────────────
+
+  toJSON() {
+    return {
+      version: 1,
+      meta: { ...this._meta },
+      timeline: this._timeline.toJSON(),
+      observations: this._observations.map(o => ({ ...o })),
+      flags: this._flags.map(f => ({ ...f })),
+      obsCounter: this._obsCounter,
+    };
+  }
+
+  static fromJSON(hrr, data, options = {}) {
+    const mem = new ObservationMemory(hrr, options);
+    if (data.meta) mem._meta = { ...data.meta };
+    if (data.timeline) mem._timeline = Timeline.fromJSON(data.timeline);
+    if (data.observations) mem._observations = data.observations.map(o => ({ ...o }));
+    if (data.flags) mem._flags = data.flags.map(f => ({ ...f }));
+    if (typeof data.obsCounter === 'number') mem._obsCounter = data.obsCounter;
+    // Rebuild known pairs from timeline so conflict detection works after load
+    if (data.timeline) {
+      for (const e of data.timeline) {
+        if (e.op === 'store') mem._conflict.track(e.subject, e.relation);
+      }
+    }
+    return mem;
+  }
+
+  save(hrrPath, obsPath) {
+    this._hrr.save(hrrPath);
+    writeFileSync(obsPath, JSON.stringify(this.toJSON(), null, 2));
+  }
+
+  static load(hrrPath, obsPath, options = {}) {
+    const hrr = HRRMemory.load(hrrPath);
+    if (!existsSync(obsPath)) return new ObservationMemory(hrr, options);
+    try {
+      const data = JSON.parse(readFileSync(obsPath, 'utf8'));
+      return ObservationMemory.fromJSON(hrr, data, options);
+    } catch {
+      return new ObservationMemory(hrr, options);
+    }
+  }
+}

package/src/prompt.js

@@ -0,0 +1,59 @@
+/**
+ * defaultPrompt — builds a consolidation prompt for LLM-driven observation synthesis.
+ *
+ * @typedef {{ entries: Array, flags: Array, existingObservations: Array<{ id: string, subject: string, observation: string, confidence: string }> }} ConsolidationInput
+ */
+
+export function defaultPrompt(input) {
+  const { entries, flags, existingObservations } = input;
+
+  const timelineSection = entries
+    .sort((a, b) => a.ts - b.ts)
+    .map(e => {
+      const date = new Date(e.ts).toISOString().split('T')[0];
+      let line = `[${date}] ${e.op.toUpperCase()} (${e.subject}, ${e.relation}, ${e.object})`;
+      if (e.conflict) {
+        line += ` ⚡ CONFLICT with '${e.conflict.oldObject}' (sim: ${e.conflict.similarity})`;
+      }
+      return line;
+    })
+    .join('\n');
+
+  let existingSection = '';
+  if (existingObservations.length > 0) {
+    existingSection = `\n\nExisting observations (use "supersedes" to indicate if a new observation replaces one of these):\n` +
+      existingObservations.map(o => `- [${o.id}] (${o.subject}, ${o.confidence}): ${o.observation}`).join('\n');
+  }
+
+  return `You are analyzing changes in an agent's structured memory (a triple store of subject-relation-object facts).
+
+The following facts were stored or forgotten over time. Entries marked with ⚡ CONFLICT indicate that a new value was stored for a relation that already had a different value.
+
+Timeline:
+${timelineSection}
+${existingSection}
+
+Your task: Synthesize observations about what has changed in this agent's knowledge.
+
+Rules:
+- Distinguish between "shifted from X to Y" (a belief change) and "added Y alongside X" (accumulation). Look at the full timeline context for each subject+relation pair to judge which case applies.
+- Each observation should be 1-2 concise sentences.
+- Set confidence to "high" if the pattern is clear across multiple entries, "medium" for a single conflict, "low" if ambiguous.
+- Use "supersedes" to reference IDs of existing observations that this new observation revises. Use an empty array if this is a new observation.
+- Evidence must reference actual timestamps from the timeline above.
+
+Respond with ONLY valid JSON (no markdown fencing, no preamble):
+{
+  "observations": [
+    {
+      "subject": "the primary subject",
+      "observation": "concise synthesis of the change",
+      "evidence": [
+        { "ts": 100, "triple": ["subject", "relation", "object"] }
+      ],
+      "confidence": "high",
+      "supersedes": []
+    }
+  ]
+}`;
+}

package/src/symbols.js

@@ -11,23 +11,18 @@ export class SymbolTable {
     this.symbols = new Map();
   }
 
-  /** Get or create a vector for a symbol name */
   get(name) {
     const key = name.toLowerCase().trim();
     if (!this.symbols.has(key)) this.symbols.set(key, randomVector(this.d));
     return this.symbols.get(key);
   }
 
-  /** Check if a symbol exists */
   has(name) { return this.symbols.has(name.toLowerCase().trim()); }
 
-  /** Number of symbols */
   get size() { return this.symbols.size; }
 
-  /** Memory footprint in bytes */
   get bytes() { return this.symbols.size * this.d * 4; }
 
-  /** Find the nearest symbol(s) to a result vector */
   nearest(vec, candidates = null, topK = 1) {
     const source = candidates || this.symbols;
     const results = [];
@@ -38,14 +33,12 @@ export class SymbolTable {
     return topK === 1 ? results[0] || null : results.slice(0, topK);
   }
 
-  /** Serialize to plain object */
   toJSON() {
     const out = {};
     for (const [k, v] of this.symbols) out[k] = Array.from(v);
     return out;
   }
 
-  /** Deserialize from plain object */
   static fromJSON(data, d) {
     const st = new SymbolTable(d);
     for (const [k, v] of Object.entries(data)) {

package/src/timeline.js

@@ -0,0 +1,71 @@
+/**
+ * Timeline — append-only event log for HRR memory operations.
+ *
+ * @typedef {{ ts: number, subject: string, relation: string, object: string, op: 'store' | 'forget', conflict?: { oldObject: string, similarity: number } }} TimelineEntry
+ */
+
+export class Timeline {
+  constructor() {
+    /** @type {TimelineEntry[]} */
+    this._entries = [];
+  }
+
+  append(entry) {
+    this._entries.push({ ...entry });
+  }
+
+  history(subject, relation) {
+    let results = this._entries.filter(e => e.subject === subject);
+    if (relation !== undefined) {
+      results = results.filter(e => e.relation === relation);
+    }
+    return results.sort((a, b) => a.ts - b.ts);
+  }
+
+  all() {
+    return [...this._entries].sort((a, b) => a.ts - b.ts);
+  }
+
+  get length() {
+    return this._entries.length;
+  }
+
+  at(ts) {
+    return new SymbolicProxy(this._entries, ts);
+  }
+
+  toJSON() {
+    return this._entries.map(e => ({ ...e }));
+  }
+
+  static fromJSON(data) {
+    const tl = new Timeline();
+    for (const entry of data) {
+      tl._entries.push({ ...entry });
+    }
+    return tl;
+  }
+}
+
+export class SymbolicProxy {
+  constructor(entries, ts) {
+    this._entries = entries;
+    this._ts = ts;
+  }
+
+  facts(subject, relation) {
+    const relevant = this._entries
+      .filter(e => e.ts <= this._ts && e.subject === subject
+        && (relation === undefined || e.relation === relation))
+      .sort((a, b) => a.ts - b.ts);
+
+    // Use Map<relation\0object, object> to handle colons in values
+    const live = new Map();
+    for (const e of relevant) {
+      const key = `${e.relation}\0${e.object}`;
+      if (e.op === 'store') live.set(key, e.object);
+      else if (e.op === 'forget') live.delete(key);
+    }
+    return [...live.values()];
+  }
+}

package/types/index.d.ts

@@ -1,3 +1,5 @@
+// ── Core types ───────────────────────────────────────
+
 export interface QueryResult {
   match: string | null;
   score: number;
@@ -120,3 +122,136 @@ export function unbind(key: Float32Array, memory: Float32Array): Float32Array;
 export function similarity(a: Float32Array, b: Float32Array): number;
 export function randomVector(dimensions: number): Float32Array;
 export function normalize(v: Float32Array): Float32Array;
+
+// ── Observation layer types ───��──────────────────────
+
+export interface TimelineEntry {
+  ts: number;
+  subject: string;
+  relation: string;
+  object: string;
+  op: 'store' | 'forget';
+  conflict?: { oldObject: string; similarity: number };
+}
+
+export interface ConflictFlag {
+  ts: number;
+  subject: string;
+  relation: string;
+  newObject: string;
+  oldObject: string;
+  similarity: number;
+}
+
+export interface Observation {
+  id: string;
+  subject: string;
+  observation: string;
+  evidence: Array<{ ts: number; triple: [string, string, string] }>;
+  confidence: 'high' | 'medium' | 'low';
+  supersedes: string[];
+  createdAt: number;
+}
+
+export interface ConsolidationInput {
+  entries: TimelineEntry[];
+  flags: ConflictFlag[];
+  existingObservations: Array<{
+    id: string;
+    subject: string;
+    observation: string;
+    confidence: string;
+  }>;
+}
+
+export interface ObservationMemoryOptions {
+  executor?: (prompt: string) => Promise<string>;
+  autoConsolidateAfter?: number | null;
+  promptFn?: (input: ConsolidationInput) => string;
+  conflictThreshold?: number;
+}
+
+export interface SerializedObservationMemory {
+  version: number;
+  meta: {
+    createdAt: number;
+    lastConsolidation: number | null;
+    totalStores: number;
+    totalForgets: number;
+    totalConsolidations: number;
+  };
+  timeline: TimelineEntry[];
+  observations: Observation[];
+  flags: ConflictFlag[];
+  obsCounter: number;
+}
+
+export class Timeline {
+  constructor();
+  append(entry: TimelineEntry): void;
+  history(subject: string, relation?: string): TimelineEntry[];
+  all(): TimelineEntry[];
+  readonly length: number;
+  at(ts: number): SymbolicProxy;
+  toJSON(): TimelineEntry[];
+  static fromJSON(data: TimelineEntry[]): Timeline;
+}
+
+export class SymbolicProxy {
+  constructor(entries: TimelineEntry[], ts: number);
+  facts(subject: string, relation?: string): string[];
+}
+
+export class ConflictDetector {
+  constructor(hrr: HRRMemory, threshold?: number);
+  track(subject: string, relation: string): void;
+  check(subject: string, relation: string, object: string, ts?: number): ConflictFlag | null;
+}
+
+export class ObservationParseError extends Error {
+  constructor(message: string, raw: string);
+  readonly name: 'ObservationParseError';
+  readonly raw: string;
+}
+
+export class ObservationMemory {
+  constructor(hrr: HRRMemory, options?: ObservationMemoryOptions);
+
+  // Delegated to HRRMemory
+  query(subject: string, relation: string): QueryResult;
+  querySubject(subject: string): Fact[];
+  search(relation: string | null, object: string | null): Triple[];
+  ask(question: string): AskResult;
+  stats(): Stats;
+
+  // Store/forget with observation tracking
+  store(subject: string, relation: string, object: string): Promise<boolean>;
+  forget(subject: string, relation: string, object: string): Promise<boolean>;
+
+  // Timeline
+  history(subject: string, relation?: string): TimelineEntry[];
+  at(ts: number): SymbolicProxy;
+
+  // Conflict flags
+  flags(): ConflictFlag[];
+  clearFlags(subject: string): void;
+
+  // Observations
+  observations(subject?: string): Observation[];
+  addObservation(obs: {
+    subject: string;
+    observation: string;
+    evidence: Array<{ ts: number; triple: [string, string, string] }>;
+    confidence: 'high' | 'medium' | 'low';
+    supersedes?: string[];
+  }): Observation;
+  consolidate(): Promise<Observation[]>;
+
+  // Persistence
+  save(hrrPath: string, obsPath: string): void;
+  static load(hrrPath: string, obsPath: string, options?: ObservationMemoryOptions): ObservationMemory;
+  toJSON(): SerializedObservationMemory;
+  static fromJSON(hrr: HRRMemory, data: SerializedObservationMemory, options?: ObservationMemoryOptions): ObservationMemory;
+}
+
+export function defaultPrompt(input: ConsolidationInput): string;