hrr-memory 0.1.1 → 0.2.0

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "hrr-memory",
-  "version": "0.1.1",
+  "version": "0.2.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"
   },
+  "types": "types/index.d.ts",
   "files": [
-    "src/"
+    "src/",
+    "types/"
   ],
   "scripts": {
-    "test": "node --test test/",
+    "test": "node --test test/memory.test.js",
     "bench": "node bench/benchmark.js"
   },
   "keywords": [

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 {
@@ -24,6 +26,22 @@ export class Bucket {
   /** 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) {
+      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;
+  }
+
   /** Serialize */
   toJSON() {
     return {

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,6 +25,12 @@ 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.
@@ -92,6 +110,44 @@ export class HRRMemory {
     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);
+      }
+      return true;
+    }
+    return false;
+  }
+
   // ── Query ──────────────────────────────────────────
 
   /**
@@ -167,11 +223,22 @@ export class HRRMemory {
   }
 
   /**
-   * Free-form query: tries subject+relation, then subject lookup, then cross-bucket search.
-   * @param {string} question
+   * 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, '').split(/\s+/);
+    const parts = question.toLowerCase().trim()
+      .replace(/[?.,!]/g, '')
+      .replace(/'s\b/g, '')     // possessive: alice's → alice
+      .replace(/-/g, '_')       // lives-in → lives_in
+      .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++) {
@@ -196,7 +263,10 @@ export class HRRMemory {
 
   // ── Stats ──────────────────────────────────────────
 
-  /** Get memory statistics */
+  /**
+   * Get memory statistics: dimensions, bucket count, total facts, RAM usage.
+   * @returns {Stats}
+   */
   stats() {
     let totalFacts = 0;
     const bucketInfo = [];
@@ -221,7 +291,10 @@ export class HRRMemory {
 
   // ── Persistence ────────────────────────────────────
 
-  /** Serialize to JSON */
+  /**
+   * 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();
@@ -230,7 +303,11 @@ export class HRRMemory {
     return { version: 3, d: this.d, symbols: this.symbols.toJSON(), buckets, routing };
   }
 
-  /** Deserialize from JSON */
+  /**
+   * 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);
@@ -244,12 +321,20 @@ export class HRRMemory {
     return mem;
   }
 
-  /** Save to a JSON file */
+  /**
+   * 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 from a JSON file (returns new empty store if file doesn't exist) */
+  /**
+   * 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/types/index.d.ts

@@ -0,0 +1,122 @@
+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;