perf: add embedding cache with FTS pre-filtering and scoped session read cache

#1: In-memory TTL embedding cache eliminates repeated blob
    deserialization. FTS pre-filtering narrows semantic candidates
    from O(N) to O(k) before cosine scoring. Cache invalidated
    on memory write/delete/update.

#7: Scoped raw-message cache (withRawSessionMessageCache) ensures
    compartment trigger evaluation loads OpenCode's message DB
    once instead of twice per evaluation. Cache is synchronous,
    try/finally scoped, and supports safe nesting.

Author: ualtinok

src/features/magic-context/memory/embedding-cache.test.ts

@@ -0,0 +1,58 @@
+/// <reference types="bun-types" />
+
+import { Database } from "bun:sqlite";
+import { afterEach, describe, expect, it } from "bun:test";
+import { initializeDatabase } from "../storage-db";
+import {
+    getProjectEmbeddings,
+    resetEmbeddingCacheForTests,
+    saveEmbedding,
+    setEmbeddingCacheTtlForTests,
+} from "./index";
+import { insertMemory } from "./storage-memory";
+
+let db: Database | null = null;
+
+function createTestDb(): Database {
+    const database = new Database(":memory:");
+    initializeDatabase(database);
+    return database;
+}
+
+function toNumbers(embedding: Float32Array | undefined): number[] {
+    return embedding ? Array.from(embedding) : [];
+}
+
+afterEach(() => {
+    resetEmbeddingCacheForTests();
+    db?.close(false);
+    db = null;
+});
+
+describe("embedding-cache", () => {
+    it("reloads project embeddings after TTL expiry", async () => {
+        db = createTestDb();
+        setEmbeddingCacheTtlForTests(10);
+
+        const memory = insertMemory(db, {
+            projectPath: "/repo/project",
+            category: "ARCHITECTURE_DECISIONS",
+            content: "Cache embeddings for memory search.",
+        });
+
+        saveEmbedding(db, memory.id, new Float32Array([1, 0]), "mock:model");
+
+        const initial = getProjectEmbeddings(db, "/repo/project");
+        expect(toNumbers(initial.get(memory.id))).toEqual([1, 0]);
+
+        saveEmbedding(db, memory.id, new Float32Array([0, 1]), "mock:model");
+
+        const beforeExpiry = getProjectEmbeddings(db, "/repo/project");
+        expect(toNumbers(beforeExpiry.get(memory.id))).toEqual([1, 0]);
+
+        await Bun.sleep(20);
+
+        const afterExpiry = getProjectEmbeddings(db, "/repo/project");
+        expect(toNumbers(afterExpiry.get(memory.id))).toEqual([0, 1]);
+    });
+});

src/features/magic-context/memory/embedding-cache.ts

@@ -0,0 +1,63 @@
+import type { Database } from "bun:sqlite";
+import { loadAllEmbeddings } from "./storage-memory-embeddings";
+
+interface ProjectEmbeddingCacheEntry {
+    embeddings: Map<number, Float32Array>;
+    expiresAt: number;
+}
+
+const DEFAULT_EMBEDDING_CACHE_TTL_MS = 60_000;
+
+const projectEmbeddingCache = new Map<string, ProjectEmbeddingCacheEntry>();
+
+let embeddingCacheTtlMs = DEFAULT_EMBEDDING_CACHE_TTL_MS;
+
+function getValidCacheEntry(projectPath: string): ProjectEmbeddingCacheEntry | null {
+    const entry = projectEmbeddingCache.get(projectPath);
+    if (!entry) {
+        return null;
+    }
+
+    if (entry.expiresAt <= Date.now()) {
+        projectEmbeddingCache.delete(projectPath);
+        return null;
+    }
+
+    return entry;
+}
+
+export function getProjectEmbeddings(db: Database, projectPath: string): Map<number, Float32Array> {
+    const cached = getValidCacheEntry(projectPath);
+    if (cached) {
+        return cached.embeddings;
+    }
+
+    const embeddings = loadAllEmbeddings(db, projectPath);
+    projectEmbeddingCache.set(projectPath, {
+        embeddings,
+        expiresAt: Date.now() + embeddingCacheTtlMs,
+    });
+    return embeddings;
+}
+
+export function peekProjectEmbeddings(projectPath: string): Map<number, Float32Array> | null {
+    return getValidCacheEntry(projectPath)?.embeddings ?? null;
+}
+
+export function invalidateProject(projectPath: string): void {
+    projectEmbeddingCache.delete(projectPath);
+}
+
+export function invalidateMemory(projectPath: string, memoryId: number): void {
+    const cached = getValidCacheEntry(projectPath);
+    cached?.embeddings.delete(memoryId);
+}
+
+export function resetEmbeddingCacheForTests(): void {
+    projectEmbeddingCache.clear();
+    embeddingCacheTtlMs = DEFAULT_EMBEDDING_CACHE_TTL_MS;
+}
+
+export function setEmbeddingCacheTtlForTests(ttlMs: number): void {
+    embeddingCacheTtlMs = Math.max(0, Math.floor(ttlMs));
+}

src/features/magic-context/memory/index.ts

@@ -1,6 +1,7 @@
 export * from "./constants";
 export * from "./embedding";
 export * from "./embedding-backfill";
+export * from "./embedding-cache";
 export * from "./normalize-hash";
 export { resolveProjectIdentity } from "./project-identity";
 export { promoteSessionFactsToMemory } from "./promotion";

src/features/magic-context/memory/storage-memory.test.ts

@@ -11,9 +11,11 @@ import {
     getMemoryByHash,
     getMemoryById,
     getMemoryCount,
+    getProjectEmbeddings,
     getStoredModelId,
     insertMemory,
     loadAllEmbeddings,
+    resetEmbeddingCacheForTests,
     saveEmbedding,
     searchMemoriesFTS,
     updateMemoryContent,
@@ -85,6 +87,7 @@ function makeMemoryDatabase(): Database {
 }
 
 afterEach(() => {
+    resetEmbeddingCacheForTests();
     if (db) {
         db.close(false);
     }
@@ -233,6 +236,46 @@ describe("storage-memory", () => {
             expect(updated?.normalizedHash).toBe(computeNormalizedHash("cache_ttl=10m"));
             expect(loadAllEmbeddings(db, "/repo/project")).toEqual(new Map());
         });
+
+        it("#when cache-sensitive writes occur #then embedding cache invalidates updated project entries", () => {
+            db = makeMemoryDatabase();
+
+            const memory = insertMemory(db, {
+                projectPath: "/repo/project",
+                category: "CONFIG_DEFAULTS",
+                content: "cache_ttl=5m",
+            });
+            saveEmbedding(db, memory.id, new Float32Array([0.1, 0.2]), "local:model-a");
+
+            const initialCache = getProjectEmbeddings(db, "/repo/project");
+            expect(Array.from(initialCache.get(memory.id) ?? [])).toEqual(
+                Array.from(new Float32Array([0.1, 0.2])),
+            );
+
+            updateMemoryContent(
+                db,
+                memory.id,
+                "cache_ttl=10m",
+                computeNormalizedHash("cache_ttl=10m"),
+            );
+
+            const cacheAfterUpdate = getProjectEmbeddings(db, "/repo/project");
+            expect(cacheAfterUpdate.has(memory.id)).toBeFalse();
+
+            const secondMemory = insertMemory(db, {
+                projectPath: "/repo/project",
+                category: "CONFIG_DEFAULTS",
+                content: "cache_ttl=15m",
+            });
+            saveEmbedding(db, secondMemory.id, new Float32Array([0.3, 0.4]), "local:model-a");
+
+            const cacheAfterInsert = getProjectEmbeddings(db, "/repo/project");
+            expect(Array.from(cacheAfterInsert.keys())).toEqual([secondMemory.id]);
+
+            deleteMemory(db, secondMemory.id);
+
+            expect(getProjectEmbeddings(db, "/repo/project")).toEqual(new Map());
+        });
     });
 
     describe("#given FTS search", () => {

src/features/magic-context/memory/storage-memory.ts

@@ -1,4 +1,5 @@
 import type { Database } from "bun:sqlite";
+import { invalidateMemory, invalidateProject } from "./embedding-cache";
 import { computeNormalizedHash } from "./normalize-hash";
 import type {
     Memory,
@@ -373,6 +374,8 @@ export function insertMemory(db: Database, input: MemoryInput): Memory {
     if (!inserted) {
         throw new Error("Failed to load inserted memory row");
     }
+
+    invalidateProject(input.projectPath);
     return inserted;
 }
 
@@ -467,6 +470,8 @@ export function updateMemoryContent(
     content: string,
     normalizedHash: string,
 ): void {
+    const memory = getMemoryById(db, id);
+
     db.transaction(() => {
         getUpdateMemoryContentStatement(db).run(content, normalizedHash, Date.now(), id);
 
@@ -480,6 +485,10 @@ export function updateMemoryContent(
         }
         stmt.run(id);
     })();
+
+    if (memory) {
+        invalidateMemory(memory.projectPath, id);
+    }
 }
 
 export function supersededMemory(db: Database, id: number, supersededById: number): void {
@@ -524,10 +533,16 @@ export function archiveMemory(db: Database, id: number, reason?: string): void {
 }
 
 export function deleteMemory(db: Database, id: number): void {
+    const memory = getMemoryById(db, id);
+
     db.transaction(() => {
         getDeleteMemoryEmbeddingStatement(db).run(id);
         getDeleteMemoryStatement(db).run(id);
     })();
+
+    if (memory) {
+        invalidateProject(memory.projectPath);
+    }
 }
 
 export function getMemoryCount(db: Database, projectPath?: string): number {

src/features/magic-context/search.test.ts

@@ -11,7 +11,7 @@ const rawMessagesBySession = new Map<
 >();
 
 import { replaceSessionFacts } from "./compartment-storage";
-import { getMemoryById, insertMemory, saveEmbedding } from "./memory";
+import { getMemoryById, insertMemory, resetEmbeddingCacheForTests, saveEmbedding } from "./memory";
 import { unifiedSearch } from "./search";
 import { initializeDatabase } from "./storage-db";
 
@@ -32,6 +32,7 @@ afterEach(() => {
     queryEmbedding = null;
     embeddingQueries.length = 0;
     rawMessagesBySession.clear();
+    resetEmbeddingCacheForTests();
 });
 
 describe("unifiedSearch", () => {
@@ -187,4 +188,38 @@ describe("unifiedSearch", () => {
             }),
         ).toEqual([]);
     });
+
+    it("falls back to full semantic search when FTS finds no matches", async () => {
+        const memory = insertMemory(db, {
+            projectPath: "/repo/project",
+            category: "ARCHITECTURE_DECISIONS",
+            content: "alpha beta gamma",
+        });
+        saveEmbedding(db, memory.id, new Float32Array([0, 1]), "mock:model");
+        queryEmbedding = new Float32Array([0, 1]);
+
+        const results = await unifiedSearch(
+            db,
+            "ses-semantic",
+            "/repo/project",
+            "vector-only query",
+            {
+                limit: 5,
+                memoryEnabled: true,
+                embeddingEnabled: true,
+                readMessages,
+                embedQuery,
+                isEmbeddingRuntimeEnabled,
+            },
+        );
+
+        const memoryResults = results.filter(
+            (result): result is Extract<(typeof results)[number], { source: "memory" }> =>
+                result.source === "memory",
+        );
+
+        expect(memoryResults).toHaveLength(1);
+        expect(memoryResults[0]?.memoryId).toBe(memory.id);
+        expect(memoryResults[0]?.matchType).toBe("semantic");
+    });
 });