hrr-memory 0.3.2 → 0.4.0

package/src/memory.js

@@ -1,234 +1,275 @@
-/**
- * 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();
-  }
-
-  _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);
-    this._activeBucket(subject).storeVector(association, triple);
-    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);
-      if (bucket.count === 0 && ids[i].includes('#')) {
-        this.buckets.delete(ids[i]);
-        ids.splice(i, 1);
-      }
-      return true;
-    }
-    return false;
-  }
-
-  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);
-      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]);
-    }
-    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';
+
+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); }
+  }
+}