docs(external-memory): clarify profile slice merges into user-profile, not external-memory block

Author: Tehan

packages/plugin/src/features/magic-context/migrations-v39.test.ts

@@ -0,0 +1,62 @@
+/// <reference types="bun-types" />
+
+import { describe, expect, test } from "bun:test";
+import { Database } from "../../shared/sqlite";
+import { closeQuietly } from "../../shared/sqlite-helpers";
+import { LATEST_MIGRATION_VERSION, runMigrations } from "./migrations";
+import { initializeDatabase } from "./storage-db";
+
+function columnNames(db: Database, table: string): string[] {
+    return (db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>).map(
+        (column) => column.name,
+    );
+}
+
+describe("migration v39 — external recall snapshot + m[0] marker", () => {
+    test("adds external recall columns to session_meta on a fresh DB, idempotently", () => {
+        const db = new Database(":memory:");
+        try {
+            initializeDatabase(db);
+            runMigrations(db);
+            runMigrations(db);
+
+            const columns = columnNames(db, "session_meta");
+            expect(columns).toContain("external_recall_json");
+            expect(columns).toContain("external_recall_state");
+            expect(columns).toContain("external_recall_at");
+            expect(columns).toContain("cached_m0_external_recall_hash");
+            expect(
+                db
+                    .prepare("SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1")
+                    .get(),
+            ).toEqual({ version: LATEST_MIGRATION_VERSION });
+        } finally {
+            closeQuietly(db);
+        }
+    });
+
+    test("external recall columns store and round-trip nulls (default absent state)", () => {
+        const db = new Database(":memory:");
+        try {
+            initializeDatabase(db);
+            runMigrations(db);
+
+            db.prepare("INSERT INTO session_meta (session_id, harness) VALUES (?, ?)").run(
+                "ses_v39",
+                "test-harness",
+            );
+            const row = db
+                .prepare(
+                    "SELECT external_recall_json, external_recall_state, external_recall_at, cached_m0_external_recall_hash FROM session_meta WHERE session_id = ?",
+                )
+                .get("ses_v39") as Record<string, unknown>;
+
+            expect(row.external_recall_json).toBeNull();
+            expect(row.external_recall_state).toBeNull();
+            expect(row.external_recall_at).toBeNull();
+            expect(row.cached_m0_external_recall_hash).toBeNull();
+        } finally {
+            closeQuietly(db);
+        }
+    });
+});

packages/plugin/src/hooks/magic-context/inject-compartments.ts

@@ -1408,6 +1408,16 @@ function renderExternalItem(item: ExternalRecallSliceItem): string {
         : `- ${escapeXmlContent(item.content)}`;
 }
 
+/** Body of the <external-memory> block. INTENTIONALLY merges only the
+ *  `project` and `global` slices — the `profile` slice is omitted here by
+ *  design and is rendered separately into the <user-profile> block (see
+ *  `renderUserProfileBlock(..., externalRecall?.profile ?? [])` in `renderM0`).
+ *  Duplicating profile lines into <external-memory> would be redundant
+ *  (the model would see the same recall content twice) and would defeat
+ *  the user-profile budget trim that lives on that block. Note that the
+ *  sibling `renderExternalDeltaLines` (m[1] delta path) DOES include the
+ *  profile slice — there profile lines reconcile into <user-profile> at
+ *  the next HARD fold, per its own comment. */
 function renderExternalLines(snapshot: ExternalRecallSnapshot): string[] {
     const items: ExternalRecallSliceItem[] = [...snapshot.project, ...snapshot.global];
     const lines: string[] = [];
@@ -1504,6 +1514,11 @@ export function renderM0(args: {
 }): string {
     const sections: string[] = [];
     if (args.projectDocs.length > 0) sections.push(args.projectDocs);
+    // The external-recall PROFILE slice is merged HERE (into <user-profile>),
+    // not into <external-memory>. `renderExternalLines` deliberately emits
+    // only project + global — see its JSDoc for the rationale. Splitting the
+    // merge this way lets the user-profile budget trim govern recall-derived
+    // profile lines without inflating the sibling <external-memory> block.
     const userProfile = renderUserProfileBlock(
         trimUserMemoriesToBudget(
             args.userProfileBaseline,

packages/plugin/src/tools/ctx-search/tools.ts

@@ -184,34 +184,24 @@ function createCtxSearchTool(deps: CtxSearchToolDeps): ToolDefinition {
             const gitCommitsEnabled =
                 embeddingSnapshot?.gitCommitEnabled ?? deps.gitCommitsEnabled ?? false;
 
-            const results = await unifiedSearch(
-                deps.db,
-                searchSessionId,
-                projectPath,
-                query,
-                {
-                    limit: normalizeLimit(args.limit),
-                    memoryEnabled,
-                    embeddingEnabled,
-                    embedQuery: async (text, signal) => {
-                        const result = await embedTextForProject(
-                            projectPath,
-                            text,
-                            signal,
-                            "query",
-                        );
-                        return result?.vector ?? null;
-                    },
-                    isEmbeddingRuntimeEnabled: () => embeddingEnabled === true,
-                    readMessages: deps.readMessages,
-                    maxMessageOrdinal: messageOrdinalCutoff,
-                    gitCommitsEnabled,
-                    sources: normalizeSources(args.sources),
-                    visibleMemoryIds,
-                    // Explicit agent search → enable literal-probe multi-query
-                    // recall for symbol/command/path lookups. Auto-search hints
-                    // (the hot path) leave this off to protect their latency.
-                    explicitSearch: true,
+            const results = await unifiedSearch(deps.db, searchSessionId, projectPath, query, {
+                limit: normalizeLimit(args.limit),
+                memoryEnabled,
+                embeddingEnabled,
+                embedQuery: async (text, signal) => {
+                    const result = await embedTextForProject(projectPath, text, signal, "query");
+                    return result?.vector ?? null;
+                },
+                isEmbeddingRuntimeEnabled: () => embeddingEnabled === true,
+                readMessages: deps.readMessages,
+                maxMessageOrdinal: messageOrdinalCutoff,
+                gitCommitsEnabled,
+                sources: normalizeSources(args.sources),
+                visibleMemoryIds,
+                // Explicit agent search → enable literal-probe multi-query
+                // recall for symbol/command/path lookups. Auto-search hints
+                // (the hot path) leave this off to protect their latency.
+                explicitSearch: true,
                 // External bank resolution: basename is the human-readable label the
                 // engine uses as a bank template parameter, NOT a key. Project
                 // identity (resolveProjectPath's output) is the key.