feat(ingest-router,memory-router): Stage I entity-linking executors + ranker

Mem0-v3-style entity-linking primitives shipped in agentos core:

ingest-router/executors/:
- EntityExtractor: regex-based detection of proper nouns, quoted text,
  and compound noun phrases. Zero LLM cost. Configurable via
  properNounMinLength + compoundNounMaxLength.
- EntityLinkingIngestExecutor: ingest-side reference executor for the
  IngestRouter 'fact-graph' strategy. Surfaces entities alongside
  chunks for downstream entity-overlap re-ranking.
- entity-types.ts: shared types for both ingest + recall sides.

memory-router/backends/:
- EntityRetrievalRanker: recall-stage re-ranker that boosts candidates
  by entity-overlap with the query. combinedScore =
  (1-w)*semanticScore + w*(overlap/queryEntityCount). Mem0-v3 default
  weight ~0.5.

Both barrel exports updated. The IngestRouter 'fact-graph' strategy ID
now has a working reference executor. Consumers using
'@framers/agentos/memory-router' get the entity-overlap re-ranker.

20 new tests, 163/163 passing across ingest-router + memory-router.

Reference: docs.mem0.ai/migration/oss-v2-to-v3

Author: jddunn

src/ingest-router/executors/EntityExtractor.ts

@@ -0,0 +1,86 @@
+/**
+ * @file EntityExtractor.ts
+ * @description Mem0-v3-style entity extractor. Three classes:
+ *   - proper nouns (standalone capitalized tokens)
+ *   - quoted text (within "..." or '...')
+ *   - compound noun phrases (consecutive capitalized tokens)
+ *
+ * Order of detection: quoted text first (preserves verbatim spans),
+ * then compound noun phrases (greedy, longest match), then proper
+ * nouns (whatever capitalized tokens are not already inside a compound).
+ *
+ * Reference: docs.mem0.ai/migration/oss-v2-to-v3 §"Entity Extraction".
+ *
+ * @module @framers/agentos/ingest-router/executors/EntityExtractor
+ */
+
+import type {
+  ExtractedEntity,
+  EntityExtractionResult,
+  EntityLinkingOptions,
+} from './entity-types.js';
+
+export class EntityExtractor {
+  private readonly properNounMinLength: number;
+  private readonly compoundNounMaxLength: number;
+
+  constructor(opts: EntityLinkingOptions = {}) {
+    this.properNounMinLength = opts.properNounMinLength ?? 2;
+    this.compoundNounMaxLength = opts.compoundNounMaxLength ?? 5;
+  }
+
+  extract(text: string): EntityExtractionResult {
+    const entities: ExtractedEntity[] = [];
+
+    // 1. Quoted text — `"..."` or `'...'`. Captures verbatim spans
+    //    that authors wrap in quotes (config values, paths, etc.).
+    const quotedRegex = /["']([^"'\n]{1,200}?)["']/g;
+    let match: RegExpExecArray | null;
+    while ((match = quotedRegex.exec(text)) !== null) {
+      entities.push({
+        text: match[1],
+        kind: 'quoted-text',
+        positions: [match.index + 1],
+      });
+    }
+
+    // 2. Compound noun phrases — N consecutive capitalized tokens
+    //    where N >= 2 and N <= compoundNounMaxLength. Greedy: the
+    //    longest match wins.
+    const maxCompoundTokens = Math.max(2, this.compoundNounMaxLength);
+    const compoundPattern = new RegExp(
+      `\\b[A-Z][a-zA-Z]+(?:\\s+[A-Z][a-zA-Z]+){1,${maxCompoundTokens - 1}}\\b`,
+      'g',
+    );
+    const compoundRanges: Array<{ start: number; end: number }> = [];
+    while ((match = compoundPattern.exec(text)) !== null) {
+      const start = match.index;
+      const end = start + match[0].length;
+      compoundRanges.push({ start, end });
+      entities.push({
+        text: match[0],
+        kind: 'compound-noun-phrase',
+        positions: [start],
+      });
+    }
+
+    // 3. Proper nouns — single capitalized tokens NOT already covered
+    //    by a compound noun phrase.
+    const properPattern = /\b[A-Z][a-zA-Z]+\b/g;
+    while ((match = properPattern.exec(text)) !== null) {
+      if (match[0].length < this.properNounMinLength) continue;
+      const start = match.index;
+      const inCompound = compoundRanges.some(
+        (range) => start >= range.start && start < range.end,
+      );
+      if (inCompound) continue;
+      entities.push({
+        text: match[0],
+        kind: 'proper-noun',
+        positions: [start],
+      });
+    }
+
+    return { entities, rawText: text };
+  }
+}

src/ingest-router/executors/EntityLinkingIngestExecutor.ts

@@ -0,0 +1,73 @@
+/**
+ * @file EntityLinkingIngestExecutor.ts
+ * @description Mem0-v3-style ingest executor for the IngestRouter
+ * `fact-graph` strategy. Extracts entities from content (proper nouns,
+ * quoted text, compound noun phrases) and surfaces them on the result
+ * for downstream entity-overlap indexing at recall time.
+ *
+ * Unlike Mem0 v2 (which kept a separate Neo4j/Memgraph graph store),
+ * v3 uses parallel entity columns + multi-signal hybrid search. This
+ * executor captures the v3 pattern: regex-based extraction at ingest,
+ * no LLM cost, entities flow alongside chunks for retrieval-time
+ * re-ranking via {@link EntityRetrievalRanker}.
+ *
+ * Reference: docs.mem0.ai/migration/oss-v2-to-v3.
+ *
+ * @module @framers/agentos/ingest-router/executors/EntityLinkingIngestExecutor
+ */
+
+import { EntityExtractor } from './EntityExtractor.js';
+import type { IngestPayload } from './SummarizedIngestExecutor.js';
+import type { EntityLinkingOptions } from './entity-types.js';
+
+/**
+ * Outcome shape for the entity-linking executor.
+ */
+export interface EntityLinkingOutcome {
+  writtenTraces: number;
+  summary: string;
+  embedTexts: string[];
+  /** Distinct entities found across all chunks, deduplicated. */
+  entities: string[];
+  /** Entities found per chunk, in chunk order. */
+  entitiesPerChunk: string[][];
+  tokensIn: number;
+  tokensOut: number;
+}
+
+/**
+ * Reference executor for the IngestRouter `fact-graph` strategy.
+ * Wires entity extraction at ingest; the bench (or any consumer)
+ * indexes the entities alongside chunks for entity-overlap re-ranking.
+ */
+export class EntityLinkingIngestExecutor {
+  /** Strategy ID expected by IngestRouter's FunctionIngestDispatcher registry. */
+  readonly strategyId = 'fact-graph' as const;
+
+  private readonly extractor: EntityExtractor;
+
+  constructor(opts: EntityLinkingOptions = {}) {
+    this.extractor = new EntityExtractor(opts);
+  }
+
+  async ingest(
+    content: string,
+    payload: IngestPayload,
+  ): Promise<EntityLinkingOutcome> {
+    const chunks = payload.chunks ?? [content];
+    const entitiesPerChunk = chunks.map((chunk) =>
+      this.extractor.extract(chunk).entities.map((e) => e.text),
+    );
+    const allEntities = Array.from(new Set(entitiesPerChunk.flat()));
+
+    return {
+      writtenTraces: chunks.length,
+      summary: '',
+      embedTexts: chunks,
+      entities: allEntities,
+      entitiesPerChunk,
+      tokensIn: 0,
+      tokensOut: 0,
+    };
+  }
+}

src/ingest-router/executors/__tests__/EntityExtractor.test.ts

@@ -0,0 +1,77 @@
+/**
+ * @file EntityExtractor.test.ts
+ * @description Tests for the Mem0-v3-style entity extractor.
+ * Validates proper noun, quoted text, and compound noun phrase
+ * detection with character offsets.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { EntityExtractor } from '../EntityExtractor.js';
+
+describe('EntityExtractor (Mem0 v3 style)', () => {
+  const ex = new EntityExtractor();
+
+  it('extracts proper nouns', () => {
+    const result = ex.extract('John works at Anthropic in San Francisco.');
+    const proper = result.entities.filter((e) => e.kind === 'proper-noun').map((e) => e.text);
+    expect(proper).toEqual(expect.arrayContaining(['John', 'Anthropic']));
+    // San Francisco is detected as a compound noun phrase, not two proper nouns
+  });
+
+  it('extracts quoted text (double quotes)', () => {
+    const result = ex.extract('She said "deploy at midnight" before leaving.');
+    const quoted = result.entities.filter((e) => e.kind === 'quoted-text');
+    expect(quoted).toHaveLength(1);
+    expect(quoted[0].text).toBe('deploy at midnight');
+  });
+
+  it('extracts quoted text (single quotes)', () => {
+    const result = ex.extract("Use 'rerank-v3.5' for now.");
+    const quoted = result.entities.filter((e) => e.kind === 'quoted-text');
+    expect(quoted).toHaveLength(1);
+    expect(quoted[0].text).toBe('rerank-v3.5');
+  });
+
+  it('extracts compound noun phrases (consecutive capitalized tokens)', () => {
+    const result = ex.extract('San Francisco is north of Los Angeles.');
+    const cnp = result.entities.filter((e) => e.kind === 'compound-noun-phrase').map((e) => e.text);
+    expect(cnp).toEqual(expect.arrayContaining(['San Francisco', 'Los Angeles']));
+  });
+
+  it('does not double-count tokens already inside compound noun phrases', () => {
+    const result = ex.extract('Apple announced something in San Francisco.');
+    const proper = result.entities.filter((e) => e.kind === 'proper-noun').map((e) => e.text);
+    // "San" and "Francisco" are inside the compound, so they should NOT
+    // also appear as standalone proper nouns
+    expect(proper).not.toContain('San');
+    expect(proper).not.toContain('Francisco');
+    expect(proper).toContain('Apple');
+  });
+
+  it('returns position offsets for each entity', () => {
+    const result = ex.extract('Anthropic released Claude.');
+    const anthropic = result.entities.find((e) => e.text === 'Anthropic');
+    expect(anthropic).toBeDefined();
+    expect(anthropic!.positions[0]).toBe(0);
+  });
+
+  it('returns empty entities for text with no proper nouns', () => {
+    const result = ex.extract('the quick brown fox jumps over the lazy dog');
+    expect(result.entities).toHaveLength(0);
+  });
+
+  it('respects properNounMinLength option', () => {
+    const ex2 = new EntityExtractor({ properNounMinLength: 3 });
+    const result = ex2.extract('At noon, Bob called Al.');
+    const proper = result.entities.filter((e) => e.kind === 'proper-noun').map((e) => e.text);
+    // 'Al' is length 2 with min 3 — should be filtered out
+    expect(proper).not.toContain('Al');
+    expect(proper).toContain('Bob');
+  });
+
+  it('preserves raw text on the result', () => {
+    const text = 'OpenAI built GPT-4.';
+    const result = ex.extract(text);
+    expect(result.rawText).toBe(text);
+  });
+});

src/ingest-router/executors/__tests__/EntityLinkingIngestExecutor.test.ts

@@ -0,0 +1,51 @@
+/**
+ * @file EntityLinkingIngestExecutor.test.ts
+ * @description Tests for the ingest-side executor that extracts entities
+ * from content and emits them alongside chunks for downstream indexing
+ * (Stage I, Mem0-v3 style).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { EntityLinkingIngestExecutor } from '../EntityLinkingIngestExecutor.js';
+
+describe('EntityLinkingIngestExecutor', () => {
+  const executor = new EntityLinkingIngestExecutor();
+
+  it('returns the strategy ID expected by IngestRouter dispatcher', () => {
+    expect(executor.strategyId).toBe('fact-graph');
+  });
+
+  it('extracts entities and surfaces them on the result', async () => {
+    const result = await executor.ingest('Anthropic released Claude 3 Opus.', {
+      sessionId: 'sess-1',
+    });
+    expect(result.writtenTraces).toBe(1);
+    expect(result.entities).toEqual(expect.arrayContaining(['Anthropic']));
+  });
+
+  it('passes content through unchanged in embedTexts (no summary prepend)', async () => {
+    const result = await executor.ingest('plain content', { sessionId: 'sess-2' });
+    expect(result.embedTexts).toEqual(['plain content']);
+  });
+
+  it('returns one entity-tagged trace per chunk when payload.chunks supplied', async () => {
+    const result = await executor.ingest('full text', {
+      sessionId: 'sess-multi',
+      chunks: ['John works at Anthropic.', 'Bob works at OpenAI.'],
+    });
+    expect(result.writtenTraces).toBe(2);
+    expect(result.embedTexts).toEqual([
+      'John works at Anthropic.',
+      'Bob works at OpenAI.',
+    ]);
+    expect(result.entitiesPerChunk).toHaveLength(2);
+    expect(result.entitiesPerChunk[0]).toEqual(expect.arrayContaining(['John', 'Anthropic']));
+    expect(result.entitiesPerChunk[1]).toEqual(expect.arrayContaining(['Bob', 'OpenAI']));
+  });
+
+  it('costs nothing in tokensIn/tokensOut (regex-only, no LLM)', async () => {
+    const result = await executor.ingest('any text', { sessionId: 'sess' });
+    expect(result.tokensIn).toBe(0);
+    expect(result.tokensOut).toBe(0);
+  });
+});

src/ingest-router/executors/entity-types.ts

@@ -0,0 +1,58 @@
+/**
+ * @file entity-types.ts
+ * @description Types for the Mem0-v3-style entity-linking ingest
+ * executor (Stage I).
+ *
+ * Mem0 v3 dropped its graph store in favor of single-pass ADD-only
+ * fact extraction with multi-signal hybrid search. Entity extraction
+ * powers the entity-overlap re-rank signal at recall time. See spec
+ * §3.2 + STAGE_L_PHASE_A_FINDINGS for why this is the next-priority
+ * accuracy push.
+ *
+ * Reference: docs.mem0.ai/migration/oss-v2-to-v3.
+ *
+ * @module @framers/agentos/ingest-router/executors/entity-types
+ */
+
+/**
+ * Three entity kinds extracted at ingest. Mem0 v3 spec.
+ */
+export type EntityKind = 'proper-noun' | 'quoted-text' | 'compound-noun-phrase';
+
+/**
+ * One extracted entity with its kind + character offsets.
+ */
+export interface ExtractedEntity {
+  /** The literal entity string as it appears in the source text. */
+  text: string;
+  /** Classification of how the entity was identified. */
+  kind: EntityKind;
+  /** Character offsets in the source where this entity was matched. */
+  positions: number[];
+}
+
+/**
+ * Result of running EntityExtractor on a piece of text.
+ */
+export interface EntityExtractionResult {
+  /** Every entity found, in detection order. */
+  entities: ExtractedEntity[];
+  /** The raw text the extractor ran against. */
+  rawText: string;
+}
+
+/**
+ * Tunable parameters for entity extraction.
+ */
+export interface EntityLinkingOptions {
+  /**
+   * Minimum length for a token to count as a proper noun. Default 2.
+   * Filters out single-letter capitals (e.g., "I", "A").
+   */
+  properNounMinLength?: number;
+  /**
+   * Maximum number of consecutive capitalized tokens to count as one
+   * compound noun phrase. Default 5.
+   */
+  compoundNounMaxLength?: number;
+}

src/ingest-router/executors/index.ts

@@ -19,11 +19,22 @@ export type { IngestOutcome, IngestPayload } from './SummarizedIngestExecutor.js
 export { RawChunksIngestExecutor } from './RawChunksIngestExecutor.js';
 export type { RawChunksOutcome } from './RawChunksIngestExecutor.js';
 export { SkipIngestExecutor } from './SkipIngestExecutor.js';
+export { EntityExtractor } from './EntityExtractor.js';
+export { EntityLinkingIngestExecutor } from './EntityLinkingIngestExecutor.js';
+export type { EntityLinkingOutcome } from './EntityLinkingIngestExecutor.js';
+export type {
+  EntityKind,
+  ExtractedEntity,
+  EntityExtractionResult,
+  EntityLinkingOptions,
+} from './entity-types.js';
 
 import { SummarizedIngestExecutor } from './SummarizedIngestExecutor.js';
 import { RawChunksIngestExecutor } from './RawChunksIngestExecutor.js';
 import { SkipIngestExecutor } from './SkipIngestExecutor.js';
+import { EntityLinkingIngestExecutor } from './EntityLinkingIngestExecutor.js';
 import type { SessionSummarizer } from '../../memory/ingest/SessionSummarizer.js';
+import type { EntityLinkingOptions } from './entity-types.js';
 
 export function createSummarizedIngestExecutor(opts: {
   summarizer: SessionSummarizer;
@@ -38,3 +49,9 @@ export function createRawChunksIngestExecutor(): RawChunksIngestExecutor {
 export function createSkipIngestExecutor(): SkipIngestExecutor {
   return new SkipIngestExecutor();
 }
+
+export function createEntityLinkingIngestExecutor(
+  opts: EntityLinkingOptions = {},
+): EntityLinkingIngestExecutor {
+  return new EntityLinkingIngestExecutor(opts);
+}