feat(memory/typed-network): TypedNetworkRetriever for canonical-shaped retrieval

Adapter that turns the typed-network store + spreading activation into
ScoredMemoryTrace[] output, drop-in compatible with the bench's existing
canonical-hybrid reader pipeline.

Pipeline per query:
1. Extract candidate entities (proper nouns >= 3 chars + quoted strings)
2. Find seed facts whose entities intersect query entities (case-insensitive)
3. Run TypedSpreadingActivation with Hindsight Eq. 12 max-aggregate
4. Top-K activated facts -> ScoredMemoryTrace via typedFactToScoredTrace
5. Bank-prefixed content ("[WORLD] Berlin is in Germany") for reader hint

Includes typedFactToScoredTrace helper that namespaces IDs as
'typed-network:<factId>' and tags rows with 'typed-network', 'bank:<bank>'
for downstream attribution. 15 unit tests cover entity extraction, seed
matching, activation ranking, scope handling, and graph traversal.

Author: jddunn

src/memory/retrieval/typed-network/TypedNetworkRetriever.ts

@@ -0,0 +1,210 @@
+/**
+ * @file TypedNetworkRetriever.ts
+ * @description Retrieval adapter that turns the typed-network into a
+ * source of {@link ScoredMemoryTrace}s — drop-in compatible with the
+ * existing canonical-hybrid retrieval pipeline.
+ *
+ * **Pipeline (per query):**
+ *
+ * 1. Extract candidate entities from the query text via regex
+ *    (proper nouns ≥ 3 chars, quoted strings).
+ * 2. Find seed facts in the {@link TypedNetworkStore} whose
+ *    `entities` set intersects the query entities.
+ * 3. Run {@link TypedSpreadingActivation} from the seed set with
+ *    Hindsight Eq. 12 max-aggregation.
+ * 4. Take top-K activated facts (sorted by activation level
+ *    descending).
+ * 5. Convert each typed fact to a `ScoredMemoryTrace`-shaped object
+ *    so the bench's reader pipeline picks it up alongside canonical
+ *    chunks.
+ *
+ * The retriever is stateless aside from the store + spreading-
+ * activation engine it wraps. Safe to share across concurrent
+ * retrieves on the same store.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/TypedNetworkRetriever
+ */
+
+import type { ScoredMemoryTrace, MemoryScope } from '../../core/types.js';
+import type { TypedFact } from './types.js';
+import type { TypedNetworkStore } from './TypedNetworkStore.js';
+import type { TypedSpreadingActivation } from './TypedSpreadingActivation.js';
+
+/**
+ * Extract candidate entity strings from a query. Matches the
+ * Mem0-v3-style regex extractor used at ingest time so query and
+ * fact entities use the same canonicalization.
+ *
+ * Captures:
+ * - Capitalized words ≥ 3 characters (proper nouns: "Berlin",
+ *   "Docker", "TypeScript")
+ * - Double-quoted strings ("hello world")
+ * - Single-quoted strings ('like this')
+ *
+ * Returns deduplicated entity strings preserving original casing
+ * (case-sensitive comparison happens upstream).
+ */
+export function extractQueryEntities(text: string): string[] {
+  const properNouns = text.match(/\b[A-Z][a-zA-Z]{2,}\b/g) ?? [];
+  const dq = text.match(/"([^"]+)"/g)?.map((s) => s.slice(1, -1)) ?? [];
+  const sq = text.match(/'([^']+)'/g)?.map((s) => s.slice(1, -1)) ?? [];
+  return [...new Set([...properNouns, ...dq, ...sq])];
+}
+
+/**
+ * Construction options.
+ */
+export interface TypedNetworkRetrieverOptions {
+  /** The typed-network store populated at ingest time. */
+  store: TypedNetworkStore;
+  /** Pre-constructed spreading-activation engine. */
+  spreading: TypedSpreadingActivation;
+  /** Maximum hops for spreading activation. Default 3. */
+  maxDepth?: number;
+  /** Activation cutoff for spreading. Default 0.05. */
+  activationThreshold?: number;
+}
+
+/**
+ * Per-query retrieval options.
+ */
+export interface TypedNetworkRetrieveOptions {
+  /** Top-K facts to return after activation ranking. */
+  topK: number;
+  /** Memory scope (matches the canonical retrieval scope). */
+  scope: { scope: MemoryScope; scopeId: string };
+  /**
+   * Pre-extracted query entities. Pass when the consumer has done
+   * its own entity extraction (e.g. via a stronger NER model);
+   * skipping passes the query through {@link extractQueryEntities}.
+   */
+  queryEntities?: string[];
+}
+
+/**
+ * Adapter that produces canonical-shaped retrieval results from the
+ * typed-network store. Plugs into the bench's existing reader
+ * pipeline without requiring changes to downstream code.
+ */
+export class TypedNetworkRetriever {
+  private readonly store: TypedNetworkStore;
+  private readonly spreading: TypedSpreadingActivation;
+  private readonly maxDepth: number;
+  private readonly activationThreshold: number;
+
+  constructor(opts: TypedNetworkRetrieverOptions) {
+    this.store = opts.store;
+    this.spreading = opts.spreading;
+    this.maxDepth = opts.maxDepth ?? 3;
+    this.activationThreshold = opts.activationThreshold ?? 0.05;
+  }
+
+  /**
+   * Retrieve top-K typed facts for the query, formatted as
+   * {@link ScoredMemoryTrace}s. Returns an empty array when no
+   * query entities match seed facts in the store (e.g. queries with
+   * no proper nouns or quoted strings, or queries whose entities
+   * the typed network has not yet observed).
+   */
+  async retrieve(
+    query: string,
+    options: TypedNetworkRetrieveOptions,
+  ): Promise<ScoredMemoryTrace[]> {
+    const entities = options.queryEntities ?? extractQueryEntities(query);
+    if (entities.length === 0) return [];
+
+    // Seed selection: any fact whose entity set intersects the query
+    // entities. Case-insensitive intersection because LLM-extracted
+    // fact entities sometimes drop capitalization.
+    const lowerEntities = new Set(entities.map((e) => e.toLowerCase()));
+    const seedIds: string[] = [];
+    for (const fact of this.store.iterateFacts()) {
+      if (fact.entities.some((e) => lowerEntities.has(e.toLowerCase()))) {
+        seedIds.push(fact.id);
+      }
+    }
+    if (seedIds.length === 0) return [];
+
+    // Spreading activation with Eq. 12 max-aggregate.
+    const activations = this.spreading.spread(this.store, seedIds, {
+      maxDepth: this.maxDepth,
+      activationThreshold: this.activationThreshold,
+    });
+
+    // Rank by activation, take top-K.
+    const ranked = [...activations.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, options.topK);
+
+    const traces: ScoredMemoryTrace[] = [];
+    for (const [factId, activation] of ranked) {
+      const fact = this.store.getFact(factId);
+      if (!fact) continue;
+      traces.push(typedFactToScoredTrace(fact, activation, options.scope));
+    }
+    return traces;
+  }
+}
+
+/**
+ * Convert a {@link TypedFact} into a {@link ScoredMemoryTrace} for
+ * the bench's downstream reader pipeline. Renders the bank label
+ * inline in the content so the reader can distinguish typed facts
+ * from raw chunks at prompt time.
+ *
+ * Defaults follow the {@link HybridRetriever.factToScoredTrace}
+ * pattern: encoding strength 1, retrieval score = activation level,
+ * neutral emotional context, lifecycle timestamps drawn from the
+ * fact's mention timestamp.
+ */
+export function typedFactToScoredTrace(
+  fact: TypedFact,
+  activation: number,
+  scope: { scope: MemoryScope; scopeId: string },
+): ScoredMemoryTrace {
+  const mentionMs = Date.parse(fact.temporal.mention);
+  const ts = Number.isNaN(mentionMs) ? Date.now() : mentionMs;
+  // Bank-prefixed content gives the reader a hint about fact kind.
+  const content = `[${fact.bank}] ${fact.text}`;
+  return {
+    id: `typed-network:${fact.id}`,
+    type: 'semantic',
+    scope: scope.scope,
+    scopeId: scope.scopeId,
+    content,
+    entities: fact.entities,
+    tags: ['typed-network', `bank:${fact.bank}`],
+    provenance: {
+      sourceType: 'typed_network',
+      sourceTimestamp: ts,
+      confidence: fact.confidence,
+      verificationCount: 0,
+    },
+    emotionalContext: {
+      valence: 0,
+      arousal: 0,
+      dominance: 0,
+      intensity: 0,
+      gmiMood: '',
+    },
+    encodingStrength: 1,
+    stability: 1,
+    retrievalCount: 0,
+    lastAccessedAt: ts,
+    accessCount: 0,
+    reinforcementInterval: 0,
+    associatedTraceIds: [],
+    createdAt: ts,
+    updatedAt: ts,
+    isActive: true,
+    retrievalScore: activation,
+    scoreBreakdown: {
+      strengthScore: 1,
+      similarityScore: 0,
+      recencyScore: 0,
+      emotionalCongruenceScore: 0,
+      graphActivationScore: activation,
+      importanceScore: fact.confidence,
+    },
+  };
+}

src/memory/retrieval/typed-network/__tests__/TypedNetworkRetriever.test.ts

@@ -0,0 +1,186 @@
+/**
+ * @file TypedNetworkRetriever.test.ts
+ * @description Contract tests for the TypedNetworkRetriever adapter.
+ * Pin: query-entity extraction (regex), seed-set construction (entity
+ * intersection), spreading-activation order, and ScoredMemoryTrace
+ * shape coming out of typedFactToScoredTrace.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  TypedNetworkRetriever,
+  extractQueryEntities,
+  typedFactToScoredTrace,
+} from '../TypedNetworkRetriever.js';
+import { TypedNetworkStore } from '../TypedNetworkStore.js';
+import { TypedSpreadingActivation } from '../TypedSpreadingActivation.js';
+import type { TypedFact, BankId } from '../types.js';
+
+function makeFact(
+  id: string,
+  text: string,
+  entities: string[],
+  bank: BankId = 'WORLD',
+  mention = '2026-04-26T10:00:00Z',
+): TypedFact {
+  return {
+    id,
+    bank,
+    text,
+    embedding: [],
+    temporal: { mention },
+    participants: [],
+    reasoningMarkers: [],
+    entities,
+    confidence: 1.0,
+  };
+}
+
+describe('extractQueryEntities', () => {
+  it('extracts capitalized proper nouns ≥ 3 chars', () => {
+    expect(extractQueryEntities('Where does Alice live?')).toEqual(['Where', 'Alice']);
+    expect(extractQueryEntities('I deployed Docker yesterday')).toEqual(['Docker']);
+  });
+
+  it('extracts double-quoted strings', () => {
+    const out = extractQueryEntities('Find the "deployment server" config');
+    expect(out).toContain('deployment server');
+  });
+
+  it('extracts single-quoted strings', () => {
+    const out = extractQueryEntities("She said 'hello world' to me");
+    expect(out).toContain('hello world');
+  });
+
+  it('deduplicates entities', () => {
+    const out = extractQueryEntities('Berlin Berlin Berlin');
+    expect(out).toEqual(['Berlin']);
+  });
+
+  it('returns empty for queries with no proper nouns or quotes', () => {
+    expect(extractQueryEntities('what time is it')).toEqual([]);
+    expect(extractQueryEntities('a b c')).toEqual([]);
+  });
+});
+
+describe('typedFactToScoredTrace', () => {
+  it('produces a valid ScoredMemoryTrace shape', () => {
+    const fact = makeFact('f1', 'Berlin is in Germany', ['Berlin', 'Germany']);
+    const trace = typedFactToScoredTrace(fact, 0.75, { scope: 'user', scopeId: 'bench' });
+    expect(trace.id).toBe('typed-network:f1');
+    expect(trace.type).toBe('semantic');
+    expect(trace.scope).toBe('user');
+    expect(trace.scopeId).toBe('bench');
+    expect(trace.content).toBe('[WORLD] Berlin is in Germany');
+    expect(trace.retrievalScore).toBe(0.75);
+    expect(trace.provenance.sourceType).toBe('typed_network');
+    expect(trace.tags).toContain('typed-network');
+    expect(trace.tags).toContain('bank:WORLD');
+    expect(trace.entities).toEqual(['Berlin', 'Germany']);
+    expect(trace.scoreBreakdown.graphActivationScore).toBe(0.75);
+  });
+
+  it('includes bank label in content for reader disambiguation', () => {
+    const fact = makeFact('f2', 'I prefer TypeScript', ['TypeScript'], 'OPINION');
+    const trace = typedFactToScoredTrace(fact, 0.5, { scope: 'user', scopeId: 'b' });
+    expect(trace.content.startsWith('[OPINION]')).toBe(true);
+  });
+
+  it('uses fact mention timestamp for lifecycle fields', () => {
+    const fact = makeFact('f3', 'X', [], 'WORLD', '2026-01-01T00:00:00Z');
+    const trace = typedFactToScoredTrace(fact, 1.0, { scope: 'user', scopeId: 'b' });
+    expect(trace.lastAccessedAt).toBe(Date.parse('2026-01-01T00:00:00Z'));
+    expect(trace.createdAt).toBe(Date.parse('2026-01-01T00:00:00Z'));
+  });
+
+  it('falls back to current time on invalid mention timestamp', () => {
+    const fact = makeFact('f4', 'X', [], 'WORLD', 'not-a-date');
+    const before = Date.now();
+    const trace = typedFactToScoredTrace(fact, 1.0, { scope: 'user', scopeId: 'b' });
+    const after = Date.now();
+    expect(trace.lastAccessedAt).toBeGreaterThanOrEqual(before);
+    expect(trace.lastAccessedAt).toBeLessThanOrEqual(after);
+  });
+});
+
+describe('TypedNetworkRetriever.retrieve', () => {
+  let store: TypedNetworkStore;
+  let spreading: TypedSpreadingActivation;
+  let retriever: TypedNetworkRetriever;
+
+  beforeEach(() => {
+    store = new TypedNetworkStore();
+    spreading = new TypedSpreadingActivation({ decay: 0.5 });
+    retriever = new TypedNetworkRetriever({ store, spreading });
+  });
+
+  it('returns empty array when query has no entities', async () => {
+    store.addFact(makeFact('f1', 'X', ['Berlin']));
+    const out = await retriever.retrieve('what time is it', {
+      topK: 5,
+      scope: { scope: 'user', scopeId: 'b' },
+    });
+    expect(out).toEqual([]);
+  });
+
+  it('returns empty array when no facts match query entities', async () => {
+    store.addFact(makeFact('f1', 'X', ['Berlin']));
+    const out = await retriever.retrieve('Where is Tokyo?', {
+      topK: 5,
+      scope: { scope: 'user', scopeId: 'b' },
+    });
+    expect(out).toEqual([]);
+  });
+
+  it('returns matching facts ordered by spreading-activation level', async () => {
+    store.addFact(makeFact('f1', 'A', ['Berlin']));
+    store.addFact(makeFact('f2', 'B', ['Germany']));
+    store.addFact(makeFact('f3', 'C', ['Other']));
+    // f1 is the seed (entity match); f2 connected via entity edge.
+    store.addEdge({ fromFactId: 'f1', toFactId: 'f2', kind: 'entity', weight: 1.0 });
+    const out = await retriever.retrieve('Where is Berlin?', {
+      topK: 5,
+      scope: { scope: 'user', scopeId: 'b' },
+    });
+    // f1 is seed (activation 1.0); f2 is 1-hop entity (activation 0.5).
+    // f3 has no edges, so no activation.
+    expect(out).toHaveLength(2);
+    expect(out[0].id).toBe('typed-network:f1');
+    expect(out[0].retrievalScore).toBe(1.0);
+    expect(out[1].id).toBe('typed-network:f2');
+    expect(out[1].retrievalScore).toBe(0.5);
+  });
+
+  it('case-insensitive entity matching', async () => {
+    store.addFact(makeFact('f1', 'X', ['BERLIN'])); // uppercase in fact
+    const out = await retriever.retrieve('where is berlin', {
+      // lowercase in query — should still match
+      topK: 5,
+      scope: { scope: 'user', scopeId: 'b' },
+      queryEntities: ['berlin'],
+    });
+    expect(out).toHaveLength(1);
+    expect(out[0].id).toBe('typed-network:f1');
+  });
+
+  it('respects topK cutoff', async () => {
+    for (let i = 0; i < 10; i++) {
+      store.addFact(makeFact(`f${i}`, `X${i}`, ['Berlin']));
+    }
+    const out = await retriever.retrieve('Where is Berlin?', {
+      topK: 3,
+      scope: { scope: 'user', scopeId: 'b' },
+    });
+    expect(out).toHaveLength(3);
+  });
+
+  it('accepts explicit queryEntities to skip regex extraction', async () => {
+    store.addFact(makeFact('f1', 'X', ['custom-entity-name']));
+    const out = await retriever.retrieve('any text', {
+      topK: 5,
+      scope: { scope: 'user', scopeId: 'b' },
+      queryEntities: ['custom-entity-name'],
+    });
+    expect(out).toHaveLength(1);
+  });
+});