Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

fix(doctor): judge the LLM provider the way the daemon does (#1575)

Dmitrii Zhukovc5b8ebfb32eb
diff --git a/src/cli.ts b/src/cli.ts
index d73e5d98..bd32b08e 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -124,7 +124,7 @@ const IS_RESET = args.includes("--reset");
// (getRestPort/getBaseUrl/getEnginePort) or the --port /
// --instance / --tools handlers below. Only-if-unset, so a real
// process.env value — including one just set by a CLI flag — still wins.
-hydrateProcessEnvFromFile();
+const shellEnv = hydrateProcessEnvFromFile();
// --version / -V early exit. Print VERSION + exit before any side effects
// (engine boot, env load, dir mkdir). `-v` is taken by --verbose so we
@@ -1992,11 +1992,15 @@ function checkClaudeCodeHooks(): CCHooksCheck {
// which prompts Fix/Skip/More/Quit per failing check, applies the fix
// inline, and re-checks only the affected diagnostic.
+function doctorEnvPath(): string {
+ return process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env");
+}
+
function buildDoctorContext(): DoctorContext {
return {
baseUrl: getBaseUrl(),
viewerUrl: getViewerUrl(),
- envPath: join(homedir(), ".agentmemory", ".env"),
+ envPath: doctorEnvPath(),
pidfilePath: readEngineState()?.kind === "compose" ? engineStatePath() : enginePidfilePath(),
enginePath: engineStatePath(),
pinnedVersion: IIPINNED_VERSION,
@@ -2005,16 +2009,17 @@ function buildDoctorContext(): DoctorContext {
function buildDoctorEffects(): DoctorEffects {
return {
- envFileExists: () => existsSync(join(homedir(), ".agentmemory", ".env")),
+ envFileExists: () => existsSync(doctorEnvPath()),
readEnvFile: () => {
try {
return parseEnvFile(
- readFileSync(join(homedir(), ".agentmemory", ".env"), "utf-8"),
+ readFileSync(doctorEnvPath(), "utf-8"),
);
} catch {
return {};
}
},
+ processEnv: () => shellEnv,
pidfileExists: () => {
const state = readEngineState();
return state?.kind === "compose" ? Boolean(state.composePid) : existsSync(enginePidfilePath());
diff --git a/src/cli/doctor-diagnostics.ts b/src/cli/doctor-diagnostics.ts
index 33f67c2d..2af80414 100644
--- a/src/cli/doctor-diagnostics.ts
+++ b/src/cli/doctor-diagnostics.ts
@@ -16,6 +16,8 @@
// agentmemory doctor --all # apply every available fix without prompting (CI)
// agentmemory doctor --dry-run # show what each fix WOULD do; execute nothing
+import { detectLlmProviderKind, parseEnvContent } from "../config.js";
+
export type DiagnosticStatus = {
ok: boolean;
/** Short status detail (one line). Shown alongside the check name. */
@@ -95,26 +97,7 @@ const PROVIDER_KEY_NAMES = [
"MINIMAX_API_KEY",
] as const;
-export function parseEnvFile(content: string): Record<string, string> {
- const out: Record<string, string> = {};
- for (const rawLine of content.split(/\r?\n/)) {
- const line = rawLine.trim();
- if (!line || line.startsWith("#")) continue;
- const eq = line.indexOf("=");
- if (eq < 0) continue;
- const key = line.slice(0, eq).trim();
- let value = line.slice(eq + 1).trim();
- // Strip surrounding quotes.
- if (
- (value.startsWith('"') && value.endsWith('"')) ||
- (value.startsWith("'") && value.endsWith("'"))
- ) {
- value = value.slice(1, -1);
- }
- out[key] = value;
- }
- return out;
-}
+export const parseEnvFile = parseEnvContent;
/** Returns the list of provider keys that look real (non-placeholder). */
export function realProviderKeys(env: Record<string, string>): string[] {
@@ -151,6 +134,7 @@ export type DoctorEffects = {
envFileExists: () => boolean;
/** Read ~/.agentmemory/.env and return parsed key=value pairs. */
readEnvFile: () => Record<string, string>;
+ processEnv: () => Record<string, string | undefined>;
/** Is the iii engine PID in the pidfile still alive? */
pidfilePidIsAlive: () => boolean | null;
/** Does the pidfile exist on disk? */
@@ -185,7 +169,8 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] {
fixPreview: "Copy .env.example into ~/.agentmemory/.env (your keys file).",
moreInfo:
"agentmemory reads provider API keys (Anthropic, OpenAI, Gemini, …) from ~/.agentmemory/.env. " +
- "Without this file the daemon falls back to BM25-only search and no LLM-backed enrichment runs.",
+ "Without this file, and without a provider key exported in the environment, the daemon " +
+ "falls back to BM25-only search and no LLM-backed enrichment runs.",
check: async () => ({
ok: effects.envFileExists(),
detail: effects.envFileExists() ? undefined : "no env file",
@@ -194,22 +179,43 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] {
},
{
id: "no-llm-provider-key",
- message: "No LLM provider API key found in ~/.agentmemory/.env.",
+ message: "No LLM provider API key found in ~/.agentmemory/.env or the environment.",
fixPreview: "Open ~/.agentmemory/.env in $EDITOR and paste your key, then re-check.",
moreInfo:
"Set at least one of: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, " +
- "OPENROUTER_API_KEY, MINIMAX_API_KEY. The daemon picks the first that resolves " +
- "to a real (non-placeholder) value at startup.",
+ "GOOGLE_API_KEY, OPENROUTER_API_KEY, MINIMAX_API_KEY. Placeholder values count as missing. " +
+ "OPENAI_API_KEY counts only while OPENAI_API_KEY_FOR_LLM is not false, and " +
+ "AGENTMEMORY_ALLOW_AGENT_SDK=true needs no key. A value exported in the environment " +
+ "wins over the file, but only for a daemon started from that environment, and " +
+ "counts even when the file is absent.",
check: async () => {
- if (!effects.envFileExists()) {
- return { ok: false, detail: "env file missing (run env-missing fix first)" };
+ const file = effects.readEnvFile();
+ const env: Record<string, string> = { ...file };
+ for (const [k, v] of Object.entries(effects.processEnv())) {
+ if (v !== undefined) env[k] = v;
}
- const env = effects.readEnvFile();
- const real = realProviderKeys(env);
- return {
- ok: real.length > 0,
- detail: real.length > 0 ? `found: ${real.join(", ")}` : "no provider key set",
- };
+ for (const k of placeholderProviderKeys(env)) delete env[k];
+ if (detectLlmProviderKind(env) !== "llm") {
+ return {
+ ok: false,
+ detail: effects.envFileExists()
+ ? "no provider key set"
+ : "no provider key set (run env-missing fix first)",
+ };
+ }
+ const real = realProviderKeys(env).filter(
+ (k) =>
+ detectLlmProviderKind({
+ [k]: env[k],
+ OPENAI_API_KEY_FOR_LLM: env.OPENAI_API_KEY_FOR_LLM,
+ }) === "llm",
+ );
+ const fromEnv = real.filter((k) => file[k] !== env[k]);
+ const named = real.map((k) => (fromEnv.includes(k) ? `${k} (environment)` : k));
+ if (named.length === 0) return { ok: true, detail: "agent-sdk fallback, no API key" };
+ const caveat =
+ fromEnv.length > 0 ? "; a daemon started elsewhere will not see it" : "";
+ return { ok: true, detail: `found: ${named.join(", ")}${caveat}` };
},
fix: (ctx) => effects.openEditor(ctx.envPath),
},
diff --git a/src/config.ts b/src/config.ts
index 54b9b11d..2ea539bc 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -48,7 +48,11 @@ function loadEnvFile(): Record<string, string> {
envFileCache = {};
return envFileCache;
}
- const content = readFileSync(ENV_FILE, "utf-8");
+ envFileCache = parseEnvContent(readFileSync(ENV_FILE, "utf-8"));
+ return envFileCache;
+}
+
+export function parseEnvContent(content: string): Record<string, string> {
const vars: Record<string, string> = {};
for (const line of content.split("\n")) {
const trimmed = line.trim();
@@ -67,8 +71,7 @@ function loadEnvFile(): Record<string, string> {
}
vars[key] = val;
}
- envFileCache = vars;
- return envFileCache;
+ return vars;
}
// Test hook: clears the memoized .env so the next loadEnvFile() re-reads disk
@@ -89,10 +92,12 @@ function hasRealValue(v: string | undefined): v is string {
// ignored by them. Copy the file's vars into process.env, but only when the
// key is currently unset so a real process.env value still wins (this
// preserves the {...fileEnv, ...process.env} precedence getMergedEnv uses).
-export function hydrateProcessEnvFromFile(): void {
+export function hydrateProcessEnvFromFile(): Record<string, string | undefined> {
+ const beforeHydration = { ...process.env };
for (const [k, v] of Object.entries(loadEnvFile())) {
if (process.env[k] === undefined) process.env[k] = v;
}
+ return beforeHydration;
}
// Warn once when a configured model is in the premium tier and likely to burn
diff --git a/test/cli-doctor-env-file.test.ts b/test/cli-doctor-env-file.test.ts
new file mode 100644
index 00000000..c2656123
--- /dev/null
+++ b/test/cli-doctor-env-file.test.ts
@@ -0,0 +1,55 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterEach, beforeEach, expect, it } from "vitest";
+
+let home: string;
+
+beforeEach(() => {
+ home = mkdtempSync(join(tmpdir(), "doctor-env-file-"));
+ mkdirSync(join(home, ".agentmemory"));
+ writeFileSync(join(home, ".agentmemory", ".env"), "# no provider key here\n");
+ writeFileSync(join(home, "custom.env"), "ANTHROPIC_API_KEY=sk-ant-real-key-value\n");
+});
+
+afterEach(() => {
+ rmSync(home, { recursive: true, force: true });
+});
+
+function doctorDryRun(extraEnv: Record<string, string>): Promise<string> {
+ return new Promise((done, reject) => {
+ const child = spawn(process.execPath, [resolve("dist/cli.mjs"), "doctor", "--dry-run"], {
+ env: {
+ PATH: process.env.PATH,
+ HOME: home,
+ USERPROFILE: home,
+ TMPDIR: home,
+ AGENTMEMORY_URL: "http://127.0.0.1:1",
+ NO_COLOR: "1",
+ CI: "1",
+ ...extraEnv,
+ },
+ timeout: 30000,
+ });
+ let output = "";
+ child.stdout.on("data", (data) => { output += data; });
+ child.stderr.on("data", (data) => { output += data; });
+ child.on("error", reject);
+ child.on("close", () => done(output));
+ });
+}
+
+it("reads provider keys from AGENTMEMORY_ENV_FILE, the file the daemon loads", async () => {
+ rmSync(join(home, ".agentmemory", ".env"));
+ const output = await doctorDryRun({ AGENTMEMORY_ENV_FILE: join(home, "custom.env") });
+ expect(output).toContain("Dry-run complete");
+ expect(output).not.toContain("[env-missing]");
+ expect(output).not.toContain("[no-llm-provider-key]");
+});
+
+it("reports no provider key when only the default env file is read", async () => {
+ const output = await doctorDryRun({});
+ expect(output).toContain("Dry-run complete");
+ expect(output).toContain("[no-llm-provider-key]");
+});
diff --git a/test/cli-doctor-fixes.test.ts b/test/cli-doctor-fixes.test.ts
index 99fab1fd..41483517 100644
--- a/test/cli-doctor-fixes.test.ts
+++ b/test/cli-doctor-fixes.test.ts
@@ -34,6 +34,7 @@ function stubEffects(overrides: Partial<DoctorEffects> = {}): DoctorEffects {
return {
envFileExists: () => true,
readEnvFile: () => ({ ANTHROPIC_API_KEY: "sk-ant-real-key-value" }),
+ processEnv: () => ({}),
pidfileExists: () => false,
pidfilePidIsAlive: () => null,
findIiiBinary: () => "/Users/test/.local/bin/iii",
@@ -113,6 +114,167 @@ describe("doctor v2 diagnostic catalog", () => {
expect(status.ok).toBe(true);
});
+ it("no-llm-provider-key passes when the agent-sdk fallback is enabled without a key", async () => {
+ const diagnostics = buildDiagnostics(
+ stubEffects({
+ readEnvFile: () => parseEnvFile("AGENTMEMORY_ALLOW_AGENT_SDK=true # opt in\n"),
+ }),
+ );
+ const check = diagnostics.find((d) => d.id === "no-llm-provider-key")!;
+ const status = await check.check(stubCtx());
+ expect(status.ok).toBe(true);
+ expect(status.detail).toContain("agent-sdk");
+ });
+
+ it("no-llm-provider-key fails when OPENAI_API_KEY is reserved for embeddings", async () => {
+ const diagnostics = buildDiagnostics(
+ stubEffects({
+ readEnvFile: () =>
+ parseEnvFile(
+ "OPENAI_API_KEY=sk-real-openai-key\n" +
+ "OPENAI_API_KEY_FOR_LLM=false # Skip OpenAI auto-detection for LLM; key stays active for embeddings\n",
+ ),
+ }),
+ );
+ const check = diagnostics.find((d) => d.id === "no-llm-provider-key")!;
+ const status = await check.check(stubCtx());
+ expect(status.ok).toBe(false);
+ });
+
+ it("no-llm-provider-key reports only the keys the daemon uses for the LLM", async () => {
+ const statusFor = async (env: Record<string, string>) => {
+ const diagnostics = buildDiagnostics(stubEffects({ readEnvFile: () => env }));
+ const check = diagnostics.find((d) => d.id === "no-llm-provider-key")!;
+ return check.check(stubCtx());
+ };
+ expect(await statusFor({ OPENAI_API_KEY: "sk-real-openai-key" })).toEqual({
+ ok: true,
+ detail: "found: OPENAI_API_KEY",
+ });
+ expect(
+ await statusFor({
+ ANTHROPIC_API_KEY: "sk-ant-real-key-value",
+ OPENAI_API_KEY: "sk-real-openai-key",
+ OPENAI_API_KEY_FOR_LLM: "false",
+ }),
+ ).toEqual({ ok: true, detail: "found: ANTHROPIC_API_KEY" });
+ });
+
+ describe("no-llm-provider-key with a process environment", () => {
+ const statusFor = async (
+ file: Record<string, string>,
+ processEnv: Record<string, string | undefined>,
+ ) => {
+ const diagnostics = buildDiagnostics(
+ stubEffects({ readEnvFile: () => file, processEnv: () => processEnv }),
+ );
+ const check = diagnostics.find((d) => d.id === "no-llm-provider-key")!;
+ return check.check(stubCtx());
+ };
+
+ it("lets the environment override the same key in the file, as the daemon does", async () => {
+ const reservedInFile = {
+ OPENAI_API_KEY: "sk-real-openai-key",
+ OPENAI_API_KEY_FOR_LLM: "false",
+ };
+ expect((await statusFor(reservedInFile, {})).ok).toBe(false);
+ expect((await statusFor(reservedInFile, { OPENAI_API_KEY_FOR_LLM: "true" })).ok).toBe(true);
+ expect(
+ (await statusFor({ ANTHROPIC_API_KEY: "sk-ant-real-key-value" }, { ANTHROPIC_API_KEY: "" }))
+ .ok,
+ ).toBe(false);
+ });
+
+ it("names a key that only the environment provides, and says a daemon elsewhere misses it", async () => {
+ expect(await statusFor({}, { ANTHROPIC_API_KEY: "sk-ant-real-key-value" })).toEqual({
+ ok: true,
+ detail:
+ "found: ANTHROPIC_API_KEY (environment); a daemon started elsewhere will not see it",
+ });
+ });
+
+ it("marks a key the environment overrides, not just one the file lacks", async () => {
+ expect(
+ await statusFor(
+ { ANTHROPIC_API_KEY: "sk-ant-key-from-file" },
+ { ANTHROPIC_API_KEY: "sk-ant-key-from-shell" },
+ ),
+ ).toEqual({
+ ok: true,
+ detail:
+ "found: ANTHROPIC_API_KEY (environment); a daemon started elsewhere will not see it",
+ });
+ });
+
+ it("leaves a file key unmarked when only an unrelated flag comes from the environment", async () => {
+ const status = await statusFor(
+ { OPENAI_API_KEY: "sk-real-openai-key", OPENAI_API_KEY_FOR_LLM: "false" },
+ { OPENAI_API_KEY_FOR_LLM: "true" },
+ );
+ expect(status.ok).toBe(true);
+ expect(status.detail).toBe("found: OPENAI_API_KEY");
+ });
+
+ it("ignores an undefined environment value instead of blanking the file key", async () => {
+ expect(
+ await statusFor({ ANTHROPIC_API_KEY: "sk-ant-real-key-value" }, {
+ ANTHROPIC_API_KEY: undefined,
+ }),
+ ).toEqual({ ok: true, detail: "found: ANTHROPIC_API_KEY" });
+ });
+
+ it("counts an exported key when no env file exists, as the daemon does", async () => {
+ const diagnostics = buildDiagnostics(
+ stubEffects({
+ envFileExists: () => false,
+ readEnvFile: () => ({}),
+ processEnv: () => ({ ANTHROPIC_API_KEY: "sk-ant-real-key-value" }),
+ }),
+ );
+ const check = diagnostics.find((d) => d.id === "no-llm-provider-key")!;
+ expect(await check.check(stubCtx())).toEqual({
+ ok: true,
+ detail:
+ "found: ANTHROPIC_API_KEY (environment); a daemon started elsewhere will not see it",
+ });
+ });
+
+ it("points at the env-missing fix when neither the file nor the environment has a key", async () => {
+ const diagnostics = buildDiagnostics(
+ stubEffects({
+ envFileExists: () => false,
+ readEnvFile: () => ({}),
+ processEnv: () => ({}),
+ }),
+ );
+ const check = diagnostics.find((d) => d.id === "no-llm-provider-key")!;
+ const status = await check.check(stubCtx());
+ expect(status.ok).toBe(false);
+ expect(status.detail).toContain("env-missing");
+ expect(await statusFor({}, {})).toEqual({ ok: false, detail: "no provider key set" });
+ });
+
+ it("keeps the agent-sdk label when the only key is reserved for embeddings", async () => {
+ expect(
+ await statusFor(
+ { OPENAI_API_KEY: "sk-real-openai-key", OPENAI_API_KEY_FOR_LLM: "false" },
+ { AGENTMEMORY_ALLOW_AGENT_SDK: "true" },
+ ),
+ ).toEqual({ ok: true, detail: "agent-sdk fallback, no API key" });
+ });
+
+ it("treats a placeholder exported in the environment as missing, unlike the daemon", async () => {
+ expect(
+ (
+ await statusFor(
+ { ANTHROPIC_API_KEY: "sk-ant-real-key-value" },
+ { ANTHROPIC_API_KEY: "your-key-here" },
+ )
+ ).ok,
+ ).toBe(false);
+ });
+ });
+
it("engine-version-mismatch fails when iii reports the wrong version", async () => {
const diagnostics = buildDiagnostics(
stubEffects({ iiiBinaryVersion: () => "0.99.99" }),
diff --git a/test/env-loader.test.ts b/test/env-loader.test.ts
index 4c31beba..ab2d89fc 100644
--- a/test/env-loader.test.ts
+++ b/test/env-loader.test.ts
@@ -139,6 +139,16 @@ describe("hydrateProcessEnvFromFile", () => {
expect(process.env["HYDRATE_WINS"]).toBe("from-process");
});
+ it("returns process.env as it was before the file was copied in", async () => {
+ writeEnv("HYDRATE_ONLY=from-file\nHYDRATE_WINS=from-file");
+ process.env["HYDRATE_WINS"] = "from-process";
+ const cfg = await freshConfig();
+ const before = cfg.hydrateProcessEnvFromFile();
+ expect(process.env["HYDRATE_ONLY"]).toBe("from-file");
+ expect(before["HYDRATE_ONLY"]).toBeUndefined();
+ expect(before["HYDRATE_WINS"]).toBe("from-process");
+ });
+
it("exposes a .env-only key via getEnvVar and, after hydrate, via raw process.env", async () => {
writeEnv("HYDRATE_ONLY=from-file");
const cfg = await freshConfig();