#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix: embedding key precedence, structured SessionStart context, docker engine config (#1472)
Rohit Ghumarec51bf3f294a4
diff --git a/.env.example b/.env.exampleindex af00f191..7afb54b8 100644--- a/.env.example+++ b/.env.example@@ -96,6 +96,8 @@# COHERE_API_KEY=... # General-purpose embeddings# Reuses OPENAI_API_KEY / OPENAI_BASE_URL above when EMBEDDING_PROVIDER=openai.+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set# OPENAI_EMBEDDING_MODEL=text-embedding-3-small # Embedding model when EMBEDDING_PROVIDER=openai# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table@@ -171,6 +173,7 @@# ~/Library/Application Support/agentmemory; Linux $XDG_DATA_HOME/agentmemory# or ~/.local/share/agentmemory; Windows %APPDATA%\agentmemory.# AGENTMEMORY_DATA_DIR=/absolute/path+# AGENTMEMORY_III_CONFIG=/path/to/iii-config.yaml # Engine config the CLI starts from; the bundled default binds 127.0.0.1# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes state to disk; a crash loses at most this much# AGENTMEMORY_USE_DOCKER=1 # Prefer bundled Docker even when a compatible native iii binary exists# AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup # Default destination for `agentmemory export`diff --git a/README.md b/README.mdindex 1c22f8af..71235b98 100644--- a/README.md+++ b/README.md@@ -1292,6 +1292,14 @@ On engine 0.22.x keep the `iii-` prefixed names for the builtins above; the unprFull registry: [workers.iii.dev](https://workers.iii.dev). Every worker there composes through the same primitives agentmemory uses, and the agentmemory you already have is one of them.+### Engine config and bind address++`agentmemory start` reads the engine config from the first file that exists: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` in the current directory, `~/.agentmemory/iii-config.yaml`, then the bundled `iii-config.yaml`. On every start it renders that file (data paths, ports, state backend) into `~/.agentmemory/data/iii-config.runtime.yaml` and launches the engine with the rendered copy, so edit the source file, not the rendered one. The `host:` values of the source file are kept as written.++The bundled `iii-config.yaml` binds `127.0.0.1` on purpose, and that default also applies inside a container. A CLI started in a container listens on the container's loopback, so published ports reach nothing. To serve a containerized CLI through published ports, set `AGENTMEMORY_III_CONFIG` to a config that binds `0.0.0.0`. The packaged `iii-config.docker.yaml` is one: it binds `iii-http`, `iii-stream` and the engine port to `0.0.0.0` and stores state under `/data`, so mount a writable volume there. Keep `AGENTMEMORY_SECRET` set, and publish only the ports you need, on `127.0.0.1` or behind a proxy you trust.++This repo's `docker-compose.yml` does not go through the CLI's config lookup: it mounts `iii-config.docker.yaml` at `/app/config.yaml`, and the `iii-engine` container starts with `--config /app/config.yaml`. The one-click [deploy templates](deploy/) write their own `0.0.0.0` config in their entrypoints.+### Storage backend: file (default) vs redis`iii-state` and `iii-stream` default to iii-engine's bundled file-based KV store: one JSON file per scope, held in the engine process's memory and rewritten to disk on a timer. That's the right default for a single-user local install; a shared daemon with several concurrent writers gets real per-key writes from Redis instead, at the cost of a network round trip per operation (every `state::*` call still serializes on one Redis connection, so this trades the file store's lock for a socket, not for parallelism).@@ -1589,6 +1597,8 @@ Create `~/.agentmemory/.env`:# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies# OPENAI_EMBEDDING_MODEL=text-embedding-3-small# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set# Outbound LLM / embedding timeout# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to everydiff --git a/plugin/scripts/session-start.mjs b/plugin/scripts/session-start.mjsindex 5b846d14..4a68ef54 100755--- a/plugin/scripts/session-start.mjs+++ b/plugin/scripts/session-start.mjs@@ -116,9 +116,16 @@ function authHeaders() {if (SECRET) h["Authorization"] = `Bearer ${SECRET}`;return h;}+function isPlainTextHost() {+ return Boolean(process.env["FACTORY_PROJECT_DIR"] || process.env["DROID_PLUGIN_ROOT"]);+}+function wantsStructuredOutput(data) {+ if (process.env["DEVIN_PROJECT_DIR"] || data.prompt_id !== void 0) return true;+ return data.hook_event_name === "SessionStart" && !isPlainTextHost();+}function contextPayload(data, context) {if (typeof data.cursor_version === "string" || data.hook_event_name === "sessionStart") return JSON.stringify({ additional_context: context });- if (process.env["DEVIN_PROJECT_DIR"] || data.prompt_id !== void 0) return JSON.stringify({ hookSpecificOutput: {+ if (wantsStructuredOutput(data)) return JSON.stringify({ hookSpecificOutput: {hookEventName: "SessionStart",additionalContext: context} });diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.mdindex 27e5e8e1..656dcf19 100644--- a/plugin/skills/agentmemory-config/REFERENCE.md+++ b/plugin/skills/agentmemory-config/REFERENCE.md@@ -79,6 +79,12 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e- `AGENTMEMORY_VIEWER_URL`<!-- AUTOGEN:env END -->+## Engine config++- `AGENTMEMORY_III_CONFIG`: path to the engine config the CLI starts from. Lookup order: this variable, `./iii-config.yaml`, `~/.agentmemory/iii-config.yaml`, the bundled `iii-config.yaml`. The chosen file is rendered into `~/.agentmemory/data/iii-config.runtime.yaml` on every start; its `host:` values are kept as written.++The bundled config binds `127.0.0.1`, also inside a container. To reach a containerized CLI through published ports, point `AGENTMEMORY_III_CONFIG` at a config that binds `0.0.0.0` (the packaged `iii-config.docker.yaml` does, and stores state under `/data`) and keep `AGENTMEMORY_SECRET` set. The repo's `docker-compose.yml` mounts `iii-config.docker.yaml` straight into the engine container and does not use this lookup. See the README section "Engine config and bind address".+## State backend- `AGENTMEMORY_STATE_BACKEND`: `file` (default) or `redis`. Anything else stops startup with an error.diff --git a/src/cli.ts b/src/cli.tsindex 6fbd15d3..067a324a 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -252,6 +252,9 @@ Environment:AGENTMEMORY_USE_DOCKER=1 Prefer the bundled docker-compose path over thenative iii-engine binary on first run.AGENTMEMORY_III_VERSION Override pinned iii-engine version (default ${IIPINNED_VERSION}).+ AGENTMEMORY_III_CONFIG Engine config to start from (default: ./iii-config.yaml,+ then ~/.agentmemory/iii-config.yaml, then the bundled+ loopback-only config).AGENTMEMORY_FOLLOWUP_WINDOW_SECONDSWindow (seconds) for the smart-search follow-up diagnostic(default 30). Long values overcount, short values undercount.diff --git a/src/config.ts b/src/config.tsindex 693871f2..5b6c4a24 100644--- a/src/config.ts+++ b/src/config.ts@@ -329,7 +329,7 @@ export function detectEmbeddingProvider(if (forced) return forced;if (source["GEMINI_API_KEY"]) return "gemini";- if (source["OPENAI_API_KEY"]) return "openai";+ if (source["OPENAI_API_KEY"] || source["OPENAI_EMBEDDING_API_KEY"]) return "openai";if (source["VOYAGE_API_KEY"]) return "voyage";if (source["COHERE_API_KEY"]) return "cohere";if (source["OPENROUTER_API_KEY"]) return "openrouter";diff --git a/src/hooks/session-start.ts b/src/hooks/session-start.tsindex 33e029af..2103216d 100644--- a/src/hooks/session-start.ts+++ b/src/hooks/session-start.ts@@ -24,6 +24,19 @@ function authHeaders(): Record<string, string> {return h;}+function isPlainTextHost(): boolean {+ return Boolean(+ process.env["FACTORY_PROJECT_DIR"] || process.env["DROID_PLUGIN_ROOT"],+ );+}++function wantsStructuredOutput(data: Record<string, unknown>): boolean {+ if (process.env["DEVIN_PROJECT_DIR"] || data.prompt_id !== undefined) {+ return true;+ }+ return data.hook_event_name === "SessionStart" && !isPlainTextHost();+}+function contextPayload(data: Record<string, unknown>, context: string): string {if (typeof data.cursor_version === "string" ||@@ -31,7 +44,7 @@ function contextPayload(data: Record<string, unknown>, context: string): string) {return JSON.stringify({ additional_context: context });}- if (process.env["DEVIN_PROJECT_DIR"] || data.prompt_id !== undefined) {+ if (wantsStructuredOutput(data)) {return JSON.stringify({hookSpecificOutput: {hookEventName: "SessionStart",diff --git a/src/providers/embedding/index.ts b/src/providers/embedding/index.tsindex d18de232..58f48a9f 100644--- a/src/providers/embedding/index.ts+++ b/src/providers/embedding/index.ts@@ -35,7 +35,7 @@ export function createEmbeddingProvider(): EmbeddingProvider | null {case "gemini":return withDimensionGuard(new GeminiEmbeddingProvider(getEnvVar("GEMINI_API_KEY")!));case "openai":- return withDimensionGuard(new OpenAIEmbeddingProvider(getEnvVar("OPENAI_API_KEY")!));+ return withDimensionGuard(new OpenAIEmbeddingProvider());case "voyage":return withDimensionGuard(new VoyageEmbeddingProvider(getEnvVar("VOYAGE_API_KEY")!));case "cohere":diff --git a/src/providers/embedding/openai.ts b/src/providers/embedding/openai.tsindex a048b902..2c088e8e 100644--- a/src/providers/embedding/openai.ts+++ b/src/providers/embedding/openai.ts@@ -26,9 +26,9 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {// then fall back to OPENAI_API_KEY. Allows e.g. a placeholder key for// local endpoints that ignore Authorization (most do).this.apiKey =- apiKey ||- getEnvVar("OPENAI_EMBEDDING_API_KEY") ||- getEnvVar("OPENAI_API_KEY") ||+ apiKey?.trim() ||+ getEnvVar("OPENAI_EMBEDDING_API_KEY")?.trim() ||+ getEnvVar("OPENAI_API_KEY")?.trim() ||"";if (!this.apiKey) {throw new Error(diff --git a/test/embedding-key-precedence.test.ts b/test/embedding-key-precedence.test.tsnew file mode 100644index 00000000..2d24e03e--- /dev/null+++ b/test/embedding-key-precedence.test.ts@@ -0,0 +1,108 @@+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { join } from "node:path";+import { tmpdir } from "node:os";++const KEYS = [+ "EMBEDDING_PROVIDER",+ "GEMINI_API_KEY",+ "OPENAI_API_KEY",+ "OPENAI_EMBEDDING_API_KEY",+ "OPENAI_BASE_URL",+ "OPENAI_EMBEDDING_BASE_URL",+ "OPENAI_EMBEDDING_MODEL",+ "OPENAI_EMBEDDING_DIMENSIONS",+ "VOYAGE_API_KEY",+ "COHERE_API_KEY",+ "OPENROUTER_API_KEY",+];++describe("OpenAI embedding key precedence", () => {+ const saved: Record<string, string | undefined> = {};+ let tmpHome: string;++ beforeEach(() => {+ tmpHome = mkdtempSync(join(tmpdir(), "am-embed-key-"));+ for (const k of [...KEYS, "HOME", "USERPROFILE"]) saved[k] = process.env[k];+ for (const k of KEYS) delete process.env[k];+ process.env["HOME"] = tmpHome;+ process.env["USERPROFILE"] = tmpHome;+ vi.resetModules();+ });++ afterEach(() => {+ for (const [k, v] of Object.entries(saved)) {+ if (v === undefined) delete process.env[k];+ else process.env[k] = v;+ }+ rmSync(tmpHome, { recursive: true, force: true });+ vi.restoreAllMocks();+ vi.resetModules();+ });++ async function embedAndCapture(): Promise<{ url: string; auth: string }> {+ const { createEmbeddingProvider } = await import(+ "../src/providers/embedding/index.js"+ );+ const provider = createEmbeddingProvider();+ expect(provider?.name).toBe("openai");+ const fetchSpy = vi+ .spyOn(globalThis, "fetch")+ .mockResolvedValue(+ new Response(+ JSON.stringify({ data: [{ embedding: new Array(1536).fill(0.1) }] }),+ { status: 200 },+ ),+ );+ await provider!.embed("hello");+ const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];+ const headers = init.headers as Record<string, string>;+ return { url, auth: headers["Authorization"] ?? headers["authorization"] ?? "" };+ }++ it("sends OPENAI_EMBEDDING_API_KEY when both keys are set", async () => {+ process.env["OPENAI_API_KEY"] = "chat-key";+ process.env["OPENAI_EMBEDDING_API_KEY"] = "embed-key";+ const { auth } = await embedAndCapture();+ expect(auth).toBe("Bearer embed-key");+ });++ it("falls back to OPENAI_API_KEY when no embedding key is set", async () => {+ process.env["OPENAI_API_KEY"] = "chat-key";+ const { auth } = await embedAndCapture();+ expect(auth).toBe("Bearer chat-key");+ });++ it("treats a blank OPENAI_EMBEDDING_API_KEY as unset", async () => {+ process.env["OPENAI_API_KEY"] = "chat-key";+ process.env["OPENAI_EMBEDDING_API_KEY"] = " ";+ const { auth } = await embedAndCapture();+ expect(auth).toBe("Bearer chat-key");+ });++ it("pairs the embedding key with OPENAI_EMBEDDING_BASE_URL", async () => {+ process.env["OPENAI_API_KEY"] = "chat-key";+ process.env["OPENAI_BASE_URL"] = "https://chat.example.com";+ process.env["OPENAI_EMBEDDING_BASE_URL"] = "https://embed.example.com";+ process.env["OPENAI_EMBEDDING_API_KEY"] = "embed-key";+ const { url, auth } = await embedAndCapture();+ expect(url).toBe("https://embed.example.com/v1/embeddings");+ expect(auth).toBe("Bearer embed-key");+ });++ it("selects the openai provider when only OPENAI_EMBEDDING_API_KEY is set", async () => {+ process.env["OPENAI_EMBEDDING_API_KEY"] = "embed-key";+ const { auth } = await embedAndCapture();+ expect(auth).toBe("Bearer embed-key");+ });++ it("reads the embedding key from ~/.agentmemory/.env", async () => {+ mkdirSync(join(tmpHome, ".agentmemory"), { recursive: true });+ writeFileSync(+ join(tmpHome, ".agentmemory", ".env"),+ "OPENAI_API_KEY=chat-key\nOPENAI_EMBEDDING_API_KEY=file-embed-key\n",+ );+ const { auth } = await embedAndCapture();+ expect(auth).toBe("Bearer file-embed-key");+ });+});diff --git a/test/engine-config.test.ts b/test/engine-config.test.tsindex 7affe486..6f0213d4 100644--- a/test/engine-config.test.ts+++ b/test/engine-config.test.ts@@ -216,6 +216,31 @@ describe("renderEngineConfig", () => {});});+describe("renderEngineConfig bind hosts", () => {+ const ports = { restPort: 3111, streamPort: 3112, viewerPort: 3113, enginePort: 49134 };+ const hostsOf = (text: string) =>+ [...text.matchAll(/^\s*host:\s*(\S+)\s*$/gm)].map((m) => m[1]);++ it("keeps the bundled config on loopback", () => {+ const source = readFileSync(join(import.meta.dirname, "..", "iii-config.yaml"), "utf8");+ const hosts = hostsOf(renderEngineConfig(source, { dataDir: "/tmp/am", ports }));+ expect(hosts.length).toBeGreaterThan(0);+ expect(new Set(hosts)).toEqual(new Set(["127.0.0.1"]));+ });++ it("keeps the 0.0.0.0 binds of a config chosen through AGENTMEMORY_III_CONFIG", () => {+ const source = readFileSync(+ join(import.meta.dirname, "..", "iii-config.docker.yaml"),+ "utf8",+ );+ const rendered = renderEngineConfig(source, { dataDir: "/tmp/am", ports });+ expect(hostsOf(rendered)).toEqual(["0.0.0.0", "0.0.0.0", "0.0.0.0"]);+ expect(rendered).toContain("port: 3111");+ expect(rendered).toContain("port: 3112");+ expect(rendered).toContain("port: 49134");+ });+});+describe("clearPersistedBuiltinConfig", () => {const configPath = join("/srv", "state", "iii-config.runtime.yaml");diff --git a/test/session-start-output.test.ts b/test/session-start-output.test.tsnew file mode 100644index 00000000..c33ff350--- /dev/null+++ b/test/session-start-output.test.ts@@ -0,0 +1,117 @@+import { describe, expect, it } from "vitest";+import { join, resolve } from "node:path";+import { createServer } from "node:http";+import { spawn } from "node:child_process";++const script = join(resolve(__dirname, ".."), "plugin", "scripts", "session-start.mjs");+const CONTEXT = '<agentmemory-context project="repo">remembered "quoted"\nline</agentmemory-context>';++const HOST_ENV_KEYS = [+ "AGENTMEMORY_INJECT_CONTEXT",+ "DEVIN_PROJECT_DIR",+ "FACTORY_PROJECT_DIR",+ "DROID_PLUGIN_ROOT",+];++async function runSessionStart(+ payload: Record<string, unknown>,+ env: Record<string, string> = {},+): Promise<{ stdout: string }> {+ const server = createServer((req, res) => {+ req.resume();+ req.on("end", () => {+ res.writeHead(200, { "Content-Type": "application/json" });+ res.end(JSON.stringify({ context: CONTEXT }));+ });+ });+ await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));+ const address = server.address();+ if (!address || typeof address === "string") {+ server.close();+ throw new Error("test server did not bind to a TCP port");+ }+ const baseEnv: Record<string, string | undefined> = { ...process.env };+ for (const k of HOST_ENV_KEYS) delete baseEnv[k];+ try {+ const child = spawn(process.execPath, [script], {+ env: {+ ...baseEnv,+ AGENTMEMORY_URL: `http://127.0.0.1:${address.port}`,+ AGENTMEMORY_SECRET: "",+ ...env,+ },+ stdio: ["pipe", "pipe", "ignore"],+ });+ let stdout = "";+ child.stdout.on("data", (chunk) => {+ stdout += chunk;+ });+ child.stdin.end(JSON.stringify(payload));+ await new Promise<void>((resolveExit, reject) => {+ const timeout = setTimeout(() => {+ child.kill();+ reject(new Error("session-start timed out"));+ }, 5000);+ child.on("error", reject);+ child.on("close", () => {+ clearTimeout(timeout);+ resolveExit();+ });+ });+ return { stdout };+ } finally {+ await new Promise<void>((r) => server.close(() => r()));+ }+}++const hookPayload = {+ session_id: "ses-1",+ cwd: "/repo",+ hook_event_name: "SessionStart",+ source: "startup",+};++describe("session-start stdout shape", () => {+ it("wraps context in the structured SessionStart envelope for hook_event_name payloads", async () => {+ const { stdout } = await runSessionStart(hookPayload, {+ AGENTMEMORY_INJECT_CONTEXT: "true",+ });+ expect(JSON.parse(stdout)).toEqual({+ hookSpecificOutput: {+ hookEventName: "SessionStart",+ additionalContext: CONTEXT,+ },+ });+ });++ it("keeps plain text for payloads without hook_event_name", async () => {+ const { stdout } = await runSessionStart(+ { sessionId: "ses-2", cwd: "/repo" },+ { AGENTMEMORY_INJECT_CONTEXT: "true" },+ );+ expect(stdout).toBe(CONTEXT);+ });++ it("keeps plain text on hosts that read stdout as context", async () => {+ const { stdout } = await runSessionStart(hookPayload, {+ AGENTMEMORY_INJECT_CONTEXT: "true",+ FACTORY_PROJECT_DIR: "/repo",+ });+ expect(stdout).toBe(CONTEXT);+ });++ it("keeps the camelCase additional_context shape for sessionStart payloads", async () => {+ const { stdout } = await runSessionStart(+ { conversation_id: "c-1", hook_event_name: "sessionStart", cursor_version: "1.0" },+ { AGENTMEMORY_INJECT_CONTEXT: "true" },+ );+ expect(JSON.parse(stdout)).toEqual({ additional_context: CONTEXT });+ });++ it("prints nothing when injection is off, for either payload shape", async () => {+ const structured = await runSessionStart(hookPayload);+ const plain = await runSessionStart({ sessionId: "ses-3", cwd: "/repo" });+ expect(structured.stdout).toBe("");+ expect(plain.stdout).toBe("");+ });+});