hrr-memory 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# 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 github:Joncik91/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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "hrr-memory",
+  "version": "0.1.0",
+  "description": "Holographic Reduced Representations for structured agent memory. Zero dependencies. Complements RAG with algebraic fact queries.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "test": "node --test test/",
+    "bench": "node bench/benchmark.js"
+  },
+  "keywords": [
+    "hrr",
+    "holographic",
+    "memory",
+    "agent",
+    "ai",
+    "rag",
+    "vector",
+    "structured-memory",
+    "fact-store",
+    "llm"
+  ],
+  "author": "Jounes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joncik/hrr-memory"
+  }
+}

package/src/bucket.js

@@ -0,0 +1,45 @@
+/**
+ * Bucket — a single HRR memory vector with fixed capacity.
+ * Auto-splits are managed by HRRMemory, not by the bucket itself.
+ */
+
+export const MAX_BUCKET_SIZE = 25;
+
+export class Bucket {
+  constructor(name, d = 2048) {
+    this.name = name;
+    this.d = d;
+    this.memory = new Float32Array(d);
+    this.count = 0;
+    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 */
+  toJSON() {
+    return {
+      name: this.name,
+      memory: Array.from(this.memory),
+      count: this.count,
+      triples: this.triples,
+    };
+  }
+
+  /** Deserialize */
+  static fromJSON(data, d) {
+    const b = new Bucket(data.name, d);
+    b.memory = new Float32Array(data.memory);
+    b.count = data.count || 0;
+    b.triples = data.triples || [];
+    return b;
+  }
+}

package/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * hrr-memory — Holographic Reduced Representations for structured agent memory.
+ *
+ * Zero dependencies. Pure JS. Float32 storage. Auto-sharding.
+ *
+ * Usage:
+ *   import { HRRMemory } from 'hrr-memory';
+ *   const mem = new HRRMemory();
+ *   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"
+ */
+
+export { HRRMemory } from './memory.js';
+export { SymbolTable } from './symbols.js';
+export { Bucket } from './bucket.js';
+export { bind, unbind, similarity, randomVector, normalize } from './ops.js';

package/src/memory.js

@@ -0,0 +1,258 @@
+/**
+ * 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.
+ */
+
+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';
+
+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, ...]
+  }
+
+  // ── 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 &&
+        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;
+  }
+
+  // ── 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) {
+          bestScore = score;
+          bestName = t.object;
+          bestBucket = bucket.name;
+        }
+      }
+    }
+
+    return {
+      match: bestName,
+      score: Math.round(bestScore * 1000) / 1000,
+      confident: bestScore > 0.1,
+      bucket: bestBucket,
+    };
+  }
+
+  /**
+   * 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 = [];
+    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 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;
+    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;
+  }
+
+  /**
+   * 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
+    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 = [];
+    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,
+    };
+  }
+
+  // ── Persistence ────────────────────────────────────
+
+  /** Serialize to JSON */
+  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 };
+  }
+
+  /** Deserialize from JSON */
+  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 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'))); }
+    catch { return new HRRMemory(d); }
+  }
+}

package/src/ops.js

@@ -0,0 +1,107 @@
+/**
+ * Core HRR operations — circular convolution, correlation, similarity.
+ * All vectors are Float32Array. FFT computed in Float64 for precision.
+ */
+
+/** Generate a random unit vector of dimension d (Gaussian, normalized) */
+export function randomVector(d) {
+  const v = new Float32Array(d);
+  for (let i = 0; i < d; i += 2) {
+    const u1 = Math.random(), u2 = Math.random();
+    const r = Math.sqrt(-2 * Math.log(u1));
+    v[i] = r * Math.cos(2 * Math.PI * u2);
+    if (i + 1 < d) v[i + 1] = r * Math.sin(2 * Math.PI * u2);
+  }
+  return normalize(v);
+}
+
+/** Normalize vector to unit length */
+export function normalize(v) {
+  let norm = 0;
+  for (let i = 0; i < v.length; i++) norm += v[i] * v[i];
+  norm = Math.sqrt(norm);
+  if (norm === 0) return v;
+  const out = new Float32Array(v.length);
+  for (let i = 0; i < v.length; i++) out[i] = v[i] / norm;
+  return out;
+}
+
+/** Cosine similarity between two vectors */
+export function similarity(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i];
+  }
+  return dot / (Math.sqrt(na) * Math.sqrt(nb) + 1e-10);
+}
+
+// ── FFT (Cooley-Tukey radix-2) ──
+
+function fft(re, im, inverse) {
+  const n = re.length;
+  for (let i = 1, j = 0; i < n; i++) {
+    let bit = n >> 1;
+    for (; j & bit; bit >>= 1) j ^= bit;
+    j ^= bit;
+    if (i < j) {
+      [re[i], re[j]] = [re[j], re[i]];
+      [im[i], im[j]] = [im[j], im[i]];
+    }
+  }
+  for (let len = 2; len <= n; len <<= 1) {
+    const ang = (inverse ? -1 : 1) * 2 * Math.PI / len;
+    const wRe = Math.cos(ang), wIm = Math.sin(ang);
+    for (let i = 0; i < n; i += len) {
+      let curRe = 1, curIm = 0;
+      for (let j = 0; j < len / 2; j++) {
+        const uRe = re[i+j], uIm = im[i+j];
+        const vRe = re[i+j+len/2]*curRe - im[i+j+len/2]*curIm;
+        const vIm = re[i+j+len/2]*curIm + im[i+j+len/2]*curRe;
+        re[i+j] = uRe+vRe; im[i+j] = uIm+vIm;
+        re[i+j+len/2] = uRe-vRe; im[i+j+len/2] = uIm-vIm;
+        const nr = curRe*wRe - curIm*wIm;
+        curIm = curRe*wIm + curIm*wRe;
+        curRe = nr;
+      }
+    }
+  }
+  if (inverse) {
+    for (let i = 0; i < n; i++) { re[i] /= n; im[i] /= n; }
+  }
+}
+
+function nextPow2(n) { let p = 1; while (p < n) p <<= 1; return p; }
+
+/**
+ * Circular convolution (binding): a ⊛ b
+ * Creates an association between two vectors.
+ * Computed in Float64, returned as Float32.
+ */
+export function bind(a, b) {
+  const d = a.length, n = nextPow2(d);
+  const aR = new Float64Array(n), aI = new Float64Array(n);
+  const bR = new Float64Array(n), bI = new Float64Array(n);
+  for (let i = 0; i < d; i++) { aR[i] = a[i]; bR[i] = b[i]; }
+  fft(aR, aI, false); fft(bR, bI, false);
+  const cR = new Float64Array(n), cI = new Float64Array(n);
+  for (let i = 0; i < n; i++) {
+    cR[i] = aR[i]*bR[i] - aI[i]*bI[i];
+    cI[i] = aR[i]*bI[i] + aI[i]*bR[i];
+  }
+  fft(cR, cI, true);
+  const out = new Float32Array(d);
+  for (let i = 0; i < d; i++) out[i] = cR[i];
+  return out;
+}
+
+/**
+ * Circular correlation (unbinding): retrieve from association.
+ * unbind(key, memory) ≈ the value that was bound with key.
+ */
+export function unbind(key, memory) {
+  const d = key.length;
+  const inv = new Float32Array(d);
+  inv[0] = key[0];
+  for (let i = 1; i < d; i++) inv[i] = key[d - i];
+  return bind(inv, memory);
+}

package/src/symbols.js

@@ -0,0 +1,56 @@
+/**
+ * Shared symbol table — maps string names to random vectors.
+ * Shared across all buckets to save memory.
+ */
+
+import { randomVector, similarity } from './ops.js';
+
+export class SymbolTable {
+  constructor(d = 2048) {
+    this.d = d;
+    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 = [];
+    for (const [name, svec] of source) {
+      results.push({ name, score: similarity(vec, svec) });
+    }
+    results.sort((a, b) => b.score - a.score);
+    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)) {
+      st.symbols.set(k, new Float32Array(v));
+    }
+    return st;
+  }
+}