#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix(doctor): judge the LLM provider the way the daemon does (#1575)
Dmitrii Zhukovc5b8ebfb32eb
diff --git a/src/cli.ts b/src/cli.tsindex 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.tsindex 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.tsindex 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 burndiff --git a/test/cli-doctor-env-file.test.ts b/test/cli-doctor-env-file.test.tsnew file mode 100644index 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.tsindex 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.tsindex 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();