om-memory-system 5.2.0 → 5.4.0

package/dist/services/settings-snapshot.js

@@ -5,7 +5,8 @@ import { CONFIG, getGlobalConfigSourcePath } from "../config.js";
 import { hasUnexpiredApiToken } from "./api-tokens.js";
 import { resolveClaudeFolder } from "./claude-folder.js";
 import { readGlobalConfigRevision } from "./global-config-writer.js";
-import { getMemoryLimitRule, MEMORY_LIMIT_SETTINGS, } from "../utils/memory-limits.js";
+import { injectionOptionsFromFile } from "./injection-options-config.js";
+import { getMemoryLimitRule, MEMORY_LIMIT_SETTINGS } from "../utils/memory-limits.js";
 import { getAutoCaptureProviderStatus, isExternalModelReady, resolveClaudeCodeLiveModel, resolvePiLiveModel, } from "./ai/live-model-choice.js";
 const editable = [
     "opencodeProvider",
@@ -37,8 +38,20 @@ const editable = [
     "skillLearning",
     "skillLearningRedact",
     "skillFolders",
+    "openingContext",
+    "openingContextQuery",
+    "subagentMemory",
+    "compaction.enabled",
     ...MEMORY_LIMIT_SETTINGS,
 ];
+/**
+ * The memory injection settings (change align-recall-host-parity). They are
+ * global-only on the page, so each shows the global file's value read with the
+ * runtime rules, never the runtime value, which can hold a project's.
+ */
+const injectionKeys = ["openingContext", "openingContextQuery", "subagentMemory"];
+/** `DEFAULTS.compaction.enabled` in src/config.ts. */
+const COMPACTION_ENABLED_DEFAULT = true;
 /** Keys a project config cannot override, so the page always shows the global value. */
 const globalOnly = [
     "captureRetryRetentionHours",
@@ -77,14 +90,14 @@ function projectFile(directory) {
         .find((path) => existsSync(path));
 }
 /**
- * Snapshot entry for a nested limit (chatMessage.maxMemories). The runtime
- * merge is shallow, so a project chatMessage object replaces the global one:
- * a missing count means the default even when the global file sets a value,
- * and the source must not be inferred from dotted-key presence alone.
+ * Snapshot entry for a nested setting (chatMessage.maxMemories, compaction.*).
+ * The runtime merge is shallow, so a project chatMessage object replaces the
+ * global one: a missing count means the default even when the global file sets
+ * a value, and the source must not be inferred from dotted-key presence alone.
  */
-function nestedMemorySetting(rule, global, project) {
-    const parent = rule.path[0];
-    const leaf = rule.path[1];
+function nestedSetting(path, defaultValue, global, project) {
+    const parent = path[0];
+    const leaf = path[1];
     const container = (source) => {
         const raw = source[parent];
         return raw && typeof raw === "object" && !Array.isArray(raw)
@@ -97,10 +110,10 @@ function nestedMemorySetting(rule, global, project) {
     const hasValue = effective !== undefined && Object.hasOwn(effective, leaf);
     const hasGlobal = globalContainer !== undefined && Object.hasOwn(globalContainer, leaf);
     return {
-        value: hasValue ? effective[leaf] : rule.default,
+        value: hasValue ? effective[leaf] : defaultValue,
         source: hasValue ? (projectHasParent ? "project" : "global") : "default",
-        globalValue: hasGlobal ? globalContainer[leaf] : rule.default,
-        default: rule.default,
+        globalValue: hasGlobal ? globalContainer[leaf] : defaultValue,
+        default: defaultValue,
         // Whether the leaf exists in the global file: the Reset action needs it.
         hasGlobal,
     };
@@ -111,10 +124,29 @@ export function getSettingsSnapshot(directory) {
     // Dotted limit identifiers (chatMessage.maxMemories) are resolved by the
     // nested rule above, so the runtime lookup only handles flat keys.
     const runtime = CONFIG;
+    const injection = injectionOptionsFromFile(global);
+    const injectionDefaults = injectionOptionsFromFile({});
     const settings = Object.fromEntries(editable.map((key) => {
         const limitRule = getMemoryLimitRule(key);
         if (limitRule && limitRule.path.length > 1) {
-            return [key, nestedMemorySetting(limitRule, global, project)];
+            return [key, nestedSetting(limitRule.path, limitRule.default, global, project)];
+        }
+        if (key === "compaction.enabled") {
+            return [key, nestedSetting(key.split("."), COMPACTION_ENABLED_DEFAULT, global, project)];
+        }
+        const injectionKey = injectionKeys.find((name) => name === key);
+        if (injectionKey) {
+            const hasGlobal = Object.hasOwn(global, key);
+            return [
+                key,
+                {
+                    value: injection[injectionKey],
+                    source: hasGlobal ? "global" : "default",
+                    globalValue: injection[injectionKey],
+                    default: injectionDefaults[injectionKey],
+                    hasGlobal,
+                },
+            ];
         }
         const projectOverrides = Object.hasOwn(project, key) &&
             // A project may turn these off, never on.

package/dist/services/single-flight.d.ts

@@ -0,0 +1,2 @@
+/** Like setInterval, but skips a tick while the previous run of the task is still pending. */
+export declare function setSingleFlightInterval(task: () => Promise<void>, ms: number): NodeJS.Timeout;

package/dist/services/single-flight.js

@@ -0,0 +1,12 @@
+/** Like setInterval, but skips a tick while the previous run of the task is still pending. */
+export function setSingleFlightInterval(task, ms) {
+    let running = false;
+    return setInterval(() => {
+        if (running)
+            return;
+        running = true;
+        void task().finally(() => {
+            running = false;
+        });
+    }, ms);
+}

package/dist/services/visible-recall-config.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The `visibleRecall` setting (change add-opencode-v2-visible-recall), kept out
+ * of `src/config.ts` to save its lines. Pure on purpose: callers pass the file
+ * config and a log function, and the loaded `CONFIG` is never imported here,
+ * because many tests stub `src/config.js`.
+ *
+ * Read the effective value from `CONFIG.visibleRecall`. It is on by default,
+ * and only an explicit `false` turns it off. It applies to OpenCode, Pi and
+ * Claude Code.
+ */
+/**
+ * The key as it appears in a config file. `OmmsConfig` in `src/config.ts` has
+ * no field for it, to save lines, so the functions take `FileConfigWithKey`,
+ * which any config object satisfies. A hand-edited file can hold any value,
+ * which is why they compare with `=== false`.
+ */
+export interface VisibleRecallFileKey {
+    /**
+     * Draw a row in the OpenCode TUI, the Pi terminal and the Claude Code reply for each memory
+     * recall. On Claude Code the hook marks each injected section when rows are off, because the
+     * recall rows read only the injected text. Default true. A project can only turn it off.
+     */
+    visibleRecall?: boolean;
+}
+type FileConfigWithKey = VisibleRecallFileKey & object;
+/** Read the setting from a merged file config. Unset means on. */
+export declare function visibleRecallFromFile(fileConfig: FileConfigWithKey): {
+    visibleRecall: boolean;
+};
+/**
+ * Apply the project rule to `overrides`, the copy of the project config that
+ * is merged over the global one. A project may turn the rows off, so a value
+ * of `false` stays. Any other project value is dropped, so the global value
+ * decides. A project value of `true` is also reported through `log`.
+ */
+export declare function applyProjectVisibleRecall(project: FileConfigWithKey, overrides: FileConfigWithKey, directory: string, log: (message: string, data: {
+    directory: string;
+}) => void): void;
+export {};

package/dist/services/visible-recall-config.js

@@ -0,0 +1,28 @@
+/**
+ * The `visibleRecall` setting (change add-opencode-v2-visible-recall), kept out
+ * of `src/config.ts` to save its lines. Pure on purpose: callers pass the file
+ * config and a log function, and the loaded `CONFIG` is never imported here,
+ * because many tests stub `src/config.js`.
+ *
+ * Read the effective value from `CONFIG.visibleRecall`. It is on by default,
+ * and only an explicit `false` turns it off. It applies to OpenCode, Pi and
+ * Claude Code.
+ */
+/** Read the setting from a merged file config. Unset means on. */
+export function visibleRecallFromFile(fileConfig) {
+    return { visibleRecall: fileConfig.visibleRecall !== false };
+}
+/**
+ * Apply the project rule to `overrides`, the copy of the project config that
+ * is merged over the global one. A project may turn the rows off, so a value
+ * of `false` stays. Any other project value is dropped, so the global value
+ * decides. A project value of `true` is also reported through `log`.
+ */
+export function applyProjectVisibleRecall(project, overrides, directory, log) {
+    if (project.visibleRecall === false)
+        return;
+    delete overrides.visibleRecall;
+    if (project.visibleRecall === true) {
+        log("Project config cannot turn on visibleRecall; the value was ignored", { directory });
+    }
+}

package/dist/services/web-server.d.ts

@@ -48,6 +48,7 @@ export declare class WebServer {
     private holdOffTimer;
     private portsExhaustedNotified;
     private takeoverFailures;
+    private lastHealthFailure;
     private readonly maxFallbackPort;
     private settingsImportJobs?;
     private backfillControlsInstance?;
@@ -99,6 +100,8 @@ export declare class WebServer {
     isRunning(): boolean;
     isServerOwner(): boolean;
     getUrl(): string;
+    /** Why the last `checkServerAvailable` call said no, or null when it said yes. */
+    getLastHealthFailure(): string | null;
     checkServerAvailable(): Promise<boolean>;
     private handleRequest;
     private contentTypeFor;

package/dist/services/web-server.js

@@ -13,10 +13,13 @@ import { AUTH_HEADER, getOrCreateAuthToken, isAuthorizedApiRequest } from "./aut
 import { WebAuth } from "./web-auth.js";
 import { NODE_HTTP_IDLE_TIMEOUT_MS } from "./request-timeouts.js";
 import { testReranker } from "./reranker-test.js";
+import { setSingleFlightInterval } from "./single-flight.js";
 import { handleListTags, handleListKeywords, handleListMemories, handleAddMemory, handleDeleteMemory, handleBulkDelete, handleUpdateMemory, handleSearch, handleStats, handlePinMemory, handleUnpinMemory, handleRunCleanup, handleRunDeduplication, handleDetectMigration, handleRunMigration, handleDetectTagMigration, handleRunTagMigrationBatch, handleGetTagMigrationProgress, handleDeletePrompt, handleBulkDeletePrompts, handleGetUserProfile, handleGetProfileChangelog, handleGetProfileSnapshot, handleRefreshProfile, handleUpdateProfileItem, } from "./api-handlers.js";
 import { routeModules } from "./web-route-modules.js";
 const isBun = typeof globalThis.Bun !== "undefined";
 const MIN_FAILED_TAKEOVERS = 3;
+/** A busy owner can answer late. Two seconds was short enough to call a live owner dead. */
+const HEALTH_CHECK_TIMEOUT_MS = 8_000;
 export function attachNodeDisconnectHandlers(req, res, onDisconnect) {
     let disconnected = false;
     const disconnectOnce = () => {
@@ -175,6 +178,7 @@ export class WebServer {
     holdOffTimer = null;
     portsExhaustedNotified = false;
     takeoverFailures = 0;
+    lastHealthFailure = null;
     maxFallbackPort;
     settingsImportJobs;
     backfillControlsInstance;
@@ -584,7 +588,7 @@ export class WebServer {
         if (this.healthCheckInterval) {
             return;
         }
-        this.healthCheckInterval = setInterval(() => void this.waiterTick(), 5000);
+        this.healthCheckInterval = setSingleFlightInterval(() => this.waiterTick(), 5000);
     }
     /** One check of a web app that waits for the port. */
     async waiterTick() {
@@ -667,6 +671,8 @@ export class WebServer {
             log("Web server port held by a non-responsive process; falling back to next port", {
                 previousPort: this.config.port,
                 newPort: nextPort,
+                lastFailure: this.lastHealthFailure,
+                healthTimeoutMs: HEALTH_CHECK_TIMEOUT_MS,
             }, "warn");
             this.config.port = nextPort;
         }
@@ -743,6 +749,10 @@ export class WebServer {
     getUrl() {
         return webServerUrl(this.config.host, this.config.port);
     }
+    /** Why the last `checkServerAvailable` call said no, or null when it said yes. */
+    getLastHealthFailure() {
+        return this.lastHealthFailure;
+    }
     async checkServerAvailable() {
         try {
             // Only a web app on this machine answers here, so the local token file is enough.
@@ -751,20 +761,28 @@ export class WebServer {
             const response = await fetch(`${this.getUrl()}${endpoint}`, {
                 method: "GET",
                 headers,
-                signal: AbortSignal.timeout(2000),
+                signal: AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS),
             });
-            if (!response.ok)
+            if (!response.ok) {
+                this.lastHealthFailure = `http ${response.status}`;
                 return false;
+            }
             // Fallback spans 10 neighbor ports; any 2xx from an unrelated local
             // service must not be mistaken for an omms owner. Require the
             // response to carry our API envelope.
             const body = (await response.json());
-            if (endpoint === "/api/health") {
-                return body.success === true && body.status === "ok";
-            }
-            return body.success === true;
+            const ok = body.success === true && (endpoint !== "/api/health" || body.status === "ok");
+            this.lastHealthFailure = ok ? null : "unexpected response";
+            return ok;
         }
-        catch {
+        catch (error) {
+            const name = error instanceof Error ? error.name : "";
+            this.lastHealthFailure =
+                name === "TimeoutError"
+                    ? "timeout"
+                    : error instanceof Error
+                        ? error.message
+                        : String(error);
             return false;
         }
     }

package/dist/utils/memory-limits.d.ts

@@ -21,8 +21,9 @@ export declare const MEMORY_LIMITS: {
     readonly userProfileMaxContextBytes: MemoryLimitRule;
     readonly retrievalMaxTokens: MemoryLimitRule;
     readonly similarityThreshold: MemoryLimitRule;
+    readonly "compaction.memoryLimit": MemoryLimitRule;
 };
-/** The six settings identifiers, in Memory card order. */
+/** The settings identifiers: the six Memory card limits in card order, then the restore limit. */
 export declare const MEMORY_LIMIT_SETTINGS: readonly string[];
 export declare function getMemoryLimitRule(setting: string): MemoryLimitRule | undefined;
 /**

package/dist/utils/memory-limits.js

@@ -1,6 +1,8 @@
 /**
- * Shared validation rules for the six memory-limit settings
- * (openspec change memory-context-controls). Pure functions only: values
+ * Shared validation rules for the six memory-limit settings of the Memory
+ * card (openspec change memory-context-controls), and the restore limit
+ * `compaction.memoryLimit`, which the Memory injection section edits
+ * (change align-recall-host-parity). Pure functions only: values
  * are passed in, so config.ts, the settings writer, and the settings
  * snapshot share one rule set without importing CONFIG. Do not import
  * CONFIG here: many tests stub src/config.js with a partial module.
@@ -26,8 +28,9 @@ export const MEMORY_LIMITS = {
     userProfileMaxContextBytes: rule("userProfileMaxContextBytes", ["userProfileMaxContextBytes"], 32768, "UTF-8 bytes", "integers from 1024 to 16777216", integerInRange(1024, 16777216)),
     retrievalMaxTokens: rule("retrievalMaxTokens", ["retrievalMaxTokens"], 2000, "approximate tokens", "integers from 256 to 65536", integerInRange(256, 65536)),
     similarityThreshold: rule("similarityThreshold", ["similarityThreshold"], 0.6, "similarity score", "numbers from 0 to 1", decimalFrom0To1, defaultSimilarityThreshold),
+    "compaction.memoryLimit": rule("compaction.memoryLimit", ["compaction", "memoryLimit"], 10, "memories", "positive safe integers", isPositiveSafeInteger),
 };
-/** The six settings identifiers, in Memory card order. */
+/** The settings identifiers: the six Memory card limits in card order, then the restore limit. */
 export const MEMORY_LIMIT_SETTINGS = Object.keys(MEMORY_LIMITS);
 const RULES = MEMORY_LIMITS;
 export function getMemoryLimitRule(setting) {

package/dist/v2/adapter.d.ts

@@ -2,4 +2,6 @@ import type { Context } from "@opencode/plugin/promise/plugin";
 import type { V2MemoryBridge } from "./memory-bridge.js";
 /** Per-session state is bounded so long-running servers cannot grow it without limit. */
 export declare const MAX_TRACKED_SESSIONS = 256;
+/** Session ids remembered as already seen by this process, for the first-prompt rule. */
+export declare const MAX_SEEN_SESSIONS = 500;
 export declare function registerV2Adapter(ctx: Context, legacy: any, memory: V2MemoryBridge): Promise<() => Promise<void>>;

package/dist/v2/adapter.js

@@ -4,6 +4,8 @@ import { SKILLS_TOOL_INPUT_SCHEMA } from "../core/skills-tool.js";
 import { log } from "../services/logger.js";
 import { utf8ByteLength } from "../utils/context-limit.js";
 import { eventBelongsToLocation, legacyToolResult, toLegacyEvent } from "./legacy-client.js";
+import { createRecallReporter } from "./recall-reporter.js";
+import { createSessionParents } from "./session-parent.js";
 const memoryInput = {
     type: "object",
     properties: {
@@ -40,14 +42,21 @@ const memoryInput = {
 };
 /** Per-session state is bounded so long-running servers cannot grow it without limit. */
 export const MAX_TRACKED_SESSIONS = 256;
+/** Session ids remembered as already seen by this process, for the first-prompt rule. */
+export const MAX_SEEN_SESSIONS = 500;
 /** Unadmitted prompts kept per session before the oldest is dropped. */
 const MAX_PENDING_PROMPTS = 16;
 /** Compaction is restored natively through the `compaction` hook, never via the V1 event path. */
 const COMPACTION_EVENT_TYPES = new Set(["session.compacted", "session.compaction.ended"]);
-function setBounded(map, key, value) {
+const NO_SECTIONS = {
+    promptSection: null,
+    openingSection: null,
+    openingQuery: null,
+};
+function setBounded(map, key, value, limit = MAX_TRACKED_SESSIONS) {
     map.delete(key);
     map.set(key, value);
-    while (map.size > MAX_TRACKED_SESSIONS) {
+    while (map.size > limit) {
         const oldest = map.keys().next().value;
         if (oldest === undefined)
             break;
@@ -70,12 +79,23 @@ function deletedSessionID(event) {
 export async function registerV2Adapter(ctx, legacy, memory) {
     const retrievals = new Map();
     const restored = new Map();
+    // Sessions this process has seen a prompt or compaction for. The first prompt of a session not
+    // in it is a first prompt (new session) or a resume, decided in the context hook.
+    const seen = new Map();
+    // Per session whose first request is still to come: ids of the prompts this process admitted.
+    const firstPending = new Map();
     const messageIDs = new Map();
     // The prompt hook runs before OpenCode admits a prompt, so prompts wait here
     // until their message appears in a model request's history (the context
     // hook), and are only then recorded for auto-capture and profile learning.
     const pendingPrompts = new Map();
+    const parents = createSessionParents(ctx, setBounded);
+    const recall = await createRecallReporter(ctx, memory, setBounded, parents);
     const forgetSession = (sessionID) => {
+        recall.forget(sessionID);
+        parents.forget(sessionID);
+        seen.delete(sessionID);
+        firstPending.delete(sessionID);
         retrievals.delete(sessionID);
         restored.delete(sessionID);
         messageIDs.delete(sessionID);
@@ -108,11 +128,47 @@ export async function registerV2Adapter(ctx, legacy, memory) {
     // reuses the same section, even if the search finishes after the timeout.
     const settledRetrieval = async (retrieval) => {
         if (!retrieval.settled) {
-            const value = await withTimeout(retrieval.promise, memory.retrievalTimeoutMs, null);
+            const value = await withTimeout(retrieval.promise, memory.retrievalTimeoutMs, NO_SECTIONS);
             retrieval.settled ??= { value };
         }
         return retrieval.settled.value;
     };
+    // Load the session's own memories once; the restored section is formatted when a request
+    // emits it, against that request's captured budget. Each load gets a new object, which keys
+    // its one row.
+    const loadRestored = async (sessionID, timeoutMs) => {
+        try {
+            const loading = memory.restoreSession(sessionID);
+            const memories = await (timeoutMs === undefined
+                ? loading
+                : withTimeout(loading, timeoutMs, null));
+            if (memories)
+                setBounded(restored, sessionID, { memories });
+            else
+                restored.delete(sessionID);
+        }
+        catch (error) {
+            log("v2 restore: failed to load session memories", { sessionID, error: String(error) }, "error");
+        }
+    };
+    // The first request of a session's first prompt in this process decides new or resumed:
+    // an earlier user message in the history means resumed.
+    const decideFirstRequest = async (sessionID, messages, retrieval) => {
+        const ours = firstPending.get(sessionID);
+        if (!firstPending.delete(sessionID))
+            return;
+        // History is a user message with an id that none of this process's prompts own.
+        const earlier = messages.some((message) => message.role === "user" && typeof message.id === "string" && !ours?.has(message.id));
+        if (!earlier)
+            return;
+        if (retrieval)
+            retrieval.resumed = true;
+        if (!memory.isCompactionEnabled())
+            return;
+        const subagent = await withTimeout(parents.isSubagent(sessionID), memory.retrievalTimeoutMs, false);
+        if (!subagent)
+            await loadRestored(sessionID, memory.retrievalTimeoutMs);
+    };
     // Each V1 tool becomes a direct V2 tool, like OpenCode's own read/grep/skill, not a
     // Code Mode catalog entry, so the model can always see and call it (as on V1 and Pi).
     const legacyTool = (name, input) => ({
@@ -178,15 +234,36 @@ export async function registerV2Adapter(ctx, legacy, memory) {
             ].slice(-MAX_PENDING_PROMPTS);
             setBounded(pendingPrompts, sessionID, pending);
         }
-        if (!memory.isInjectionEnabled() || !text.trim())
+        if (!text.trim())
+            return;
+        const first = !seen.has(sessionID);
+        if (first) {
+            setBounded(seen, sessionID, true, MAX_SEEN_SESSIONS);
+            setBounded(firstPending, sessionID, new Set());
+        }
+        firstPending.get(sessionID)?.add(event.messageID);
+        if (!memory.isInjectionEnabled())
+            return;
+        // A subagent session gets the prompt recall only when `subagentMemory` is on, and never the
+        // opening section. A failed or slow lookup counts as a root session.
+        const subagent = await withTimeout(parents.isSubagent(sessionID), memory.retrievalTimeoutMs, false);
+        if (subagent && !memory.isSubagentMemoryEnabled())
             return;
         // Start the search now with the entry snapshot, so it overlaps prompt admission.
         // An edit during retrieval must not change this request's allowance.
-        const promise = memory.retrieve(text, sessionID, budgetBytes).catch((error) => {
+        const search = async () => first && !subagent
+            ? memory.retrieveFirstPrompt(text, sessionID, budgetBytes)
+            : { ...NO_SECTIONS, promptSection: await memory.retrieve(text, sessionID, budgetBytes) };
+        const promise = search().catch((error) => {
             log("v2 prompt: memory retrieval failed", { sessionID, error: String(error) }, "error");
-            return null;
+            return NO_SECTIONS;
+        });
+        setBounded(retrievals, sessionID, {
+            promise,
+            budgetBytes,
+            query: text,
+            openingToken: {},
         });
-        setBounded(retrievals, sessionID, { promise, budgetBytes });
     });
     await ctx.session.hook("context", async (event) => {
         const sessionID = event.sessionID;
@@ -194,24 +271,31 @@ export async function registerV2Adapter(ctx, legacy, memory) {
         const budgetBytes = retrieval?.budgetBytes ?? memory.snapshotRequestBudget();
         // Before chat.params, which stores the model on the recorded prompt row.
         await recordAdmittedPrompts(sessionID, event.messages);
-        // The retrieval and the restored section share one request budget: the
+        await decideFirstRequest(sessionID, event.messages, retrieval);
+        // The retrieval sections and the restored section share one request budget: the
         // restored section is formatted here, within what the retrieval left.
         let remainingBytes = null;
         if (retrieval) {
-            const section = await settledRetrieval(retrieval);
-            if (section) {
-                event.system.push({ type: "text", text: section });
-                remainingBytes = retrieval.budgetBytes - utf8ByteLength(section);
+            const { promptSection, openingSection, openingQuery } = await settledRetrieval(retrieval);
+            remainingBytes = retrieval.budgetBytes;
+            if (promptSection) {
+                event.system.push({ type: "text", text: promptSection });
+                recall.record(sessionID, retrieval, "search", retrieval.query, promptSection);
+                remainingBytes -= utf8ByteLength(promptSection);
             }
-            else {
-                remainingBytes = retrieval.budgetBytes;
+            if (openingSection && !retrieval.resumed) {
+                event.system.push({ type: "text", text: openingSection });
+                recall.record(sessionID, retrieval.openingToken, "opening", openingQuery, openingSection);
+                remainingBytes -= utf8ByteLength(openingSection);
             }
         }
-        const restoredMemories = restored.get(sessionID);
-        if (restoredMemories) {
-            const section = memory.formatRestoredSession(restoredMemories, remainingBytes ?? budgetBytes);
-            if (section)
+        const restoredEntry = restored.get(sessionID);
+        if (restoredEntry) {
+            const section = memory.formatRestoredSession(restoredEntry.memories, remainingBytes ?? budgetBytes);
+            if (section) {
                 event.system.push({ type: "text", text: section });
+                recall.record(sessionID, restoredEntry, "restore", null, section);
+            }
         }
         if (legacy["chat.params"]) {
             await legacy["chat.params"]({
@@ -222,21 +306,12 @@ export async function registerV2Adapter(ctx, legacy, memory) {
     });
     await ctx.session.hook("compaction", async (event) => {
         memory.snapshotRequestBudget();
+        const sessionID = event.sessionID;
+        setBounded(seen, sessionID, true, MAX_SEEN_SESSIONS);
+        firstPending.delete(sessionID);
         if (!memory.isCompactionEnabled())
             return;
-        const sessionID = event.sessionID;
-        try {
-            // Load once here; the restored section is formatted when a request
-            // emits it, against that request's captured budget.
-            const memories = await memory.restoreSession(sessionID);
-            if (memories)
-                setBounded(restored, sessionID, memories);
-            else
-                restored.delete(sessionID);
-        }
-        catch (error) {
-            log("v2 compaction: failed to load session memories", { sessionID, error: String(error) }, "error");
-        }
+        await loadRestored(sessionID);
     });
     const controller = new AbortController();
     const watcher = (async () => {
@@ -266,6 +341,10 @@ export async function registerV2Adapter(ctx, legacy, memory) {
         restored.clear();
         messageIDs.clear();
         pendingPrompts.clear();
+        seen.clear();
+        firstPending.clear();
+        parents.clear();
+        recall.clear();
         await legacy.dispose?.();
     };
 }

package/dist/v2/legacy-client.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
+import { markInProcessClient } from "../adapters/opencode/in-process-client.js";
 function textFromParts(parts = []) {
     return parts
         .filter((part) => part.type === "text")
@@ -216,7 +217,7 @@ export function createLegacyClient(ctx) {
             },
         },
     };
-    return client;
+    return markInProcessClient(client);
 }
 export function legacyToolResult(value) {
     if (typeof value === "string")

package/dist/v2/memory-bridge.d.ts

@@ -1,3 +1,9 @@
+/** The sections of a session's first prompt. `openingQuery` is the query the opening search used. */
+export interface FirstPromptSections {
+    promptSection: string | null;
+    openingSection: string | null;
+    openingQuery: string | null;
+}
 /**
  * The memory operations the native OpenCode v2 hooks need, bound to the
  * plugin's location. Kept separate from the adapter so hook wiring can be
@@ -8,6 +14,10 @@ export interface V2MemoryBridge {
     isConfigured(): boolean;
     isInjectionEnabled(): boolean;
     isCompactionEnabled(): boolean;
+    /** Effective `visibleRecall` setting for this project, from a fresh config read. */
+    isVisibleRecallEnabled(): boolean;
+    /** Effective `subagentMemory` setting, from the config the last budget snapshot read. */
+    isSubagentMemoryEnabled(): boolean;
     isInternalPrompt(sessionID: string, text: string): boolean;
     recordPrompt(sessionID: string, messageID: string, text: string): Promise<void>;
     /**
@@ -18,6 +28,11 @@ export interface V2MemoryBridge {
     snapshotRequestBudget(): number;
     /** Wrapped per-prompt retrieval section packed within `budgetBytes`, or null when nothing is relevant. */
     retrieve(prompt: string, sessionID: string, budgetBytes: number): Promise<string | null>;
+    /**
+     * The first prompt of a main session: the prompt section plus the opening section when the
+     * option is on. The prompt section equals what `retrieve` returns for the same budget.
+     */
+    retrieveFirstPrompt(prompt: string, sessionID: string, budgetBytes: number): Promise<FirstPromptSections>;
     /** The session's own memories for restore after compaction, loaded once, or null. */
     restoreSession(sessionID: string): Promise<unknown[] | null>;
     /** Cached restored memories formatted within `budgetBytes`, or null when nothing fits. */

package/dist/v2/memory-bridge.js

@@ -1,6 +1,7 @@
 import { CONFIG, isConfigured, refreshConfigIfChanged } from "../config.js";
 import { buildRetrievalSection, formatMemoriesForCompaction, retrievalWrapperBytes, wrapRetrievalSection, } from "../core/retrieval.js";
 import { DEFAULT_RETRIEVAL_MAX_TOKENS, tokensToByteCeiling } from "../core/context-budget.js";
+import { buildFirstPromptSections, openingQueryFor } from "../core/opening-context.js";
 import { isInternalPrompt, recordUserPrompt } from "../adapters/opencode/user-prompt.js";
 import { memoryClient } from "../services/client.js";
 import { V2_RETRIEVAL_TIMEOUT_MS } from "../services/request-timeouts.js";
@@ -11,6 +12,11 @@ export function createV2MemoryBridge(directory) {
         isConfigured,
         isInjectionEnabled: () => isConfigured() && Boolean(CONFIG.chatMessage.enabled),
         isCompactionEnabled: () => isConfigured() && Boolean(CONFIG.compaction.enabled),
+        isVisibleRecallEnabled() {
+            refreshConfigIfChanged(directory);
+            return CONFIG.visibleRecall !== false;
+        },
+        isSubagentMemoryEnabled: () => CONFIG.subagentMemory !== false,
         isInternalPrompt,
         async recordPrompt(sessionID, messageID, text) {
             await recordUserPrompt(sessionID, messageID, directory, text);
@@ -28,6 +34,21 @@ export function createV2MemoryBridge(directory) {
             });
             return section ? wrapRetrievalSection(section) : null;
         },
+        async retrieveFirstPrompt(prompt, sessionID, budgetBytes) {
+            const openingQuery = openingQueryFor({
+                openingContext: CONFIG.openingContext,
+                openingContextQuery: CONFIG.openingContextQuery,
+            });
+            const sections = await buildFirstPromptSections({
+                prompt,
+                openingQuery,
+                directory,
+                sessionId: sessionID,
+                budget: { maxBytes: budgetBytes, wrapperBytes: retrievalWrapperBytes() },
+                openingReserveBytes: 0,
+            });
+            return { ...sections, openingQuery };
+        },
         async restoreSession(sessionID) {
             const tags = getTags(directory);
             const result = await memoryClient.searchMemoriesBySessionID(sessionID, tags.project.tag, CONFIG.compaction.memoryLimit);