hrr-memory 0.1.1 → 0.3.0

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "hrr-memory",
-  "version": "0.1.1",
-  "description": "Holographic Reduced Representations for structured agent memory. Zero dependencies. Complements RAG with algebraic fact queries.",
+  "version": "0.3.0",
+  "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": {
     ".": "./src/index.js"
   },
+  "types": "types/index.d.ts",
   "files": [
-    "src/"
+    "src/",
+    "types/"
   ],
   "scripts": {
-    "test": "node --test test/",
-    "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",
@@ -36,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

@@ -3,6 +3,8 @@
  * Auto-splits are managed by HRRMemory, not by the bucket itself.
  */
 
+import { bind } from './ops.js';
+
 export const MAX_BUCKET_SIZE = 25;
 
 export class Bucket {
@@ -14,17 +16,26 @@ 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; }
 
-  /** Serialize */
+  rebuild(symbols) {
+    this.memory = new Float32Array(this.d);
+    for (const t of this.triples) {
+      const s = symbols.get(t.subject);
+      const r = symbols.get(t.relation);
+      const o = symbols.get(t.object);
+      const association = bind(bind(s, r), o);
+      for (let i = 0; i < this.d; i++) this.memory[i] += association[i];
+    }
+    this.count = this.triples.length;
+  }
+
   toJSON() {
     return {
       name: this.name,
@@ -34,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

@@ -6,6 +6,18 @@
  * 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';
@@ -13,68 +25,50 @@ 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 {
-  /**
-   * 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 &&
@@ -82,36 +76,45 @@ 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;
   }
 
-  // ── Query ──────────────────────────────────────────
+  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);
+      if (bucket.count === 0 && ids[i].includes('#')) {
+        this.buckets.delete(ids[i]);
+        ids.splice(i, 1);
+      }
+      return true;
+    }
+    return false;
+  }
 
-  /**
-   * 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) {
@@ -121,7 +124,6 @@ export class HRRMemory {
         }
       }
     }
-
     return {
       match: bestName,
       score: Math.round(bestScore * 1000) / 1000,
@@ -130,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 = [];
@@ -146,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;
@@ -166,37 +157,28 @@ export class HRRMemory {
     return results;
   }
 
-  /**
-   * Free-form query: tries subject+relation, then subject lookup, then cross-bucket search.
-   * @param {string} question
-   */
   ask(question) {
-    const parts = question.toLowerCase().trim().replace(/[?.,!]/g, '').split(/\s+/);
-
-    // Try consecutive word pairs as subject+relation
+    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] };
     }
-
-    // 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 */
   stats() {
     let totalFacts = 0;
     const bucketInfo = [];
@@ -219,9 +201,6 @@ export class HRRMemory {
     };
   }
 
-  // ── Persistence ────────────────────────────────────
-
-  /** Serialize to JSON */
   toJSON() {
     const buckets = {};
     for (const [k, v] of this.buckets) buckets[k] = v.toJSON();
@@ -230,7 +209,6 @@ export class HRRMemory {
     return { version: 3, d: this.d, symbols: this.symbols.toJSON(), buckets, routing };
   }
 
-  /** Deserialize from JSON */
   static fromJSON(data) {
     const d = data.d || 2048;
     const mem = new HRRMemory(d);
@@ -244,12 +222,10 @@ export class HRRMemory {
     return mem;
   }
 
-  /** Save to a JSON file */
   save(filePath) {
     writeFileSync(filePath, JSON.stringify(this.toJSON()));
   }
 
-  /** Load from a JSON file (returns new empty store if file doesn't exist) */
   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

@@ -0,0 +1,257 @@
+// ── Core types ───────────────────────────────────────
+
+export interface QueryResult {
+  match: string | null;
+  score: number;
+  confident: boolean;
+  bucket: string | null;
+}
+
+export interface Fact {
+  relation: string;
+  object: string;
+}
+
+export interface Triple {
+  subject: string;
+  relation: string;
+  object: string;
+}
+
+export interface DirectAskResult {
+  type: 'direct';
+  match: string;
+  score: number;
+  confident: boolean;
+  subject: string;
+  relation: string;
+  bucket: string | null;
+}
+
+export interface SubjectAskResult {
+  type: 'subject';
+  subject: string;
+  facts: Fact[];
+}
+
+export interface SearchAskResult {
+  type: 'search';
+  term: string;
+  results: Triple[];
+}
+
+export interface MissAskResult {
+  type: 'miss';
+  query: string;
+}
+
+export type AskResult = DirectAskResult | SubjectAskResult | SearchAskResult | MissAskResult;
+
+export interface BucketStats {
+  name: string;
+  facts: number;
+  full: boolean;
+}
+
+export interface Stats {
+  dimensions: number;
+  maxBucketSize: number;
+  symbols: number;
+  buckets: number;
+  subjects: number;
+  totalFacts: number;
+  ramBytes: number;
+  ramMB: number;
+  perBucket: BucketStats[];
+}
+
+export interface SerializedMemory {
+  version: number;
+  d: number;
+  symbols: Record<string, number[]>;
+  buckets: Record<string, unknown>;
+  routing: Record<string, string[]>;
+}
+
+export class HRRMemory {
+  constructor(dimensions?: number);
+
+  store(subject: string, relation: string, object: string): boolean;
+  forget(subject: string, relation: string, object: string): boolean;
+  query(subject: string, relation: string): QueryResult;
+  querySubject(subject: string): Fact[];
+  search(relation: string | null, object: string | null): Triple[];
+  ask(question: string): AskResult;
+  stats(): Stats;
+
+  save(filePath: string): void;
+  static load(filePath: string, dimensions?: number): HRRMemory;
+
+  toJSON(): SerializedMemory;
+  static fromJSON(data: SerializedMemory): HRRMemory;
+}
+
+export class SymbolTable {
+  constructor(dimensions?: number);
+  get(name: string): Float32Array;
+  has(name: string): boolean;
+  readonly size: number;
+  readonly bytes: number;
+  nearest(
+    vec: Float32Array,
+    candidates?: Map<string, Float32Array> | null,
+    topK?: number
+  ): { name: string; score: number } | { name: string; score: number }[] | null;
+  toJSON(): Record<string, number[]>;
+  static fromJSON(data: Record<string, number[]>, dimensions: number): SymbolTable;
+}
+
+export class Bucket {
+  constructor(name: string, dimensions?: number);
+  readonly name: string;
+  readonly count: number;
+  readonly isFull: boolean;
+  storeVector(association: Float32Array, triple: Triple): void;
+  rebuild(symbols: SymbolTable): void;
+  toJSON(): unknown;
+  static fromJSON(data: unknown, dimensions: number): Bucket;
+}
+
+export function bind(a: Float32Array, b: Float32Array): Float32Array;
+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;

package/README.md

@@ -1,64 +0,0 @@
-# hrr-memory
-
-**Your AI agent already has RAG. Now give it instant fact recall.**
-
-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>
-
-## Install
-
-```bash
-npm install hrr-memory
-```
-
-## 30-Second 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.save('memory.json');
-```
-
-## Why Not Just RAG?
-
-| Query | 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 |
-
-Use both. HRR for structured facts, RAG for semantic search. [See the architecture guide →](docs/architecture.md)
-
-## Performance
-
-| Facts | Accuracy | Query | RAM |
-|-------|----------|-------|-----|
-| 100 | 100% | <1ms | 0.1 MB |
-| 1,000 | 100% | 1.5ms | 4 MB |
-| 10,000 | 100% | 1.8ms | 86 MB |
-
-## Documentation
-
-- **[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
-
-## License
-
-MIT