feat(memory): FactStore — in-memory fact-graph keyed by scope/subject/predicate

Author: jddunn

src/memory/retrieval/fact-graph/FactStore.ts

@@ -0,0 +1,102 @@
+/**
+ * @file FactStore.ts
+ * @description In-memory `(scope, scopeId, subjectHash, predicateHash) →
+ * FactStoreEntry` map. Populated at session-ingest time by
+ * `FactExtractor`; queried from `HybridRetriever` at query time.
+ *
+ * The store is per-case-scoped (no cross-run persistence in MVP); callers
+ * that want persistent fact storage wire a SQLite-backed variant on top
+ * of the same interface in a follow-up.
+ *
+ * @module agentos/memory/retrieval/fact-graph/FactStore
+ */
+
+import type { Fact, FactStoreEntry } from './types.js';
+import {
+  canonicalizeSubject,
+  hashPredicate,
+  hashSubject,
+  isValidPredicate,
+} from './canonicalization.js';
+
+export class FactStore {
+  private readonly map = new Map<string, FactStoreEntry>();
+
+  private keyOf(
+    scope: string,
+    scopeId: string,
+    subjectHash: string,
+    predicateHash: string,
+  ): string {
+    return `${scope}|${scopeId}|${subjectHash}|${predicateHash}`;
+  }
+
+  /**
+   * Insert facts. Facts with predicates outside the closed schema are
+   * silently dropped (matches the `FactExtractor` contract). Subjects
+   * are canonicalized; the stored form carries the canonical subject.
+   * Per-(subject, predicate) entries stay time-sorted ascending so
+   * {@link getLatest} is O(1) and {@link getAllTimeOrdered} is O(n).
+   */
+  upsert(scope: string, scopeId: string, facts: readonly Fact[]): void {
+    for (const raw of facts) {
+      if (!isValidPredicate(raw.predicate)) continue;
+      const subject = canonicalizeSubject(raw.subject);
+      const fact: Fact = { ...raw, subject };
+      const key = this.keyOf(
+        scope,
+        scopeId,
+        hashSubject(subject),
+        hashPredicate(fact.predicate),
+      );
+      let entry = this.map.get(key);
+      if (!entry) {
+        entry = { facts: [] };
+        this.map.set(key, entry);
+      }
+      entry.facts.push(fact);
+      entry.facts.sort((a, b) => a.timestamp - b.timestamp);
+    }
+  }
+
+  /**
+   * Return the latest fact for (subject, predicate) or null. Supports
+   * un-canonicalized subject input (canonicalized internally). Returns
+   * null for predicates outside the closed schema.
+   */
+  getLatest(
+    scope: string,
+    scopeId: string,
+    subject: string,
+    predicate: string,
+  ): Fact | null {
+    if (!isValidPredicate(predicate)) return null;
+    const canonicalSubject = canonicalizeSubject(subject);
+    const key = this.keyOf(
+      scope,
+      scopeId,
+      hashSubject(canonicalSubject),
+      hashPredicate(predicate),
+    );
+    const entry = this.map.get(key);
+    if (!entry || entry.facts.length === 0) return null;
+    return entry.facts[entry.facts.length - 1]!;
+  }
+
+  /**
+   * Return ALL facts for a subject (across predicates), time-sorted
+   * ascending. Used for temporal queries where history matters.
+   */
+  getAllTimeOrdered(scope: string, scopeId: string, subject: string): Fact[] {
+    const canonicalSubject = canonicalizeSubject(subject);
+    const subjectHash = hashSubject(canonicalSubject);
+    const prefix = `${scope}|${scopeId}|${subjectHash}|`;
+    const out: Fact[] = [];
+    for (const [k, entry] of this.map) {
+      if (!k.startsWith(prefix)) continue;
+      out.push(...entry.facts);
+    }
+    out.sort((a, b) => a.timestamp - b.timestamp);
+    return out;
+  }
+}

src/memory/retrieval/fact-graph/__tests__/FactStore.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { FactStore } from '../FactStore.js';
+import type { Fact } from '../types.js';
+
+function f(subject: string, predicate: string, object: string, ts: number): Fact {
+  return {
+    subject,
+    predicate,
+    object,
+    timestamp: ts,
+    sourceTraceIds: [`trace-${ts}`],
+    sourceSpan: `${subject} ${predicate} ${object}`,
+  };
+}
+
+describe('FactStore', () => {
+  it('upserts and returns the latest fact per (subject, predicate)', () => {
+    const store = new FactStore();
+    store.upsert('user', 'bench', [f('user', 'livesIn', 'NYC', 1)]);
+    store.upsert('user', 'bench', [f('user', 'livesIn', 'Berlin', 2)]);
+    expect(store.getLatest('user', 'bench', 'user', 'livesIn')?.object).toBe('Berlin');
+  });
+
+  it('returns time-sorted ascending list for getAllTimeOrdered', () => {
+    const store = new FactStore();
+    store.upsert('user', 'bench', [f('user', 'livesIn', 'NYC', 2)]);
+    store.upsert('user', 'bench', [f('user', 'livesIn', 'Berlin', 3)]);
+    store.upsert('user', 'bench', [f('user', 'livesIn', 'Boston', 1)]);
+    const all = store.getAllTimeOrdered('user', 'bench', 'user');
+    expect(all.map((x) => x.object)).toEqual(['Boston', 'NYC', 'Berlin']);
+  });
+
+  it('isolates facts across (scope, scopeId) pairs', () => {
+    const store = new FactStore();
+    store.upsert('user', 'u1', [f('user', 'prefers', 'tea', 1)]);
+    store.upsert('user', 'u2', [f('user', 'prefers', 'coffee', 1)]);
+    expect(store.getLatest('user', 'u1', 'user', 'prefers')?.object).toBe('tea');
+    expect(store.getLatest('user', 'u2', 'user', 'prefers')?.object).toBe('coffee');
+  });
+
+  it('canonicalizes subjects on upsert (I → user)', () => {
+    const store = new FactStore();
+    store.upsert('user', 'bench', [f('I', 'prefers', 'tea', 1)]);
+    expect(store.getLatest('user', 'bench', 'user', 'prefers')?.object).toBe('tea');
+    expect(store.getLatest('user', 'bench', 'I', 'prefers')?.object).toBe('tea');
+  });
+
+  it('drops facts with predicates outside the closed schema', () => {
+    const store = new FactStore();
+    store.upsert('user', 'bench', [f('user', 'mentioned', 'something', 1)]);
+    expect(store.getAllTimeOrdered('user', 'bench', 'user')).toEqual([]);
+  });
+
+  it('getLatest returns null for predicates outside the schema', () => {
+    const store = new FactStore();
+    store.upsert('user', 'bench', [f('user', 'prefers', 'tea', 1)]);
+    expect(store.getLatest('user', 'bench', 'user', 'mentioned')).toBeNull();
+  });
+
+  it('getLatest returns null for missing (subject, predicate)', () => {
+    const store = new FactStore();
+    expect(store.getLatest('user', 'bench', 'user', 'livesIn')).toBeNull();
+  });
+});

src/memory/retrieval/fact-graph/types.ts

@@ -0,0 +1,39 @@
+/**
+ * @file types.ts
+ * @description `Fact` + `FactStoreEntry` interfaces for the Step 9
+ * fact-graph. See the Step 9 design spec §4.2 for rationale behind the
+ * closed predicate schema + literal-object contract.
+ *
+ * @module agentos/memory/retrieval/fact-graph/types
+ */
+
+/**
+ * A single extracted fact tuple. `object` MUST be a literal span from
+ * the source turn (never paraphrased); this contract is the design
+ * delta from Steps 5/7/8 whose summary-based approaches erased
+ * specific-value tokens.
+ */
+export interface Fact {
+  /** Canonical subject ("user" for first-person, lowercase otherwise). */
+  subject: string;
+  /** Predicate from the closed schema (see {@link PREDICATE_SCHEMA}). */
+  predicate: string;
+  /** Literal object span from the source turn — NEVER paraphrased. */
+  object: string;
+  /** ms since epoch. */
+  timestamp: number;
+  /** Trace or session IDs this fact was extracted from. */
+  sourceTraceIds: string[];
+  /** The full sentence the fact came from (for audit, not retrieval). */
+  sourceSpan: string;
+}
+
+/**
+ * Time-sorted-ascending list of facts for a single (subject, predicate)
+ * pair. The latest fact supersedes earlier ones for `getLatest`
+ * queries; all of them are visible to temporal queries via
+ * `getAllTimeOrdered`.
+ */
+export interface FactStoreEntry {
+  facts: Fact[];
+}