Skip to content

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

fix: embedding key precedence, structured SessionStart context, docker engine config (#1472)

Rohit Ghumarec51bf3f294a4
diff --git a/.env.example b/.env.example
index 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.md
index 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 unpr
Full 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 every
diff --git a/plugin/scripts/session-start.mjs b/plugin/scripts/session-start.mjs
index 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.md
index 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.ts
index 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 the
native 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_SECONDS
Window (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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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("");
+ });
+});