om-memory-system 5.3.0 → 5.4.0

package/dist/services/global-config-writer.js

@@ -8,6 +8,7 @@ import { isValidClaudeConfigDir } from "./claude-folder.js";
 import { missingSkillFolder } from "./skill-learning/skill-config.js";
 import { KEYWORD_MODES } from "../utils/keyword-boost.js";
 import { getMemoryLimitRule } from "../utils/memory-limits.js";
+import { OPENING_CONTEXT_QUERY_MAX_LENGTH } from "./injection-options-config.js";
 import { RERANKER_TIMEOUT_MAX_MS, RERANKER_TIMEOUT_MIN_MS } from "./request-timeouts.js";
 const keys = new Set([
     "opencodeProvider",
@@ -47,6 +48,11 @@ const keys = new Set([
     "skillLearning",
     "skillLearningRedact",
     "skillFolders",
+    "openingContext",
+    "openingContextQuery",
+    "subagentMemory",
+    "compaction.enabled",
+    "compaction.memoryLimit",
 ]);
 function isFolder(path) {
     try {
@@ -83,10 +89,18 @@ export function isSecretReference(value) {
 /** Reranker keys that a null edit removes, the same wire form as a limit reset. */
 const OPTIONAL_RERANKER_KEYS = ["rerankerApiUrl", "rerankerModel", "rerankerApiKey"];
 /** Other keys whose `null` edit removes them, so they follow the default again. */
-const RESETTABLE_KEYS = ["keywordMode", "skillFolders"];
+const RESETTABLE_KEYS = [
+    "keywordMode",
+    "skillFolders",
+    "openingContextQuery",
+    "openingContext",
+    "subagentMemory",
+    "compaction.enabled",
+];
+const QUERY_RULE = `openingContextQuery must be text of ${OPENING_CONTEXT_QUERY_MAX_LENGTH} characters or fewer`;
 function isValidEdit(key, value) {
     // `undefined` removes the key from the file. `null` is the wire form of
-    // "reset to default", accepted for the six memory limits and the optional reranker keys.
+    // "reset to default", accepted for the memory limits and the optional reranker keys.
     const memoryLimit = getMemoryLimitRule(key);
     if (memoryLimit && value === null)
         return true;
@@ -98,6 +112,11 @@ function isValidEdit(key, value) {
     // keywordMode: null removes the key, so the mode follows the default again.
     if (key === "keywordMode")
         return value === null || KEYWORD_MODES.includes(value);
+    // The opening context query: null removes it; an empty query means no opening search.
+    if (key === "openingContextQuery") {
+        return (value === null ||
+            (typeof value === "string" && value.trim().length <= OPENING_CONTEXT_QUERY_MAX_LENGTH));
+    }
     // The five opt-in reranker keys (openspec retrieval-threshold-and-reranker).
     if (key === "rerankerEnabled")
         return typeof value === "boolean";
@@ -133,8 +152,12 @@ function isValidEdit(key, value) {
         key === "webServerAutoStart" ||
         key === "userProfileAutoCleanupEnabled" ||
         key === "skillLearning" ||
-        key === "skillLearningRedact") {
-        return typeof value === "boolean";
+        key === "skillLearningRedact" ||
+        key === "openingContext" ||
+        key === "subagentMemory" ||
+        key === "compaction.enabled") {
+        // The three memory injection switches take null too: it removes the key (reset to default).
+        return typeof value === "boolean" || (value === null && RESETTABLE_KEYS.includes(key));
     }
     // Path rules are checked by the startup validation below; existence just after this check.
     if (key === "skillFolders") {
@@ -160,8 +183,8 @@ function isValidEdit(key, value) {
     // Entries are checked by the startup validation below.
     if (key === "importPathMaps" || key === "importIgnoredDirectories")
         return Array.isArray(value);
-    // The five memory limits share one validation rule set (six with
-    // similarityThreshold; null means reset, handled above).
+    // The memory limits share one validation rule set (similarityThreshold and
+    // compaction.memoryLimit included; null means reset, handled above).
     if (memoryLimit)
         return memoryLimit.isValid(value);
     // An empty value clears the field.
@@ -218,11 +241,13 @@ options = {}) {
             };
             throw new Error(["memoryApiKey", "embeddingApiKey", "webServerAuthPassword", "rerankerApiKey"].includes(key)
                 ? `${key} must be an env:// or file:// reference`
-                : memoryRule
-                    ? `Invalid ${key} setting: accepted ${memoryRule.accepted}`
-                    : rerankerAccepted[key]
-                        ? `Invalid ${key} setting: accepted ${rerankerAccepted[key]}`
-                        : `Invalid ${key} setting`);
+                : key === "openingContextQuery"
+                    ? QUERY_RULE
+                    : memoryRule
+                        ? `Invalid ${key} setting: accepted ${memoryRule.accepted}`
+                        : rerankerAccepted[key]
+                            ? `Invalid ${key} setting: accepted ${rerankerAccepted[key]}`
+                            : `Invalid ${key} setting`);
         }
         const missing = key === "skillFolders" && value !== null
             ? missingSkillFolder(value, isFolder)
@@ -246,9 +271,9 @@ options = {}) {
         }
         let content = original.content;
         for (const [key, value] of Object.entries(edits)) {
-            // A nested limit identifier maps to its JSONC leaf path, so
-            // chatMessage.maxMemories writes the leaf, never a literal dotted key.
-            const jsoncPath = (getMemoryLimitRule(key)?.path ?? [key]);
+            // A nested identifier maps to its JSONC leaf path, so chatMessage.maxMemories
+            // and compaction.enabled write the leaf, never a literal dotted key.
+            const jsoncPath = (getMemoryLimitRule(key)?.path ?? key.split("."));
             // null is the wire form of "reset to default": remove the key so the
             // value follows the default again (undefined removes in jsonc modify).
             const jsoncValue = value === null &&

package/dist/services/injection-options-config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The memory injection settings (change align-recall-host-parity): the opening
+ * context and subagent memory, on OpenCode V2, Pi and Claude Code. Kept out of
+ * `src/config.ts` to save its lines. Pure on purpose, like
+ * `visible-recall-config.ts`: 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 values from `CONFIG.openingContext`,
+ * `CONFIG.openingContextQuery` and `CONFIG.subagentMemory`.
+ */
+/** The opening context search query when the config file sets none. */
+export declare const DEFAULT_OPENING_CONTEXT_QUERY = "project architecture, setup, conventions and key decisions";
+/** Most characters of `openingContextQuery`, after trimming. */
+export declare const OPENING_CONTEXT_QUERY_MAX_LENGTH = 500;
+/**
+ * The keys as they appear in a config file. `OmmsConfig` in `src/config.ts` has
+ * no fields for them, to save lines, so the functions take `FileConfigWithKeys`,
+ * which any config object satisfies. A hand-edited file can hold any value,
+ * which is why each key is checked for its type.
+ */
+export interface InjectionOptionsFileKeys {
+    /** Search memory with `openingContextQuery` on the first message of a new session. Default false. A project can only turn it off. */
+    openingContext?: boolean;
+    /** The opening context search query. Global only. Trimmed, 500 characters at most. Empty means no search. */
+    openingContextQuery?: string;
+    /** Give subagent sessions the memories that match their task. Default true. A project can only turn it off. */
+    subagentMemory?: boolean;
+}
+type FileConfigWithKeys = InjectionOptionsFileKeys & object;
+/**
+ * Read the settings from a merged file config. A value of the wrong type reads
+ * as the default. A query over the limit is cut, and `log` gets its length,
+ * never its text.
+ */
+export declare function injectionOptionsFromFile(fileConfig: FileConfigWithKeys, log?: (message: string, data: {
+    length: number;
+}) => void): {
+    openingContext: boolean;
+    openingContextQuery: string;
+    subagentMemory: boolean;
+};
+/**
+ * Apply the project rules to `overrides`, the copy of the project config that
+ * is merged over the global one. A project may turn either switch off, so a
+ * value of `false` stays. Any other value is dropped, and a value of `true` is
+ * reported through `log`. The query is global only, so a project query is
+ * always dropped and reported.
+ */
+export declare function applyProjectInjectionOptions(project: FileConfigWithKeys, overrides: FileConfigWithKeys, directory: string, log: (message: string, data: {
+    directory: string;
+}) => void): void;
+export {};

package/dist/services/injection-options-config.js

@@ -0,0 +1,56 @@
+/**
+ * The memory injection settings (change align-recall-host-parity): the opening
+ * context and subagent memory, on OpenCode V2, Pi and Claude Code. Kept out of
+ * `src/config.ts` to save its lines. Pure on purpose, like
+ * `visible-recall-config.ts`: 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 values from `CONFIG.openingContext`,
+ * `CONFIG.openingContextQuery` and `CONFIG.subagentMemory`.
+ */
+/** The opening context search query when the config file sets none. */
+export const DEFAULT_OPENING_CONTEXT_QUERY = "project architecture, setup, conventions and key decisions";
+/** Most characters of `openingContextQuery`, after trimming. */
+export const OPENING_CONTEXT_QUERY_MAX_LENGTH = 500;
+/**
+ * Read the settings from a merged file config. A value of the wrong type reads
+ * as the default. A query over the limit is cut, and `log` gets its length,
+ * never its text.
+ */
+export function injectionOptionsFromFile(fileConfig, log) {
+    const raw = fileConfig.openingContextQuery;
+    let query = typeof raw === "string" ? raw.trim() : DEFAULT_OPENING_CONTEXT_QUERY;
+    if (query.length > OPENING_CONTEXT_QUERY_MAX_LENGTH) {
+        log?.("openingContextQuery is longer than 500 characters; only the first 500 are used", {
+            length: query.length,
+        });
+        query = query.slice(0, OPENING_CONTEXT_QUERY_MAX_LENGTH);
+    }
+    return {
+        openingContext: fileConfig.openingContext === true,
+        openingContextQuery: query,
+        subagentMemory: fileConfig.subagentMemory !== false,
+    };
+}
+/**
+ * Apply the project rules to `overrides`, the copy of the project config that
+ * is merged over the global one. A project may turn either switch off, so a
+ * value of `false` stays. Any other value is dropped, and a value of `true` is
+ * reported through `log`. The query is global only, so a project query is
+ * always dropped and reported.
+ */
+export function applyProjectInjectionOptions(project, overrides, directory, log) {
+    for (const key of ["openingContext", "subagentMemory"]) {
+        if (project[key] === false)
+            continue;
+        delete overrides[key];
+        if (project[key] === true) {
+            log(`Project config cannot turn on ${key}; the value was ignored`, { directory });
+        }
+    }
+    delete overrides.openingContextQuery;
+    if (Object.hasOwn(project, "openingContextQuery")) {
+        log("Project config cannot set openingContextQuery; the value was ignored", { directory });
+    }
+}

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/visible-recall-config.d.ts

@@ -5,7 +5,8 @@
  * 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.
+ * 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
@@ -14,7 +15,11 @@
  * which is why they compare with `=== false`.
  */
 export interface VisibleRecallFileKey {
-    /** Draw a row in the OpenCode TUI for each memory recall. Default true. A project can only turn it off. */
+    /**
+     * 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;

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

@@ -5,7 +5,8 @@
  * 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.
+ * 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) {

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

@@ -5,6 +5,7 @@ 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: {
@@ -41,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;
@@ -71,14 +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 recall = await createRecallReporter(ctx, memory, setBounded);
+    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);
@@ -111,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) => ({
@@ -181,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, query: text });
     });
     await ctx.session.hook("context", async (event) => {
         const sessionID = event.sessionID;
@@ -197,25 +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 });
-                recall.record(sessionID, retrieval, retrieval.query, 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"]({
@@ -226,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 () => {
@@ -270,6 +341,9 @@ 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/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
@@ -10,6 +16,8 @@ export interface V2MemoryBridge {
     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>;
     /**
@@ -20,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. */