tlc-claude-code 1.8.5 → 2.0.1

package/server/lib/semantic-recall.js

@@ -0,0 +1,242 @@
+/**
+ * Semantic Recall — searches and ranks memory results using vector similarity,
+ * recency decay, and project relevance.
+ *
+ * Scoring formula:
+ *   combinedScore = vectorSimilarity * 0.5 + recency * 0.25 + projectRelevance * 0.25
+ *   Permanent memories receive a 1.2x boost on the combined score.
+ *   Recency uses exponential decay with a 7-day half-life.
+ *
+ * @module semantic-recall
+ */
+
+/** Weight for vector similarity in the combined score */
+const SIMILARITY_WEIGHT = 0.5;
+
+/** Weight for recency in the combined score */
+const RECENCY_WEIGHT = 0.25;
+
+/** Weight for project relevance in the combined score */
+const PROJECT_RELEVANCE_WEIGHT = 0.25;
+
+/** Boost multiplier for permanent memories */
+const PERMANENT_BOOST = 1.2;
+
+/** Half-life for recency decay in days */
+const RECENCY_HALF_LIFE_DAYS = 7;
+
+/** Minimum results before auto-widening from project to workspace scope */
+const AUTO_WIDEN_THRESHOLD = 3;
+
+/** Default maximum number of results to return */
+const DEFAULT_LIMIT = 10;
+
+/** Default number of results for context injection */
+const CONTEXT_INJECTION_LIMIT = 5;
+
+/**
+ * Calculate recency score using exponential decay with 7-day half-life.
+ * Returns 1.0 for very recent timestamps, decaying toward 0 for older ones.
+ *
+ * @param {number} timestamp - Unix timestamp in milliseconds
+ * @returns {number} Recency score between 0 and 1
+ */
+function calculateRecency(timestamp) {
+  const now = Date.now();
+  const ageMs = Math.max(0, now - timestamp);
+  const ageDays = ageMs / (24 * 60 * 60 * 1000);
+  return Math.exp(-ageDays * Math.LN2 / RECENCY_HALF_LIFE_DAYS);
+}
+
+/**
+ * Calculate the combined score for a memory result.
+ *
+ * @param {object} result - Raw vector store result
+ * @param {object} context - Current context with projectId
+ * @returns {number} Combined score
+ */
+function calculateScore(result, context) {
+  const vectorSimilarity = result.similarity || 0;
+  const recency = calculateRecency(result.timestamp);
+  const projectRelevance = result.project === context.projectId ? 1.0 : 0.0;
+
+  let score = vectorSimilarity * SIMILARITY_WEIGHT
+    + recency * RECENCY_WEIGHT
+    + projectRelevance * PROJECT_RELEVANCE_WEIGHT;
+
+  if (result.permanent) {
+    score *= PERMANENT_BOOST;
+  }
+
+  return score;
+}
+
+/**
+ * Apply scope-based filtering to raw results.
+ *
+ * @param {Array} results - Scored results
+ * @param {string} scope - 'project', 'workspace', or 'global'
+ * @param {object} context - Current context
+ * @returns {Array} Filtered results
+ */
+function filterByScope(results, scope, context) {
+  if (scope === 'global') {
+    return results;
+  }
+
+  if (scope === 'workspace') {
+    return results.filter((r) => r._raw.workspace === context.workspace);
+  }
+
+  // scope === 'project'
+  const projectFiltered = results.filter((r) => r._raw.project === context.projectId);
+
+  // Auto-widen to workspace if too few project-scoped results
+  // Only widen if the workspace scope actually provides enough results
+  if (projectFiltered.length < AUTO_WIDEN_THRESHOLD) {
+    const workspaceFiltered = results.filter((r) => r._raw.workspace === context.workspace);
+    if (workspaceFiltered.length >= AUTO_WIDEN_THRESHOLD) {
+      return workspaceFiltered;
+    }
+  }
+
+  return projectFiltered;
+}
+
+/**
+ * Deduplicate results by id, keeping only the entry with the highest score.
+ *
+ * @param {Array} results - Scored results (may contain duplicate ids)
+ * @returns {Array} Deduplicated results
+ */
+function deduplicateById(results) {
+  const bestById = new Map();
+
+  for (const result of results) {
+    const existing = bestById.get(result.id);
+    if (!existing || result.score > existing.score) {
+      bestById.set(result.id, result);
+    }
+  }
+
+  return [...bestById.values()];
+}
+
+/**
+ * Transform a raw vector store result into the public result shape.
+ *
+ * @param {object} raw - Raw result from vector store
+ * @param {number} score - Calculated combined score
+ * @returns {object} Public result object
+ */
+function toPublicResult(raw, score) {
+  return {
+    id: raw.id,
+    text: raw.text,
+    score,
+    type: raw.type,
+    source: {
+      project: raw.project,
+      workspace: raw.workspace,
+      branch: raw.branch,
+      sourceFile: raw.sourceFile,
+    },
+    date: raw.timestamp,
+    permanent: raw.permanent || false,
+  };
+}
+
+/**
+ * Create a semantic recall instance for searching and ranking memory results.
+ *
+ * @param {object} deps - Dependencies
+ * @param {object} deps.vectorStore - Vector store for similarity search
+ * @param {object} deps.embeddingClient - Client for generating embeddings
+ * @returns {object} Object with recall and recallForContext methods
+ */
+export function createSemanticRecall({ vectorStore, embeddingClient }) {
+  /**
+   * Perform a semantic search with scoring, filtering, and deduplication.
+   *
+   * @param {string} query - Search query text
+   * @param {object} context - Current context
+   * @param {string} context.projectId - Current project identifier
+   * @param {string} context.workspace - Current workspace path
+   * @param {string} [context.branch] - Current branch name
+   * @param {Array} [context.touchedFiles] - Recently touched files
+   * @param {object} [options] - Search options
+   * @param {string} [options.scope='project'] - Search scope: 'project', 'workspace', or 'global'
+   * @param {number} [options.limit=10] - Maximum number of results
+   * @param {number} [options.minScore] - Minimum vector similarity threshold
+   * @param {Array<string>} [options.types] - Filter to specific memory types
+   * @returns {Promise<Array>} Scored and ranked results
+   */
+  async function recall(query, context, options = {}) {
+    if (!query || query.length === 0) {
+      return [];
+    }
+
+    const embedding = await embeddingClient.embed(query);
+    if (!embedding) {
+      return [];
+    }
+
+    const {
+      scope = 'project',
+      limit = DEFAULT_LIMIT,
+      minScore,
+      types,
+    } = options;
+
+    const rawResults = vectorStore.search({ embedding, limit: limit * 3 });
+
+    // Score all raw results and attach the raw data for filtering
+    let scored = rawResults.map((raw) => {
+      const score = calculateScore(raw, context);
+      return { ...toPublicResult(raw, score), _raw: raw };
+    });
+
+    // Filter by type if specified
+    if (types && types.length > 0) {
+      scored = scored.filter((r) => types.includes(r.type));
+    }
+
+    // Apply scope filtering (including auto-widening)
+    scored = filterByScope(scored, scope, context);
+
+    // Deduplicate by id
+    scored = deduplicateById(scored);
+
+    // Filter by minimum vector similarity score
+    if (minScore !== undefined) {
+      scored = scored.filter((r) => r._raw.similarity >= minScore);
+    }
+
+    // Sort descending by score
+    scored.sort((a, b) => b.score - a.score);
+
+    // Apply limit
+    scored = scored.slice(0, limit);
+
+    // Strip internal _raw property before returning
+    return scored.map(({ _raw, ...rest }) => rest);
+  }
+
+  /**
+   * Convenience method for context injection — returns top 5 memories
+   * relevant to the given project root and context.
+   *
+   * @param {string} projectRoot - Project root path used as query basis
+   * @param {object} context - Current context
+   * @returns {Promise<Array>} Top 5 results sorted by score
+   */
+  async function recallForContext(projectRoot, context) {
+    const query = context.projectId
+      ? `${context.projectId} project context`
+      : projectRoot;
+
+    return recall(query, context, { limit: CONTEXT_INJECTION_LIMIT });
+  }
+
+  return { recall, recallForContext };
+}

package/server/lib/semantic-recall.test.js

@@ -0,0 +1,446 @@
+/**
+ * Semantic Recall Tests
+ * Tests for semantically searching and ranking memory results
+ * using vector similarity, recency, and project relevance.
+ *
+ * Scoring formula:
+ *   vectorSimilarity * 0.5 + recency * 0.25 + projectRelevance * 0.25
+ *   Permanent memories boosted 1.2x
+ *   Deduplication by id (keep highest score)
+ */
+
+import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+import { createSemanticRecall } from './semantic-recall.js';
+
+/**
+ * Creates a mock embedding client that returns deterministic embeddings.
+ * @returns {object} Mock embedding client with vi.fn() methods
+ */
+function createMockEmbeddingClient() {
+  return {
+    embed: vi.fn().mockResolvedValue(new Float32Array(1024).fill(0.5)),
+    embedBatch: vi.fn().mockResolvedValue([]),
+    isAvailable: vi.fn().mockResolvedValue(true),
+    getModelInfo: () => ({ model: 'mxbai-embed-large', dimensions: 1024 }),
+  };
+}
+
+/**
+ * Creates a mock vector store that tracks all search calls.
+ * @returns {object} Mock vector store with vi.fn() methods
+ */
+function createMockVectorStore() {
+  return {
+    insert: vi.fn(),
+    search: vi.fn().mockReturnValue([]),
+    delete: vi.fn(),
+    count: vi.fn().mockReturnValue(0),
+    rebuild: vi.fn(),
+    getAll: vi.fn().mockReturnValue([]),
+    close: vi.fn(),
+  };
+}
+
+/**
+ * Creates a mock search result entry.
+ * @param {object} overrides - Properties to override
+ * @returns {object} A mock search result
+ */
+function createMockResult(overrides = {}) {
+  return {
+    id: 'mem-1',
+    text: 'Use Postgres for production',
+    type: 'decision',
+    project: 'my-project',
+    workspace: '/ws',
+    branch: 'main',
+    timestamp: Date.now() - 86400000, // 1 day ago
+    sourceFile: 'decisions/use-postgres.md',
+    permanent: false,
+    similarity: 0.92,
+    ...overrides,
+  };
+}
+
+describe('semantic-recall', () => {
+  let mockVectorStore;
+  let mockEmbeddingClient;
+  let recall;
+
+  beforeEach(() => {
+    mockVectorStore = createMockVectorStore();
+    mockEmbeddingClient = createMockEmbeddingClient();
+    recall = createSemanticRecall({
+      vectorStore: mockVectorStore,
+      embeddingClient: mockEmbeddingClient,
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('recall', () => {
+    it('returns semantically similar results for a query', async () => {
+      const mockResults = [
+        createMockResult({ id: 'mem-1', text: 'Use Postgres for production', similarity: 0.92 }),
+        createMockResult({ id: 'mem-2', text: 'Postgres JSONB for flexible schema', similarity: 0.85 }),
+      ];
+      mockVectorStore.search.mockReturnValue(mockResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recall('database choice', context);
+
+      expect(results).toHaveLength(2);
+      expect(results[0]).toHaveProperty('id');
+      expect(results[0]).toHaveProperty('text');
+      expect(results[0]).toHaveProperty('score');
+      expect(results[0]).toHaveProperty('type');
+      expect(results[0]).toHaveProperty('source');
+      expect(results[0]).toHaveProperty('date');
+      expect(results[0]).toHaveProperty('permanent');
+      expect(mockEmbeddingClient.embed).toHaveBeenCalledWith('database choice');
+      expect(mockVectorStore.search).toHaveBeenCalled();
+    });
+
+    it('sorts results by combined score highest first', async () => {
+      // mem-1: high similarity but old (low recency)
+      // mem-2: moderate similarity but recent (high recency)
+      // mem-3: low similarity, same project (high project relevance)
+      const now = Date.now();
+      const mockResults = [
+        createMockResult({
+          id: 'mem-1',
+          text: 'Old but relevant',
+          similarity: 0.95,
+          timestamp: now - 30 * 86400000, // 30 days ago
+          project: 'other-project',
+        }),
+        createMockResult({
+          id: 'mem-2',
+          text: 'Recent and moderately relevant',
+          similarity: 0.70,
+          timestamp: now - 3600000, // 1 hour ago
+          project: 'my-project',
+        }),
+        createMockResult({
+          id: 'mem-3',
+          text: 'Medium all around',
+          similarity: 0.80,
+          timestamp: now - 7 * 86400000, // 7 days ago
+          project: 'my-project',
+        }),
+      ];
+      mockVectorStore.search.mockReturnValue(mockResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recall('something', context);
+
+      expect(results).toHaveLength(3);
+      // Results should be sorted descending by combined score
+      for (let i = 0; i < results.length - 1; i++) {
+        expect(results[i].score).toBeGreaterThanOrEqual(results[i + 1].score);
+      }
+    });
+
+    it('filters to current project only with project scope', async () => {
+      const mockResults = [
+        createMockResult({ id: 'mem-1', project: 'my-project', similarity: 0.90 }),
+        createMockResult({ id: 'mem-2', project: 'other-project', similarity: 0.88 }),
+      ];
+      mockVectorStore.search.mockReturnValue(mockResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recall('query', context, { scope: 'project' });
+
+      // Only results matching the current project should be returned
+      const projectIds = results.map((r) => r.source?.project || r.id);
+      expect(results.length).toBeLessThanOrEqual(mockResults.length);
+      // Every result should belong to 'my-project'
+      results.forEach((r) => {
+        // The result set should not contain 'other-project' entries
+        expect(r.id).not.toBe('mem-2');
+      });
+    });
+
+    it('includes workspace-level memories with workspace scope', async () => {
+      const mockResults = [
+        createMockResult({ id: 'mem-1', project: 'my-project', workspace: '/ws', similarity: 0.90 }),
+        createMockResult({ id: 'mem-2', project: 'other-project', workspace: '/ws', similarity: 0.85 }),
+        createMockResult({ id: 'mem-3', project: 'outside-project', workspace: '/other-ws', similarity: 0.80 }),
+      ];
+      mockVectorStore.search.mockReturnValue(mockResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recall('query', context, { scope: 'workspace' });
+
+      // Should include mem-1 and mem-2 (same workspace) but not mem-3 (different workspace)
+      const ids = results.map((r) => r.id);
+      expect(ids).toContain('mem-1');
+      expect(ids).toContain('mem-2');
+      expect(ids).not.toContain('mem-3');
+    });
+
+    it('searches everything with global scope (no project/workspace filter)', async () => {
+      const mockResults = [
+        createMockResult({ id: 'mem-1', project: 'project-a', workspace: '/ws-a', similarity: 0.90 }),
+        createMockResult({ id: 'mem-2', project: 'project-b', workspace: '/ws-b', similarity: 0.85 }),
+        createMockResult({ id: 'mem-3', project: 'project-c', workspace: '/ws-c', similarity: 0.80 }),
+      ];
+      mockVectorStore.search.mockReturnValue(mockResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recall('query', context, { scope: 'global' });
+
+      // All results should be present regardless of project or workspace
+      expect(results).toHaveLength(3);
+      const ids = results.map((r) => r.id);
+      expect(ids).toContain('mem-1');
+      expect(ids).toContain('mem-2');
+      expect(ids).toContain('mem-3');
+    });
+
+    it('auto-widens from project to workspace when few results (<3)', async () => {
+      // First call (project scope) returns only 2 results
+      // Second call (widened to workspace) returns more
+      const projectResults = [
+        createMockResult({ id: 'mem-1', project: 'my-project', workspace: '/ws', similarity: 0.90 }),
+      ];
+      const workspaceResults = [
+        createMockResult({ id: 'mem-1', project: 'my-project', workspace: '/ws', similarity: 0.90 }),
+        createMockResult({ id: 'mem-2', project: 'other-project', workspace: '/ws', similarity: 0.85 }),
+        createMockResult({ id: 'mem-3', project: 'other-project', workspace: '/ws', similarity: 0.80 }),
+      ];
+
+      // The store returns all results; filtering happens in recall
+      // On first pass with project scope only 1 matches, so it widens
+      mockVectorStore.search.mockReturnValue(workspaceResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      // Default scope is 'project', which should auto-widen
+      const results = await recall.recall('query', context, { scope: 'project' });
+
+      // After auto-widening, should have more than the 1 project-only result
+      expect(results.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it('boosts permanent memories by 1.2x', async () => {
+      const now = Date.now();
+      const mockResults = [
+        createMockResult({
+          id: 'mem-ephemeral',
+          text: 'Ephemeral memory',
+          similarity: 0.90,
+          permanent: false,
+          timestamp: now - 86400000,
+          project: 'my-project',
+        }),
+        createMockResult({
+          id: 'mem-permanent',
+          text: 'Permanent memory',
+          similarity: 0.90,
+          permanent: true,
+          timestamp: now - 86400000,
+          project: 'my-project',
+        }),
+      ];
+      mockVectorStore.search.mockReturnValue(mockResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recall('query', context, { scope: 'global' });
+
+      const ephemeral = results.find((r) => r.id === 'mem-ephemeral');
+      const permanent = results.find((r) => r.id === 'mem-permanent');
+
+      expect(ephemeral).toBeDefined();
+      expect(permanent).toBeDefined();
+      // Permanent should have a higher score due to the 1.2x boost
+      expect(permanent.score).toBeGreaterThan(ephemeral.score);
+    });
+
+    it('respects minScore threshold', async () => {
+      const mockResults = [
+        createMockResult({ id: 'mem-high', similarity: 0.95, project: 'my-project' }),
+        createMockResult({ id: 'mem-mid', similarity: 0.60, project: 'my-project' }),
+        createMockResult({ id: 'mem-low', similarity: 0.20, project: 'my-project' }),
+      ];
+      mockVectorStore.search.mockReturnValue(mockResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recall('query', context, { minScore: 0.5, scope: 'global' });
+
+      // All returned results should have a combined score >= 0.5
+      results.forEach((r) => {
+        expect(r.score).toBeGreaterThanOrEqual(0.5);
+      });
+      // The low-similarity result should be filtered out
+      const ids = results.map((r) => r.id);
+      expect(ids).not.toContain('mem-low');
+    });
+
+    it('respects limit option', async () => {
+      const mockResults = [
+        createMockResult({ id: 'mem-1', similarity: 0.95, project: 'my-project' }),
+        createMockResult({ id: 'mem-2', similarity: 0.90, project: 'my-project' }),
+        createMockResult({ id: 'mem-3', similarity: 0.85, project: 'my-project' }),
+        createMockResult({ id: 'mem-4', similarity: 0.80, project: 'my-project' }),
+        createMockResult({ id: 'mem-5', similarity: 0.75, project: 'my-project' }),
+      ];
+      mockVectorStore.search.mockReturnValue(mockResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recall('query', context, { limit: 2, scope: 'global' });
+
+      expect(results).toHaveLength(2);
+    });
+
+    it('falls back to empty results when vector store returns nothing and embedding fails', async () => {
+      mockVectorStore.search.mockReturnValue([]);
+      mockEmbeddingClient.embed.mockResolvedValue(null);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recall('some query', context);
+
+      expect(results).toEqual([]);
+    });
+
+    it('deduplicates overlapping results by id keeping highest score', async () => {
+      const now = Date.now();
+      const mockResults = [
+        createMockResult({
+          id: 'mem-dup',
+          text: 'Duplicate entry version A',
+          similarity: 0.90,
+          timestamp: now - 86400000,
+          project: 'my-project',
+        }),
+        createMockResult({
+          id: 'mem-dup',
+          text: 'Duplicate entry version B',
+          similarity: 0.70,
+          timestamp: now - 3600000,
+          project: 'my-project',
+        }),
+        createMockResult({
+          id: 'mem-unique',
+          text: 'Unique entry',
+          similarity: 0.80,
+          timestamp: now - 86400000,
+          project: 'my-project',
+        }),
+      ];
+      mockVectorStore.search.mockReturnValue(mockResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recall('query', context, { scope: 'global' });
+
+      // Should only have 2 unique ids
+      const ids = results.map((r) => r.id);
+      const uniqueIds = [...new Set(ids)];
+      expect(uniqueIds).toHaveLength(2);
+      expect(ids).toHaveLength(2);
+
+      // The duplicate should keep the higher-scoring version
+      const dupResult = results.find((r) => r.id === 'mem-dup');
+      expect(dupResult).toBeDefined();
+      // The one with similarity 0.90 should win
+      expect(dupResult.text).toBe('Duplicate entry version A');
+    });
+
+    it('returns empty results for an empty query', async () => {
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recall('', context);
+
+      expect(results).toEqual([]);
+      // Should not call the vector store or embedding client for empty queries
+      expect(mockVectorStore.search).not.toHaveBeenCalled();
+      expect(mockEmbeddingClient.embed).not.toHaveBeenCalled();
+    });
+
+    it('calculates combined score correctly using the formula', async () => {
+      // Score = vectorSimilarity * 0.5 + recency * 0.25 + projectRelevance * 0.25
+      // We need to verify the math with known values
+      const now = Date.now();
+      const mockResults = [
+        createMockResult({
+          id: 'mem-verify',
+          text: 'Verify scoring',
+          similarity: 0.80,
+          // Very recent: recency should be close to 1.0
+          timestamp: now - 60000, // 1 minute ago
+          project: 'my-project', // Same project as context: projectRelevance = 1.0
+          permanent: false,
+        }),
+      ];
+      mockVectorStore.search.mockReturnValue(mockResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recall('scoring test', context, { scope: 'global' });
+
+      expect(results).toHaveLength(1);
+      const result = results[0];
+
+      // vectorSimilarity = 0.80, recency ~= 1.0 (very recent), projectRelevance = 1.0
+      // Expected score ~= 0.80 * 0.5 + 1.0 * 0.25 + 1.0 * 0.25 = 0.40 + 0.25 + 0.25 = 0.90
+      // Allow some tolerance for recency calculation (timestamp-based)
+      expect(result.score).toBeGreaterThan(0.85);
+      expect(result.score).toBeLessThanOrEqual(1.0);
+    });
+
+    it('filters by type when types option is provided', async () => {
+      const mockResults = [
+        createMockResult({ id: 'mem-decision', type: 'decision', similarity: 0.90, project: 'my-project' }),
+        createMockResult({ id: 'mem-convo', type: 'conversation', similarity: 0.88, project: 'my-project' }),
+        createMockResult({ id: 'mem-gotcha', type: 'gotcha', similarity: 0.85, project: 'my-project' }),
+      ];
+      mockVectorStore.search.mockReturnValue(mockResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+
+      // Filter to only decisions
+      const decisionsOnly = await recall.recall('query', context, {
+        types: ['decision'],
+        scope: 'global',
+      });
+      expect(decisionsOnly.every((r) => r.type === 'decision')).toBe(true);
+      expect(decisionsOnly).toHaveLength(1);
+
+      // Filter to decisions and conversations
+      const mixed = await recall.recall('query', context, {
+        types: ['decision', 'conversation'],
+        scope: 'global',
+      });
+      expect(mixed.every((r) => ['decision', 'conversation'].includes(r.type))).toBe(true);
+      expect(mixed).toHaveLength(2);
+    });
+  });
+
+  describe('recallForContext', () => {
+    it('returns top-K results for context injection with default of 5', async () => {
+      const now = Date.now();
+      const mockResults = [];
+      for (let i = 0; i < 10; i++) {
+        mockResults.push(
+          createMockResult({
+            id: `mem-${i}`,
+            text: `Memory entry ${i}`,
+            similarity: 0.95 - i * 0.05,
+            timestamp: now - i * 86400000,
+            project: 'my-project',
+          })
+        );
+      }
+      mockVectorStore.search.mockReturnValue(mockResults);
+
+      const context = { projectId: 'my-project', workspace: '/ws', branch: 'main', touchedFiles: [] };
+      const results = await recall.recallForContext('/path/to/project', context);
+
+      // Default top-K should be 5
+      expect(results).toHaveLength(5);
+      // Results should be sorted by score descending
+      for (let i = 0; i < results.length - 1; i++) {
+        expect(results[i].score).toBeGreaterThanOrEqual(results[i + 1].score);
+      }
+    });
+  });
+});