@vellumai/assistant 0.3.0

package/src/__tests__/memory-recall-quality.test.ts

@@ -0,0 +1,846 @@
+/**
+ * Memory Recall Quality Fixtures
+ *
+ * Fixture-driven tests that guard recall quality: preference recall,
+ * contradiction suppression, stale-memory filtering, and importance ranking.
+ * These tests fail if memory quality degrades — they act as guardrails
+ * before any retrieval or ranking changes.
+ */
+import { afterAll, beforeAll, beforeEach, describe, expect, mock, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const testDir = mkdtempSync(join(tmpdir(), 'memory-recall-quality-'));
+
+mock.module('../util/platform.js', () => ({
+  getDataDir: () => testDir,
+  isMacOS: () => process.platform === 'darwin',
+  isLinux: () => process.platform === 'linux',
+  isWindows: () => process.platform === 'win32',
+  getSocketPath: () => join(testDir, 'test.sock'),
+  getPidPath: () => join(testDir, 'test.pid'),
+  getDbPath: () => join(testDir, 'test.db'),
+  getLogPath: () => join(testDir, 'test.log'),
+  ensureDataDir: () => {},
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+}));
+
+// Stub the local embedding backend so the real ONNX model (2.5 GB RSS) never
+// loads — avoids a Bun v1.3.9 panic on process exit.
+mock.module('../memory/embedding-local.js', () => ({
+  LocalEmbeddingBackend: class {
+    readonly provider = 'local' as const;
+    readonly model: string;
+    constructor(model: string) { this.model = model; }
+    async embed(texts: string[]): Promise<number[][]> {
+      return texts.map(() => new Array(384).fill(0));
+    }
+  },
+}));
+
+// Mock Qdrant client so semantic search returns empty results instead of
+// throwing "Qdrant client not initialized" (which would discard lexical results
+// due to the single try-catch in buildMemoryRecall).
+mock.module('../memory/qdrant-client.js', () => ({
+  getQdrantClient: () => ({
+    searchWithFilter: async () => [],
+    upsertPoints: async () => {},
+    deletePoints: async () => {},
+  }),
+  initQdrantClient: () => {},
+}));
+
+import { DEFAULT_CONFIG } from '../config/defaults.js';
+
+const TEST_CONFIG = {
+  ...DEFAULT_CONFIG,
+  memory: {
+    ...DEFAULT_CONFIG.memory,
+    extraction: {
+      ...DEFAULT_CONFIG.memory.extraction,
+      useLLM: false,
+    },
+    embeddings: {
+      ...DEFAULT_CONFIG.memory.embeddings,
+      required: false,
+    },
+  },
+};
+
+mock.module('../config/loader.js', () => ({
+  loadConfig: () => TEST_CONFIG,
+  getConfig: () => TEST_CONFIG,
+  invalidateConfigCache: () => {},
+}));
+
+import { getDb, initializeDb, resetDb } from '../memory/db.js';
+import { buildMemoryRecall } from '../memory/retriever.js';
+import {
+  conversations,
+  memoryEntities,
+  memoryEntityRelations,
+  memoryItemEntities,
+  memoryItems,
+  memoryItemSources,
+  messages,
+} from '../memory/schema.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Insert a standard conversation + message row for fixture setup. */
+function insertConversation(db: ReturnType<typeof getDb>, id: string, createdAt: number) {
+  db.insert(conversations).values({
+    id,
+    title: null,
+    createdAt,
+    updatedAt: createdAt,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalEstimatedCost: 0,
+    contextSummary: null,
+    contextCompactedMessageCount: 0,
+    contextCompactedAt: null,
+  }).run();
+}
+
+function insertMessage(db: ReturnType<typeof getDb>, id: string, conversationId: string, role: string, text: string, createdAt: number) {
+  db.insert(messages).values({
+    id,
+    conversationId,
+    role,
+    content: JSON.stringify([{ type: 'text', text }]),
+    createdAt,
+  }).run();
+}
+
+function insertSegment(db: ReturnType<typeof getDb>, id: string, messageId: string, conversationId: string, role: string, text: string, createdAt: number) {
+  db.run(`
+    INSERT INTO memory_segments (
+      id, message_id, conversation_id, role, segment_index, text, token_estimate, created_at, updated_at
+    ) VALUES (
+      '${id}', '${messageId}', '${conversationId}', '${role}', 0, '${text.replace(/'/g, "''")}', ${Math.ceil(text.split(/\s+/).length * 1.3)}, ${createdAt}, ${createdAt}
+    )
+  `);
+}
+
+function insertItem(db: ReturnType<typeof getDb>, opts: {
+  id: string;
+  kind: string;
+  subject: string;
+  statement: string;
+  status?: string;
+  confidence?: number;
+  importance?: number;
+  accessCount?: number;
+  firstSeenAt: number;
+  lastSeenAt?: number;
+}) {
+  db.insert(memoryItems).values({
+    id: opts.id,
+    kind: opts.kind,
+    subject: opts.subject,
+    statement: opts.statement,
+    status: opts.status ?? 'active',
+    confidence: opts.confidence ?? 0.8,
+    importance: opts.importance ?? 0.6,
+    accessCount: opts.accessCount ?? 0,
+    fingerprint: `fp-${opts.id}`,
+    firstSeenAt: opts.firstSeenAt,
+    lastSeenAt: opts.lastSeenAt ?? opts.firstSeenAt,
+    lastUsedAt: null,
+  }).run();
+}
+
+function insertItemSource(db: ReturnType<typeof getDb>, itemId: string, messageId: string, createdAt: number) {
+  db.insert(memoryItemSources).values({
+    memoryItemId: itemId,
+    messageId,
+    evidence: `evidence for ${itemId}`,
+    createdAt,
+  }).run();
+}
+
+/**
+ * Assert that at least `minFound` of the `expectedSubstrings` appear in `text`.
+ * This is a deterministic precision@k-style check: given a list of expected
+ * items and the injected recall text, verify enough of them were recalled.
+ */
+function assertPrecisionAtK(
+  text: string,
+  expectedSubstrings: string[],
+  minFound: number,
+  label?: string,
+) {
+  const found = expectedSubstrings.filter((s) => text.includes(s));
+  const precision = found.length / expectedSubstrings.length;
+  if (found.length < minFound) {
+    const prefix = label ? `[${label}] ` : '';
+    throw new Error(
+      `${prefix}precision@${expectedSubstrings.length} too low: ` +
+      `found ${found.length}/${expectedSubstrings.length} (${(precision * 100).toFixed(0)}%), ` +
+      `need at least ${minFound}. ` +
+      `Missing: ${expectedSubstrings.filter((s) => !text.includes(s)).join(', ')}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Suite
+// ---------------------------------------------------------------------------
+
+describe('Memory Recall Quality', () => {
+  beforeAll(() => {
+    initializeDb();
+  });
+
+  beforeEach(() => {
+    const db = getDb();
+    db.run('DELETE FROM memory_item_sources');
+    db.run('DELETE FROM memory_item_entities');
+    db.run('DELETE FROM memory_entity_relations');
+    db.run('DELETE FROM memory_entities');
+    db.run('DELETE FROM memory_embeddings');
+    db.run('DELETE FROM memory_summaries');
+    db.run('DELETE FROM memory_items');
+    db.run('DELETE FROM memory_segment_fts');
+    db.run('DELETE FROM memory_segments');
+    db.run('DELETE FROM messages');
+    db.run('DELETE FROM conversations');
+    db.run('DELETE FROM memory_jobs');
+    db.run('DELETE FROM memory_checkpoints');
+  });
+
+  afterAll(() => {
+    resetDb();
+    try {
+      rmSync(testDir, { recursive: true });
+    } catch {
+      // best effort cleanup
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // Preference Recall
+  // -------------------------------------------------------------------------
+
+  describe('preference recall', () => {
+    test('preferences are recalled when querying about user preferences', async () => {
+      const db = getDb();
+      const now = 1_700_000_000_000;
+      insertConversation(db, 'conv-pref', now);
+      insertMessage(db, 'msg-pref-1', 'conv-pref', 'user', 'I prefer dark mode and concise answers', now);
+      insertMessage(db, 'msg-pref-2', 'conv-pref', 'user', 'My favorite editor is Neovim', now + 1000);
+      insertMessage(db, 'msg-fact-1', 'conv-pref', 'user', 'The server runs on port 3000', now + 2000);
+
+      insertSegment(db, 'seg-pref-1', 'msg-pref-1', 'conv-pref', 'user', 'I prefer dark mode and concise answers', now);
+      insertSegment(db, 'seg-pref-2', 'msg-pref-2', 'conv-pref', 'user', 'My favorite editor is Neovim', now + 1000);
+      insertSegment(db, 'seg-fact-1', 'msg-fact-1', 'conv-pref', 'user', 'The server runs on port 3000', now + 2000);
+
+      const recall = await buildMemoryRecall('what are my preferences', 'conv-pref', TEST_CONFIG);
+
+      expect(recall.injectedText).toContain('dark mode');
+      expect(recall.injectedText).toContain('concise answers');
+    });
+
+    test('high-importance preferences outrank low-importance facts in recall', async () => {
+      const db = getDb();
+      const now = 1_700_000_100_000;
+      insertConversation(db, 'conv-rank', now);
+
+      // High-importance preference
+      insertMessage(db, 'msg-hi', 'conv-rank', 'user', 'I strongly prefer TypeScript over JavaScript', now);
+      insertSegment(db, 'seg-hi', 'msg-hi', 'conv-rank', 'user', 'I strongly prefer TypeScript over JavaScript', now);
+      insertItem(db, {
+        id: 'item-hi-pref',
+        kind: 'preference',
+        subject: 'language preference',
+        statement: 'User strongly prefers TypeScript over JavaScript',
+        importance: 0.9,
+        firstSeenAt: now,
+      });
+      insertItemSource(db, 'item-hi-pref', 'msg-hi', now);
+
+      // Low-importance fact
+      insertMessage(db, 'msg-lo', 'conv-rank', 'user', 'The default port is 8080', now + 1000);
+      insertSegment(db, 'seg-lo', 'msg-lo', 'conv-rank', 'user', 'The default port is 8080', now + 1000);
+      insertItem(db, {
+        id: 'item-lo-fact',
+        kind: 'fact',
+        subject: 'default port',
+        statement: 'The default port is 8080',
+        importance: 0.3,
+        firstSeenAt: now + 1000,
+      });
+      insertItemSource(db, 'item-lo-fact', 'msg-lo', now + 1000);
+
+      const recall = await buildMemoryRecall('TypeScript preference language', 'conv-rank', TEST_CONFIG);
+
+      // The preference should appear
+      expect(recall.injectedText).toContain('TypeScript');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Contradiction / Superseding Suppression
+  // -------------------------------------------------------------------------
+
+  describe('contradiction suppression', () => {
+    test('superseded memory items do not appear in recall', async () => {
+      const db = getDb();
+      const now = 1_700_000_200_000;
+      insertConversation(db, 'conv-contra', now);
+
+      // Old preference (superseded)
+      insertMessage(db, 'msg-old-pref', 'conv-contra', 'user', 'I prefer vim for editing code', now - 50_000);
+      insertSegment(db, 'seg-old-pref', 'msg-old-pref', 'conv-contra', 'user', 'I prefer vim for editing code', now - 50_000);
+      insertItem(db, {
+        id: 'item-old-pref',
+        kind: 'preference',
+        subject: 'editor preference',
+        statement: 'User prefers vim for editing code',
+        status: 'superseded',
+        importance: 0.8,
+        firstSeenAt: now - 50_000,
+      });
+      insertItemSource(db, 'item-old-pref', 'msg-old-pref', now - 50_000);
+
+      // New preference (active, replaces the old one)
+      insertMessage(db, 'msg-new-pref', 'conv-contra', 'user', 'I now prefer neovim with LazyVim for editing code', now);
+      insertSegment(db, 'seg-new-pref', 'msg-new-pref', 'conv-contra', 'user', 'I now prefer neovim with LazyVim for editing code', now);
+      insertItem(db, {
+        id: 'item-new-pref',
+        kind: 'preference',
+        subject: 'editor preference',
+        statement: 'User now prefers neovim with LazyVim for editing code',
+        status: 'active',
+        importance: 0.8,
+        firstSeenAt: now,
+      });
+      insertItemSource(db, 'item-new-pref', 'msg-new-pref', now);
+
+      const recall = await buildMemoryRecall('editor preference', 'conv-contra', TEST_CONFIG);
+
+      // Active preference should appear
+      expect(recall.injectedText).toContain('neovim');
+      expect(recall.injectedText).toContain('LazyVim');
+
+      // Superseded preference should NOT appear in recalled item lines.
+      // Assert against the actual statement text unique to the superseded item
+      // ("prefers vim for") rather than an internal candidate key, which is
+      // never emitted in the formatted recall output.
+      const itemLines = recall.injectedText
+        .split('\n')
+        .filter((line) => line.includes('<kind>'));
+      const hasSupersededItem = itemLines.some(
+        (line) => line.includes('prefers vim for'),
+      );
+      expect(hasSupersededItem).toBe(false);
+    });
+
+    test('only active items are included in entity-based recall', async () => {
+      const db = getDb();
+      const now = 1_700_000_250_000;
+      insertConversation(db, 'conv-entity-status', now);
+
+      insertMessage(db, 'msg-entity-active', 'conv-entity-status', 'user', 'We decided to use PostgreSQL as the database', now);
+      insertSegment(db, 'seg-entity-active', 'msg-entity-active', 'conv-entity-status', 'user', 'We decided to use PostgreSQL as the database', now);
+      insertItem(db, {
+        id: 'item-active-db',
+        kind: 'decision',
+        subject: 'database choice',
+        statement: 'Team decided to use PostgreSQL as the primary database',
+        status: 'active',
+        importance: 0.8,
+        firstSeenAt: now,
+      });
+      insertItemSource(db, 'item-active-db', 'msg-entity-active', now);
+
+      insertItem(db, {
+        id: 'item-superseded-db',
+        kind: 'decision',
+        subject: 'database choice',
+        statement: 'Team decided to use MySQL as the primary database',
+        status: 'superseded',
+        importance: 0.8,
+        firstSeenAt: now - 100_000,
+      });
+      insertItemSource(db, 'item-superseded-db', 'msg-entity-active', now - 100_000);
+
+      const recall = await buildMemoryRecall('database choice decision', 'conv-entity-status', TEST_CONFIG);
+
+      expect(recall.injectedText).toContain('PostgreSQL');
+    });
+
+    test('pending clarification and invalidated items are excluded from direct item recall', async () => {
+      const db = getDb();
+      const now = 1_700_000_275_000;
+      insertConversation(db, 'conv-conflict-status', now);
+      insertMessage(
+        db,
+        'msg-conflict-status',
+        'conv-conflict-status',
+        'user',
+        'Framework preference is React for this codebase.',
+        now,
+      );
+
+      insertItem(db, {
+        id: 'item-framework-active',
+        kind: 'preference',
+        subject: 'framework preference',
+        statement: 'Framework preference is React for this codebase',
+        status: 'active',
+        importance: 0.9,
+        firstSeenAt: now,
+      });
+      insertItemSource(db, 'item-framework-active', 'msg-conflict-status', now);
+
+      insertItem(db, {
+        id: 'item-framework-pending',
+        kind: 'preference',
+        subject: 'framework preference',
+        statement: 'Framework preference is Vue for this codebase',
+        status: 'pending_clarification',
+        importance: 0.9,
+        firstSeenAt: now + 1,
+      });
+      insertItemSource(db, 'item-framework-pending', 'msg-conflict-status', now + 1);
+
+      insertItem(db, {
+        id: 'item-framework-invalid',
+        kind: 'preference',
+        subject: 'framework preference',
+        statement: 'Framework preference is Angular for this codebase',
+        status: 'active',
+        importance: 0.9,
+        firstSeenAt: now + 2,
+      });
+      db.run(`UPDATE memory_items SET invalid_at = ${now + 3} WHERE id = 'item-framework-invalid'`);
+      insertItemSource(db, 'item-framework-invalid', 'msg-conflict-status', now + 2);
+
+      const recall = await buildMemoryRecall('framework preference', 'conv-conflict-status', TEST_CONFIG);
+      expect(recall.injectedText).toContain('React');
+      expect(recall.injectedText).not.toContain('Vue');
+      expect(recall.injectedText).not.toContain('Angular');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Stale Memory Suppression
+  // -------------------------------------------------------------------------
+
+  describe('stale memory suppression', () => {
+    test('recently mentioned memories outrank old memories via recency scoring', async () => {
+      const db = getDb();
+      const now = Date.now();
+      const oneMonthAgo = now - 30 * 24 * 60 * 60 * 1000;
+      insertConversation(db, 'conv-stale', now);
+
+      // Recent mention
+      insertMessage(db, 'msg-recent', 'conv-stale', 'user', 'We are using Bun as our runtime environment', now - 1000);
+      insertSegment(db, 'seg-recent', 'msg-recent', 'conv-stale', 'user', 'We are using Bun as our runtime environment', now - 1000);
+
+      // Old mention (same topic)
+      insertMessage(db, 'msg-old', 'conv-stale', 'user', 'We are using Node as our runtime environment', oneMonthAgo);
+      insertSegment(db, 'seg-old', 'msg-old', 'conv-stale', 'user', 'We are using Node as our runtime environment', oneMonthAgo);
+
+      const recall = await buildMemoryRecall('runtime environment', 'conv-stale', TEST_CONFIG);
+
+      // Both may appear but recent should rank higher (appear in injected text)
+      expect(recall.injectedText).toContain('Bun');
+    });
+
+    test('frequently accessed items get a retrieval reinforcement boost', async () => {
+      const db = getDb();
+      const now = 1_700_000_400_000;
+      insertConversation(db, 'conv-access', now);
+
+      // Frequently accessed item
+      insertMessage(db, 'msg-freq', 'conv-access', 'user', 'User timezone is America/Los_Angeles', now);
+      insertSegment(db, 'seg-freq', 'msg-freq', 'conv-access', 'user', 'User timezone is America/Los_Angeles', now);
+      insertItem(db, {
+        id: 'item-freq',
+        kind: 'profile',
+        subject: 'timezone',
+        statement: 'User timezone is America/Los_Angeles',
+        importance: 0.5,
+        accessCount: 20,
+        firstSeenAt: now,
+      });
+      insertItemSource(db, 'item-freq', 'msg-freq', now);
+
+      // Rarely accessed item
+      insertMessage(db, 'msg-rare', 'conv-access', 'user', 'User timezone offset is UTC-8', now + 1000);
+      insertSegment(db, 'seg-rare', 'msg-rare', 'conv-access', 'user', 'User timezone offset is UTC-8', now + 1000);
+      insertItem(db, {
+        id: 'item-rare',
+        kind: 'profile',
+        subject: 'timezone offset',
+        statement: 'User timezone offset is UTC-8',
+        importance: 0.5,
+        accessCount: 0,
+        firstSeenAt: now + 1000,
+      });
+      insertItemSource(db, 'item-rare', 'msg-rare', now + 1000);
+
+      const recall = await buildMemoryRecall('timezone', 'conv-access', TEST_CONFIG);
+
+      // The frequently accessed item should appear
+      expect(recall.injectedText).toContain('America/Los_Angeles');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Multi-source recall consistency
+  // -------------------------------------------------------------------------
+
+  describe('multi-source recall', () => {
+    test('lexical and item-based results are merged into a single recall', async () => {
+      const db = getDb();
+      const now = 1_700_000_500_000;
+      insertConversation(db, 'conv-multi', now);
+
+      // Segment (lexical source)
+      insertMessage(db, 'msg-seg', 'conv-multi', 'user', 'Deploy to staging before production always', now);
+      insertSegment(db, 'seg-deploy', 'msg-seg', 'conv-multi', 'user', 'Deploy to staging before production always', now);
+
+      // Item (entity/item source)
+      insertItem(db, {
+        id: 'item-deploy-rule',
+        kind: 'constraint',
+        subject: 'deployment rule',
+        statement: 'Always deploy to staging before production',
+        importance: 0.9,
+        firstSeenAt: now,
+      });
+      insertItemSource(db, 'item-deploy-rule', 'msg-seg', now);
+
+      const recall = await buildMemoryRecall('deployment staging production', 'conv-multi', TEST_CONFIG);
+
+      // Both the segment and item should contribute to the recall
+      expect(recall.lexicalHits).toBeGreaterThan(0);
+      expect(recall.injectedText).toContain('staging');
+      expect(recall.injectedText).toContain('production');
+    });
+
+    test('recall with no matching content returns empty injection', async () => {
+      const db = getDb();
+      const now = 1_700_000_600_000;
+      insertConversation(db, 'conv-empty', now);
+
+      const recall = await buildMemoryRecall('completely unrelated xyzzy topic', 'conv-empty', TEST_CONFIG);
+
+      expect(recall.injectedText).toBe('');
+      expect(recall.injectedTokens).toBe(0);
+    });
+
+    test('entity alias matching recalls linked items on indirect query terms', async () => {
+      const db = getDb();
+      const now = 1_700_000_650_000;
+      insertConversation(db, 'conv-entity-alias', now);
+      insertMessage(
+        db,
+        'msg-entity-alias',
+        'conv-entity-alias',
+        'user',
+        'Our team standard editor is Visual Studio Code.',
+        now,
+      );
+
+      insertItem(db, {
+        id: 'item-editor-vscode',
+        kind: 'preference',
+        subject: 'editor preference',
+        statement: 'Team standard editor is Visual Studio Code',
+        importance: 0.8,
+        firstSeenAt: now,
+      });
+      insertItemSource(db, 'item-editor-vscode', 'msg-entity-alias', now);
+
+      db.insert(memoryEntities).values({
+        id: 'entity-vscode',
+        name: 'Visual Studio Code',
+        type: 'tool',
+        aliases: JSON.stringify(['vscode']),
+        description: null,
+        firstSeenAt: now,
+        lastSeenAt: now,
+        mentionCount: 1,
+      }).run();
+      db.insert(memoryItemEntities).values({
+        memoryItemId: 'item-editor-vscode',
+        entityId: 'entity-vscode',
+      }).run();
+
+      const recall = await buildMemoryRecall('vscode debug setup', 'conv-entity-alias', TEST_CONFIG);
+      expect(recall.entityHits).toBeGreaterThan(0);
+      expect(recall.injectedText).toContain('Visual Studio Code');
+    });
+
+    test('relation expansion recalls neighbor-linked items when only seed entity is mentioned', async () => {
+      const db = getDb();
+      const now = 1_700_000_680_000;
+      insertConversation(db, 'conv-entity-rel', now);
+      insertMessage(
+        db,
+        'msg-entity-rel',
+        'conv-entity-rel',
+        'user',
+        'Project Atlas reliability playbook.',
+        now,
+      );
+
+      insertItem(db, {
+        id: 'item-k8s-hpa',
+        kind: 'fact',
+        subject: 'autoscaling strategy',
+        statement: 'Use Kubernetes horizontal pod autoscaling for sustained traffic spikes',
+        importance: 0.75,
+        firstSeenAt: now,
+      });
+      insertItemSource(db, 'item-k8s-hpa', 'msg-entity-rel', now);
+
+      db.insert(memoryEntities).values([
+        {
+          id: 'entity-atlas',
+          name: 'Project Atlas',
+          type: 'project',
+          aliases: JSON.stringify(['atlas']),
+          description: null,
+          firstSeenAt: now,
+          lastSeenAt: now,
+          mentionCount: 1,
+        },
+        {
+          id: 'entity-kubernetes',
+          name: 'Kubernetes',
+          type: 'tool',
+          aliases: JSON.stringify(['k8s']),
+          description: null,
+          firstSeenAt: now,
+          lastSeenAt: now,
+          mentionCount: 1,
+        },
+      ]).run();
+      db.insert(memoryEntityRelations).values({
+        id: 'rel-atlas-k8s',
+        sourceEntityId: 'entity-atlas',
+        targetEntityId: 'entity-kubernetes',
+        relation: 'uses',
+        evidence: 'Project Atlas runs on Kubernetes',
+        firstSeenAt: now,
+        lastSeenAt: now,
+      }).run();
+      db.insert(memoryItemEntities).values({
+        memoryItemId: 'item-k8s-hpa',
+        entityId: 'entity-kubernetes',
+      }).run();
+
+      const relationConfig = {
+        ...TEST_CONFIG,
+        memory: {
+          ...TEST_CONFIG.memory,
+          entity: {
+            ...TEST_CONFIG.memory.entity,
+            relationRetrieval: {
+              ...TEST_CONFIG.memory.entity.relationRetrieval,
+              enabled: true,
+              maxSeedEntities: 4,
+              maxNeighborEntities: 4,
+              maxEdges: 6,
+              neighborScoreMultiplier: 0.6,
+            },
+          },
+        },
+      };
+
+      const recall = await buildMemoryRecall(
+        'atlas reliability guidance',
+        'conv-entity-rel',
+        relationConfig,
+      );
+      expect(recall.entityHits).toBeGreaterThan(0);
+      expect(recall.injectedText).toContain('Kubernetes horizontal pod autoscaling');
+    });
+
+    test('direct preference evidence outranks weak relation-expanded noise', async () => {
+      const db = getDb();
+      const now = 1_700_000_690_000;
+      insertConversation(db, 'conv-rel-rank', now);
+      insertMessage(
+        db,
+        'msg-rel-rank',
+        'conv-rel-rank',
+        'user',
+        'For Project Atlas deployments, we prefer blue-green rollout strategy.',
+        now,
+      );
+      insertSegment(
+        db,
+        'seg-rel-rank',
+        'msg-rel-rank',
+        'conv-rel-rank',
+        'user',
+        'For Project Atlas deployments, we prefer blue-green rollout strategy.',
+        now,
+      );
+
+      insertItem(db, {
+        id: 'item-direct-pref',
+        kind: 'preference',
+        subject: 'deployment preference',
+        statement: 'Project Atlas deployment preference is blue-green rollouts',
+        importance: 0.95,
+        firstSeenAt: now,
+      });
+      insertItemSource(db, 'item-direct-pref', 'msg-rel-rank', now);
+
+      db.insert(memoryEntities).values({
+        id: 'entity-atlas-rank',
+        name: 'Project Atlas',
+        type: 'project',
+        aliases: JSON.stringify(['atlas']),
+        description: null,
+        firstSeenAt: now,
+        lastSeenAt: now,
+        mentionCount: 1,
+      }).run();
+      db.insert(memoryItemEntities).values({
+        memoryItemId: 'item-direct-pref',
+        entityId: 'entity-atlas-rank',
+      }).run();
+
+      for (let index = 1; index <= 8; index++) {
+        const entityId = `entity-noise-${index}`;
+        const itemId = `item-rel-noise-${index}`;
+        db.insert(memoryEntities).values({
+          id: entityId,
+          name: `AtlasTool${index}`,
+          type: 'tool',
+          aliases: JSON.stringify([`atlas-tool-${index}`]),
+          description: null,
+          firstSeenAt: now + index,
+          lastSeenAt: now + index,
+          mentionCount: 1,
+        }).run();
+        db.insert(memoryEntityRelations).values({
+          id: `rel-atlas-noise-${index}`,
+          sourceEntityId: 'entity-atlas-rank',
+          targetEntityId: entityId,
+          relation: 'uses',
+          evidence: `Project Atlas uses AtlasTool${index}`,
+          firstSeenAt: now + index,
+          lastSeenAt: now + index,
+        }).run();
+        insertItem(db, {
+          id: itemId,
+          kind: 'fact',
+          subject: `monitoring tool ${index}`,
+          statement: `ObservabilityTool${index} emits generic telemetry metrics`,
+          importance: 0.35,
+          firstSeenAt: now + index,
+        });
+        insertItemSource(db, itemId, 'msg-rel-rank', now + index);
+        db.insert(memoryItemEntities).values({
+          memoryItemId: itemId,
+          entityId,
+        }).run();
+      }
+
+      const relationConfig = {
+        ...TEST_CONFIG,
+        memory: {
+          ...TEST_CONFIG.memory,
+          retrieval: {
+            ...TEST_CONFIG.memory.retrieval,
+            semanticTopK: 10,
+          },
+          entity: {
+            ...TEST_CONFIG.memory.entity,
+            relationRetrieval: {
+              ...TEST_CONFIG.memory.entity.relationRetrieval,
+              enabled: true,
+              maxSeedEntities: 6,
+              maxNeighborEntities: 20,
+              maxEdges: 20,
+              neighborScoreMultiplier: 0.7,
+            },
+          },
+        },
+      };
+
+      const recall = await buildMemoryRecall(
+        'atlas deployment preference strategy',
+        'conv-rel-rank',
+        relationConfig,
+      );
+      const orderedKeys = recall.topCandidates.map((candidate) => candidate.key);
+      const directIndex = orderedKeys.indexOf('item:item-direct-pref');
+      const noiseIndices = orderedKeys
+        .map((key, index) => ({ key, index }))
+        .filter(({ key }) => key.startsWith('item:item-rel-noise-'))
+        .map(({ index }) => index);
+
+      expect(directIndex).toBeGreaterThanOrEqual(0);
+      expect(noiseIndices.length).toBeGreaterThan(0);
+      expect(noiseIndices.every((index) => index > directIndex)).toBe(true);
+      expect(noiseIndices.length).toBeLessThanOrEqual(4);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Precision@K helpers
+  // -------------------------------------------------------------------------
+
+  describe('precision@k assertions', () => {
+    test('assertPrecisionAtK passes when enough expected items are found', () => {
+      const text = 'item-a is here, item-b is here, item-c is here';
+      assertPrecisionAtK(text, ['item-a', 'item-b', 'item-c'], 3);
+      assertPrecisionAtK(text, ['item-a', 'item-b', 'item-c', 'item-d'], 3);
+    });
+
+    test('assertPrecisionAtK fails when too few expected items are found', () => {
+      const text = 'only item-a is here';
+      expect(() => {
+        assertPrecisionAtK(text, ['item-a', 'item-b', 'item-c'], 2, 'test-label');
+      }).toThrow(/precision@3 too low.*found 1\/3.*need at least 2.*Missing: item-b, item-c/);
+    });
+
+    test('precision@k guard for preference recall fixture', async () => {
+      const db = getDb();
+      const now = 1_700_000_700_000;
+      insertConversation(db, 'conv-pk', now);
+
+      const prefs = [
+        { msg: 'msg-pk-1', seg: 'seg-pk-1', text: 'I prefer dark mode over light mode' },
+        { msg: 'msg-pk-2', seg: 'seg-pk-2', text: 'I like using TypeScript for all projects' },
+        { msg: 'msg-pk-3', seg: 'seg-pk-3', text: 'I prefer tabs over spaces for indentation' },
+      ];
+
+      for (let i = 0; i < prefs.length; i++) {
+        const p = prefs[i]!;
+        const t = now + i * 1000;
+        insertMessage(db, p.msg, 'conv-pk', 'user', p.text, t);
+        insertSegment(db, p.seg, p.msg, 'conv-pk', 'user', p.text, t);
+      }
+
+      const recall = await buildMemoryRecall('what do I prefer', 'conv-pk', TEST_CONFIG);
+
+      // At least 2 of 3 preference segments should appear in recall
+      assertPrecisionAtK(
+        recall.injectedText,
+        ['dark mode', 'TypeScript', 'tabs over spaces'],
+        2,
+        'preference-recall',
+      );
+    });
+  });
+});