om-memory-system 5.3.0 → 5.4.1

package/dist/importer/claude-hook-api.js

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { CONFIG, refreshConfigIfChanged } from "../config.js";
 import { classifyCaptureFailure, quickRetryDelayMs } from "../core/capture-retry-policy.js";
-import { buildRecentMemoriesSection, buildRetrievalSection, formatMemoriesForCompaction, retrievalWrapperBytes, wrapRetrievalSection, } from "../core/retrieval.js";
+import { formatMemoriesForCompaction } from "../core/retrieval.js";
 import { handleFinishedTurn } from "../core/turn-outputs.js";
 import { DEFAULT_RETRIEVAL_MAX_TOKENS, tokensToByteCeiling } from "../core/context-budget.js";
 import { resolveClaudeCodeLiveModel } from "../services/ai/live-model-choice.js";
@@ -11,15 +11,15 @@ import { captureFailureOf, drainCaptureRetries, queueFailedCapture, registerCapt
 import { readClaudeCaptureCursor, writeClaudeCaptureCursor, } from "../services/claude-capture-cursor.js";
 import { memoryClient } from "../services/client.js";
 import { log } from "../services/logger.js";
-import { isFullyPrivate, stripPrivateContent } from "../services/privacy.js";
 import { skillTurnRecorder } from "../services/skill-learning/settings-for.js";
 import { getTags } from "../services/tags.js";
 import { parseClaudeTranscript } from "./claude-conversation.js";
+import { markSessionSeen, promptContext, sectionBudget, sectionLimits, subagentContext, wrapSection, } from "./claude-hook-context.js";
 import { learnClaudeProfile } from "./claude-profile-learning.js";
 import { claudeWindowsToCapture, recordClaudeSkillTurns, sessionDirectory, skillUnitOf, workUnitOf, } from "./claude-turn-units.js";
 import { defaultClaudeProjectsRoot } from "./claude-reader.js";
 // The web app's side of the Claude Code hooks (design decisions 4, 6, 7):
-// retrieval for SessionStart and UserPromptSubmit, a one-worker capture queue
+// retrieval for SessionStart, UserPromptSubmit and SubagentStart, a one-worker capture queue
 // for Stop, profile learning, and the once-per-process backfill start. Logs
 // carry event names, session ids, counts, sizes, and codes; never text.
 const HOST = "claude-code";
@@ -31,6 +31,7 @@ export class ClaudeHookRequestError extends Error {
         this.name = "ClaudeHookRequestError";
     }
 }
+const RETRIEVE_EVENTS = ["session-start", "user-prompt-submit", "subagent-start"];
 function objectBody(body) {
     if (!body || typeof body !== "object" || Array.isArray(body)) {
         throw new ClaudeHookRequestError("A JSON object is required");
@@ -57,14 +58,17 @@ function optionalString(body, key) {
 }
 function parseRetrieveRequest(body) {
     const input = objectBody(body);
-    if (input.event !== "session-start" && input.event !== "user-prompt-submit") {
-        throw new ClaudeHookRequestError("event must be session-start or user-prompt-submit");
+    const event = RETRIEVE_EVENTS.find((name) => name === input.event);
+    if (!event) {
+        throw new ClaudeHookRequestError(`event must be one of ${RETRIEVE_EVENTS.join(", ")}`);
     }
     return {
-        event: input.event,
+        event,
         ...sessionAndCwd(input),
         source: optionalString(input, "source"),
         prompt: optionalString(input, "prompt"),
+        transcriptPath: optionalString(input, "transcript_path"),
+        agentType: optionalString(input, "agent_type"),
     };
 }
 /**
@@ -140,44 +144,58 @@ function maybeStartBackfill(deps) {
         .startBackfill()
         .catch((error) => log("Claude Code backfill start failed", { code: errorCode(error) }, "error"));
 }
-async function retrievalSection(request, budgetBytes) {
-    // Every section this api returns is wrapped in the retrieval tag, so each
-    // packed section reserves the wrapper bytes.
-    const budget = { maxBytes: budgetBytes, wrapperBytes: retrievalWrapperBytes() };
+/** The checked transcript path of the request, or undefined when it has none or fails the check. */
+function requestTranscript(request) {
+    if (!request.transcriptPath)
+        return undefined;
+    try {
+        return checkedTranscriptPath(request.transcriptPath, request.sessionId);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The text to add for one request, already wrapped in the retrieval tag. Empty means nothing. */
+async function retrievalText(request, budgetBytes) {
+    const limits = sectionLimits(budgetBytes);
     if (request.event === "user-prompt-submit") {
-        const prompt = stripPrivateContent(request.prompt ?? "").trim();
-        if (!CONFIG.chatMessage.enabled || !prompt || isFullyPrivate(request.prompt ?? "")) {
-            return null;
-        }
-        return buildRetrievalSection(prompt, request.cwd, request.sessionId, budget);
+        return promptContext({
+            prompt: request.prompt ?? "",
+            cwd: request.cwd,
+            sessionId: request.sessionId,
+            transcriptPath: requestTranscript(request),
+        }, limits);
     }
-    const tags = getTags(request.cwd);
-    if (request.source === "compact" || request.source === "resume") {
-        if (!CONFIG.compaction.enabled)
-            return null;
-        const result = await memoryClient.searchMemoriesBySessionID(request.sessionId, tags.project.tag, CONFIG.compaction.memoryLimit);
-        const own = result.success
-            ? result.results.filter((memory) => memory.metadata?.host === HOST)
-            : [];
-        return own.length > 0 ? formatMemoriesForCompaction(own, budget) : null;
+    if (request.event === "subagent-start") {
+        return subagentContext({
+            cwd: request.cwd,
+            sessionId: request.sessionId,
+            transcriptPath: requestTranscript(request),
+            agentType: request.agentType,
+        }, budgetBytes);
     }
-    if (!CONFIG.chatMessage.enabled)
-        return null;
-    return buildRecentMemoriesSection({
-        projectTag: tags.project.tag,
-        userEmail: tags.user.userEmail,
-        sessionId: request.sessionId,
-        maxMemories: CONFIG.chatMessage.maxMemories,
-        excludeCurrentSession: CONFIG.chatMessage.excludeCurrentSession,
-        maxAgeDays: CONFIG.chatMessage.maxAgeDays,
-        budget,
-    });
+    // A fresh or cleared session adds nothing; the opening section waits for the first prompt.
+    if (request.source !== "compact" && request.source !== "resume")
+        return "";
+    // A compacted or resumed session already has history, so it never gets an opening section.
+    markSessionSeen(request.sessionId);
+    if (!CONFIG.compaction.enabled)
+        return "";
+    const tags = getTags(request.cwd);
+    const result = await memoryClient.searchMemoriesBySessionID(request.sessionId, tags.project.tag, CONFIG.compaction.memoryLimit);
+    const own = result.success
+        ? result.results.filter((memory) => memory.metadata?.host === HOST)
+        : [];
+    return own.length > 0
+        ? wrapSection(formatMemoriesForCompaction(own, sectionBudget(limits)), limits)
+        : "";
 }
 /**
- * `POST /api/claude/retrieve`: recent project memories for a fresh session,
- * the session's own memories after compaction or resume, or the retrieval
- * section for a prompt. Every text is wrapped in the retrieval tag; an empty
- * string means nothing to add.
+ * `POST /api/claude/retrieve`: the retrieval section for a prompt (and the
+ * opening section on a session's first prompt, when on), the memories for a
+ * starting subagent's task, or the session's own memories after compaction or
+ * resume. A fresh or cleared session adds nothing. Every text is wrapped in the
+ * retrieval tag; an empty string means nothing to add.
  */
 export async function handleClaudeRetrieve(body, deps = {}) {
     const request = parseRetrieveRequest(body);
@@ -189,8 +207,7 @@ export async function handleClaudeRetrieve(body, deps = {}) {
     if (request.event === "session-start")
         maybeStartBackfill(deps);
     try {
-        const section = await retrievalSection(request, budgetBytes);
-        return { additionalContext: section ? wrapRetrievalSection(section) : "" };
+        return { additionalContext: await retrievalText(request, budgetBytes) };
     }
     catch (error) {
         log("Claude Code retrieval failed", {

package/dist/importer/claude-hook-context.d.ts

@@ -0,0 +1,49 @@
+import type { ContextBudgetOptions } from "../core/context-budget.js";
+/** Tells the recall rows to draw nothing for this section. 21 bytes, newline included. */
+export declare const ROWS_OFF_MARKER = "<!--omms:rows-off-->\n";
+/** The byte budget of one request and whether recall rows are off for it. */
+export interface SectionLimits {
+    budgetBytes: number;
+    rowsOff: boolean;
+}
+/** Read `visibleRecall` once per request, after the config refresh. */
+export declare function sectionLimits(budgetBytes: number): SectionLimits;
+/** The budget for one packed section: the retrieval tag, and the rows-off marker when set, are reserved. */
+export declare function sectionBudget(limits: SectionLimits): ContextBudgetOptions;
+/** Put a marker line right after the opening tag of a wrapped section. */
+export declare function insertMarker(wrapped: string, marker: string): string;
+/** Wrap a packed section, with the rows-off marker when rows are off. */
+export declare function wrapSection(section: string, limits: SectionLimits): string;
+/**
+ * The opening marker. The query goes on one line, with `"`, `<` and `>`
+ * removed, `--` folded to `-` and 300 characters at most, so it cannot end the
+ * comment early.
+ */
+export declare function openingMarker(query: string): string;
+/** Remember a session, so a later prompt in this process is never first. Oldest ids drop out. */
+export declare function markSessionSeen(sessionId: string): void;
+export interface PromptContextInput {
+    prompt: string;
+    cwd: string;
+    sessionId: string;
+    /** The checked transcript path, or undefined when the request had none or it failed the check. */
+    transcriptPath: string | undefined;
+}
+/**
+ * The added context for a prompt: its retrieval section, and on the first
+ * prompt of a session, with `openingContext` on, the opening section after it.
+ * Empty string when there is nothing to add.
+ */
+export declare function promptContext(input: PromptContextInput, limits: SectionLimits): Promise<string>;
+export interface SubagentContextInput {
+    cwd: string;
+    sessionId: string;
+    transcriptPath: string | undefined;
+    agentType: string | undefined;
+}
+/**
+ * The added context for a starting subagent: the retrieval section for its
+ * task prompt, read from the parent transcript. Every subagent section carries
+ * the rows-off marker. Any problem gives an empty string.
+ */
+export declare function subagentContext(input: SubagentContextInput, budgetBytes: number): Promise<string>;

package/dist/importer/claude-hook-context.js

@@ -0,0 +1,264 @@
+import { open, readFile, stat } from "node:fs/promises";
+import { CONFIG } from "../config.js";
+import { buildFirstPromptSections, openingQueryFor } from "../core/opening-context.js";
+import { RETRIEVAL_SECTION_TAG, buildRetrievalSection, retrievalWrapperBytes, wrapRetrievalSection, } from "../core/retrieval.js";
+import { isFullyPrivate, stripPrivateContent } from "../services/privacy.js";
+import { utf8ByteLength } from "../utils/context-limit.js";
+import { parseClaudeTranscript } from "./claude-conversation.js";
+// What the Claude Code hooks add beyond a plain retrieval section (change
+// align-recall-host-parity): the rows-off marker, the opening section for the
+// first prompt of a session, and the task memories for a subagent. The hook
+// reaches the recall rows only through the injected text, so the markers are
+// HTML comments on the line after a section's opening tag. They hold no memory
+// text. Logs here carry sizes and codes, never text.
+/** Tells the recall rows to draw nothing for this section. 21 bytes, newline included. */
+export const ROWS_OFF_MARKER = "<!--omms:rows-off-->\n";
+/** Between the prompt's section and the opening section. */
+const SECTION_SEPARATOR = "\n";
+const OPENING_QUERY_MAX = 300;
+/** Sessions this process remembers, so the transcript check runs once per session. */
+const SEEN_SESSIONS_MAX = 500;
+/** A transcript this large already holds earlier prompts, or is too big to scan. */
+const FIRST_PROMPT_SCAN_MAX_BYTES = 1024 * 1024;
+const SUBAGENT_TAIL_BYTES = 1024 * 1024;
+/** Read `visibleRecall` once per request, after the config refresh. */
+export function sectionLimits(budgetBytes) {
+    return { budgetBytes, rowsOff: CONFIG.visibleRecall === false };
+}
+/** The budget for one packed section: the retrieval tag, and the rows-off marker when set, are reserved. */
+export function sectionBudget(limits) {
+    const marker = limits.rowsOff ? utf8ByteLength(ROWS_OFF_MARKER) : 0;
+    return { maxBytes: limits.budgetBytes, wrapperBytes: retrievalWrapperBytes() + marker };
+}
+/** Put a marker line right after the opening tag of a wrapped section. */
+export function insertMarker(wrapped, marker) {
+    const head = `<${RETRIEVAL_SECTION_TAG}>\n`;
+    return wrapped.startsWith(head) ? head + marker + wrapped.slice(head.length) : wrapped;
+}
+/** Wrap a packed section, with the rows-off marker when rows are off. */
+export function wrapSection(section, limits) {
+    const wrapped = wrapRetrievalSection(section);
+    return limits.rowsOff ? insertMarker(wrapped, ROWS_OFF_MARKER) : wrapped;
+}
+/**
+ * The opening marker. The query goes on one line, with `"`, `<` and `>`
+ * removed, `--` folded to `-` and 300 characters at most, so it cannot end the
+ * comment early.
+ */
+export function openingMarker(query) {
+    const line = query
+        .replace(/["<>]/g, "")
+        .replace(/-{2,}/g, "-")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, OPENING_QUERY_MAX)
+        // Do not leave half of a surrogate pair at the cut.
+        .replace(/[\uD800-\uDBFF]$/, "");
+    return `<!--omms:opening query="${line}"-->\n`;
+}
+// --- First prompt of a session ---
+const seenSessions = new Set();
+/** Remember a session, so a later prompt in this process is never first. Oldest ids drop out. */
+export function markSessionSeen(sessionId) {
+    seenSessions.delete(sessionId);
+    seenSessions.add(sessionId);
+    if (seenSessions.size > SEEN_SESSIONS_MAX) {
+        seenSessions.delete(seenSessions.values().next().value);
+    }
+}
+// User entries that Claude Code writes itself (command output, shell mode,
+// background task notices) are not prompts.
+const NOT_PROMPT_PREFIXES = [
+    "<local-command-",
+    "<command-name>",
+    "<command-message>",
+    "<bash-",
+    "<task-notification>",
+];
+function contentBlocks(entry) {
+    const content = entry.message?.content;
+    return Array.isArray(content)
+        ? content.filter((block) => block && typeof block === "object")
+        : [];
+}
+/** The text of a prompt the user typed, or null for any other transcript entry. */
+function userPromptText(entry) {
+    if (entry.type !== "user" || entry.isMeta === true || entry.isSidechain === true)
+        return null;
+    const content = entry.message?.content;
+    let text;
+    if (typeof content === "string")
+        text = content;
+    else {
+        const blocks = contentBlocks(entry);
+        if (blocks.some((block) => block.type === "tool_result"))
+            return null;
+        text = blocks.map((block) => (block.type === "text" ? (block.text ?? "") : "")).join("\n");
+    }
+    text = text.trim();
+    return text && !NOT_PROMPT_PREFIXES.some((prefix) => text.startsWith(prefix)) ? text : null;
+}
+/**
+ * True when the transcript holds no user prompt before `prompt`. The host may
+ * or may not have written the current prompt yet, so a last prompt with the same
+ * text is not counted. A missing file is a session with no history. Any other
+ * problem counts as not first, so the opening section is skipped.
+ */
+async function hasNoEarlierPrompt(transcriptPath, prompt) {
+    let text;
+    try {
+        if ((await stat(transcriptPath)).size > FIRST_PROMPT_SCAN_MAX_BYTES)
+            return false;
+        text = await readFile(transcriptPath, "utf8");
+    }
+    catch (error) {
+        return error?.code === "ENOENT";
+    }
+    const earlier = parseClaudeTranscript(text)
+        .entries.map(userPromptText)
+        .filter((entry) => entry !== null);
+    if (earlier.at(-1) === prompt.trim())
+        earlier.pop();
+    return earlier.length === 0;
+}
+/**
+ * The first prompt of a session, as far as this process can tell: the session
+ * is new to this process and its transcript holds no earlier prompt. Marks the
+ * session seen. A missing or invalid transcript path counts as not first.
+ */
+async function isFirstPrompt(sessionId, transcriptPath, prompt) {
+    if (seenSessions.has(sessionId))
+        return false;
+    const first = transcriptPath ? await hasNoEarlierPrompt(transcriptPath, prompt) : false;
+    markSessionSeen(sessionId);
+    return first;
+}
+/**
+ * The added context for a prompt: its retrieval section, and on the first
+ * prompt of a session, with `openingContext` on, the opening section after it.
+ * Empty string when there is nothing to add.
+ */
+export async function promptContext(input, limits) {
+    const prompt = stripPrivateContent(input.prompt).trim();
+    if (!CONFIG.chatMessage.enabled || !prompt || isFullyPrivate(input.prompt))
+        return "";
+    const budget = sectionBudget(limits);
+    const openingQuery = openingQueryFor(CONFIG);
+    const first = openingQuery !== null &&
+        (await isFirstPrompt(input.sessionId, input.transcriptPath, input.prompt));
+    if (!first) {
+        const section = await buildRetrievalSection(prompt, input.cwd, input.sessionId, budget);
+        return section ? wrapSection(section, limits) : "";
+    }
+    const marker = limits.rowsOff ? ROWS_OFF_MARKER : openingMarker(openingQuery);
+    const { promptSection, openingSection } = await buildFirstPromptSections({
+        prompt,
+        openingQuery,
+        directory: input.cwd,
+        sessionId: input.sessionId,
+        budget,
+        // The rows-off marker is already in `wrapperBytes`; the opening marker and the
+        // line between the two sections are extra.
+        openingReserveBytes: (limits.rowsOff ? 0 : utf8ByteLength(marker)) + SECTION_SEPARATOR.length,
+    });
+    return [
+        promptSection &&
+            (limits.rowsOff ? insertMarker(promptSection, ROWS_OFF_MARKER) : promptSection),
+        openingSection && insertMarker(openingSection, marker),
+    ]
+        .filter(Boolean)
+        .join(SECTION_SEPARATOR);
+}
+// --- Subagents ---
+/**
+ * A background subagent's call gets this receipt as its tool result at launch, before the agent
+ * runs. It is not an answer: the call is still the one whose agent is starting.
+ */
+const LAUNCH_RECEIPT_PREFIX = "Async agent launched";
+function isLaunchReceipt(content) {
+    const text = Array.isArray(content)
+        ? content.map((part) => part?.text ?? "").join("")
+        : content;
+    return typeof text === "string" && text.startsWith(LAUNCH_RECEIPT_PREFIX);
+}
+/** Calls that already fed a subagent, per parent session. Bounded, in memory only. */
+const claimedCalls = new Map();
+const CLAIMED_SESSIONS_MAX = 500;
+const CLAIMED_CALLS_MAX = 200;
+function claimCall(sessionId, callId) {
+    const used = claimedCalls.get(sessionId) ?? new Set();
+    claimedCalls.delete(sessionId);
+    used.add(callId);
+    if (used.size > CLAIMED_CALLS_MAX)
+        used.delete(used.values().next().value);
+    claimedCalls.set(sessionId, used);
+    if (claimedCalls.size > CLAIMED_SESSIONS_MAX) {
+        claimedCalls.delete(claimedCalls.keys().next().value);
+    }
+}
+/**
+ * The task prompt of the oldest `Agent` or `Task` call of `agentType` that has no result yet and
+ * has not fed a subagent already.
+ * A background launch receipt does not count as a result.
+ */
+async function subagentTaskPrompt(transcriptPath, agentType, sessionId) {
+    const handle = await open(transcriptPath, "r");
+    let text;
+    try {
+        const { size } = await handle.stat();
+        const length = Math.min(size, SUBAGENT_TAIL_BYTES);
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, size - length);
+        text = buffer.toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+    const answered = new Set();
+    const calls = [];
+    for (const entry of parseClaudeTranscript(text).entries) {
+        if (entry.isSidechain === true)
+            continue;
+        for (const block of contentBlocks(entry)) {
+            if (block.type === "tool_result" && block.tool_use_id && !isLaunchReceipt(block.content)) {
+                answered.add(block.tool_use_id);
+            }
+            if (block.type !== "tool_use" || !block.id)
+                continue;
+            if (block.name !== "Agent" && block.name !== "Task")
+                continue;
+            const input = (block.input ?? {});
+            if (typeof input.prompt !== "string")
+                continue;
+            const type = typeof input.subagent_type === "string" && input.subagent_type;
+            calls.push({ id: block.id, type: type || "general-purpose", prompt: input.prompt });
+        }
+    }
+    // Oldest first: parallel subagents start in the order of their calls. A call that already
+    // fed a subagent is not used again, so a background call (open until its agent ends) or a
+    // second start with no new call gets nothing.
+    const used = claimedCalls.get(sessionId);
+    const call = calls.find((candidate) => candidate.type === agentType && !answered.has(candidate.id) && !used?.has(candidate.id));
+    if (!call)
+        return null;
+    claimCall(sessionId, call.id);
+    return call.prompt;
+}
+/**
+ * The added context for a starting subagent: the retrieval section for its
+ * task prompt, read from the parent transcript. Every subagent section carries
+ * the rows-off marker. Any problem gives an empty string.
+ */
+export async function subagentContext(input, budgetBytes) {
+    if (!CONFIG.subagentMemory || !CONFIG.chatMessage.enabled)
+        return "";
+    if (!input.transcriptPath || !input.agentType)
+        return "";
+    const task = await subagentTaskPrompt(input.transcriptPath, input.agentType, input.sessionId).catch(() => null);
+    const prompt = stripPrivateContent(task ?? "").trim();
+    if (!task || !prompt || isFullyPrivate(task))
+        return "";
+    const limits = { budgetBytes, rowsOff: true };
+    const section = await buildRetrievalSection(prompt, input.cwd, input.sessionId, sectionBudget(limits));
+    return section ? wrapSection(section, limits) : "";
+}

package/dist/services/ai/local-api-url.d.ts

@@ -0,0 +1,2 @@
+/** True when the URL names this machine, so a model server there may run without a key. */
+export declare function isLocalApiUrl(url: string | undefined): boolean;

package/dist/services/ai/local-api-url.js

@@ -0,0 +1,12 @@
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/** True when the URL names this machine, so a model server there may run without a key. */
+export function isLocalApiUrl(url) {
+    if (!url)
+        return false;
+    try {
+        return LOCAL_HOSTS.has(new URL(url).hostname.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}

package/dist/services/ai/provider-config.d.ts

@@ -12,6 +12,8 @@ interface MemoryProviderRuntimeConfig {
 interface ProviderConfigOverrides {
     maxIterations?: number;
     iterationTimeout?: number;
+    /** Chat only: a model server on this machine needs no key. Other callers still need one. */
+    keylessForLocalUrl?: boolean;
 }
 export declare function buildMemoryProviderConfig(config: MemoryProviderRuntimeConfig, overrides?: ProviderConfigOverrides): ProviderConfig;
 export {};

package/dist/services/ai/provider-config.js

@@ -1,4 +1,5 @@
 import { isPlaceholderApiKey } from "./api-key-placeholder.js";
+import { isLocalApiUrl } from "./local-api-url.js";
 export function buildMemoryProviderConfig(config, overrides = {}) {
     const memoryModel = config.memoryModel;
     const memoryApiUrl = config.memoryApiUrl;
@@ -11,7 +12,8 @@ export function buildMemoryProviderConfig(config, overrides = {}) {
         issues.push("missing memoryModel");
     if (!memoryApiUrl && !isOrcaRouter)
         issues.push("missing memoryApiUrl");
-    if (!memoryApiKey)
+    const keyOptional = overrides.keylessForLocalUrl === true && isLocalApiUrl(memoryApiUrl);
+    if (!memoryApiKey && !keyOptional)
         issues.push("missing memoryApiKey");
     if (isPlaceholderApiKey(memoryApiKey))
         issues.push("replace the placeholder memoryApiKey value");

package/dist/services/ai/providers/google-gemini.js

@@ -123,7 +123,8 @@ export class GoogleGeminiProvider extends BaseAIProvider {
             const timeout = setTimeout(() => controller.abort(), iterationTimeout);
             try {
                 const baseUrl = this.config.apiUrl || "https://generativelanguage.googleapis.com/v1beta";
-                const url = `${baseUrl}/models/${this.config.model}:generateContent?key=${this.config.apiKey}`;
+                const keyQuery = this.config.apiKey ? `?key=${this.config.apiKey}` : "";
+                const url = `${baseUrl}/models/${this.config.model}:generateContent${keyQuery}`;
                 const requestBody = {
                     contents,
                     systemInstruction: geminiSystemInstruction,

package/dist/services/ai/providers/openai-responses.js

@@ -54,7 +54,8 @@ export class OpenAIResponsesProvider extends BaseAIProvider {
                     method: "POST",
                     headers: {
                         "Content-Type": "application/json",
-                        Authorization: `Bearer ${this.config.apiKey}`,
+                        // A keyless server on this machine gets no Authorization header.
+                        ...(this.config.apiKey ? { Authorization: `Bearer ${this.config.apiKey}` } : {}),
                     },
                     body: JSON.stringify(requestBody),
                     signal: controller.signal,

package/dist/services/chat/chat-runtime.js

@@ -23,7 +23,11 @@ export async function callTool(config, system, user, tool, timeoutMs = CHAT_MODE
     const { AIProviderFactory } = await import("../ai/ai-provider-factory.js");
     const { buildMemoryProviderConfig } = await import("../ai/provider-config.js");
     const { aiSessionManager } = await import("../ai/session/ai-session-manager.js");
-    const provider = AIProviderFactory.createProvider(config.memoryProvider, buildMemoryProviderConfig(config, { maxIterations: 1, iterationTimeout: timeoutMs }));
+    const provider = AIProviderFactory.createProvider(config.memoryProvider, buildMemoryProviderConfig(config, {
+        maxIterations: 1,
+        iterationTimeout: timeoutMs,
+        keylessForLocalUrl: true,
+    }));
     const sessionId = `chat_${crypto.randomUUID()}`;
     try {
         return await provider.executeToolCall(system, user, tool, sessionId);

package/dist/services/chat/chat-status.js

@@ -1,4 +1,5 @@
 import { isPlaceholderApiKey } from "../ai/api-key-placeholder.js";
+import { isLocalApiUrl } from "../ai/local-api-url.js";
 /** Whether chat can call the external memory model. Mirrors `buildMemoryProviderConfig`. */
 export function chatStatus(config) {
     const provider = config.memoryProvider ?? "openai-chat";
@@ -8,7 +9,9 @@ export function chatStatus(config) {
         missing.push("memoryModel");
     if (!config.memoryApiUrl && !presetEndpoint)
         missing.push("memoryApiUrl");
-    if (!config.memoryApiKey || isPlaceholderApiKey(config.memoryApiKey)) {
+    // A model server on this machine needs no key. A placeholder that was left in the box is still flagged.
+    const keyOptional = !config.memoryApiKey && isLocalApiUrl(config.memoryApiUrl);
+    if (!keyOptional && (!config.memoryApiKey || isPlaceholderApiKey(config.memoryApiKey))) {
         missing.push("memoryApiKey");
     }
     return {