#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix(cli): add --data-dir flag + AGENTMEMORY_DATA_DIR so engine state lives outside repos (#314)
Matt Van Hornd8b5267c367a
diff --git a/README.md b/README.mdindex 84d747f9..24751192 100644--- a/README.md+++ b/README.md@@ -224,6 +224,13 @@ You explain the same architecture every session. You re-discover the same bugs.npx @agentmemory/agentmemory```+By default, agentmemory stores iii-engine state outside the repository you start it from: `~/Library/Application Support/agentmemory` on macOS, `$XDG_DATA_HOME/agentmemory` or `~/.local/share/agentmemory` on Linux, and `%APPDATA%\agentmemory` on Windows. To choose a location, pass `--data-dir <path>` or set `AGENTMEMORY_DATA_DIR`:++```bash+npx @agentmemory/agentmemory --data-dir ~/.agentmemory-projects/main+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx @agentmemory/agentmemory+```+Latest release notes: [CHANGELOG.md](CHANGELOG.md).---@@ -1219,7 +1226,7 @@ agentmemory auto-detects from your environment. By default, no LLM calls are mad| Gemini | `GEMINI_API_KEY` | Also enables embeddings || OpenRouter | `OPENROUTER_API_KEY` | Any model || OpenAI API | `OPENAI_API_KEY` | Default `gpt-4o-mini`, override with `OPENAI_MODEL` |-| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) or `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=<your model>` | Anything OpenAI-API-compatible. Zero cost, runs on your hardware. See [Local models](#local-models-ollama-lm-studio-vllm) below. |+| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) or `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=<your model>` | Anything OpenAI-API-compatible. Zero cost, runs on your hardware. See [Local models](#local-models-ollama--lm-studio--vllm) below. || Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in only. Spawns `@anthropic-ai/claude-agent-sdk` sessions — used to cause unbounded Stop-hook recursion so it is no longer the default. |### Local models (Ollama / LM Studio / vLLM)diff --git a/docker-compose.yml b/docker-compose.ymlindex 6b117652..a74cd82a 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -9,7 +9,7 @@ services:image: busybox:1.36user: "0:0"volumes:- - iii-data:/data+ - "${AGENTMEMORY_DATA_DIR:-iii-data}:/data"entrypoint: ["sh", "-c", "chown -R 65532:65532 /data && chmod 755 /data"]restart: "no"@@ -34,7 +34,7 @@ services:- "127.0.0.1:3112:3112"- "127.0.0.1:9464:9464"volumes:- - iii-data:/data+ - "${AGENTMEMORY_DATA_DIR:-iii-data}:/data"- ./iii-config.docker.yaml:/app/config.yaml:rorestart: unless-stoppedlogging:diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.mdindex 08c873a4..e56e8743 100644--- a/plugin/skills/agentmemory-config/REFERENCE.md+++ b/plugin/skills/agentmemory-config/REFERENCE.md@@ -3,7 +3,7 @@Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded.<!-- AUTOGEN:env START - generated by scripts/skills/generate.ts, do not edit by hand -->-Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 34 recognized variables:+Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 35 recognized variables:- `AGENTMEMORY_AGENT_SCOPE`- `AGENTMEMORY_ALLOW_AGENT_SDK`@@ -11,6 +11,7 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e- `AGENTMEMORY_COMMIT_SHA`- `AGENTMEMORY_COPILOT_MCP_BLOCK`- `AGENTMEMORY_CWD`+- `AGENTMEMORY_DATA_DIR`- `AGENTMEMORY_DEBUG`- `AGENTMEMORY_DROP_STALE_INDEX`- `AGENTMEMORY_EXPORT_ROOT`diff --git a/src/cli-data-dir.ts b/src/cli-data-dir.tsnew file mode 100644index 00000000..e27fc60a--- /dev/null+++ b/src/cli-data-dir.ts@@ -0,0 +1,139 @@+import { existsSync } from "node:fs";+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";+import { homedir, platform } from "node:os";++export type DataDirSource = "flag" | "env" | "default";++export type ResolvedDataDir = {+ dataDir: string;+ source: DataDirSource;+ relocatedFrom?: string;+};++type ResolveDataDirOptions = {+ args?: string[];+ env?: NodeJS.ProcessEnv;+ cwd?: string;+ home?: string;+ platform?: NodeJS.Platform;+};++function argValue(args: string[], name: string): string | undefined {+ const equals = `${name}=`;+ const inline = args.find((arg) => arg.startsWith(equals));+ if (inline) return inline.slice(equals.length);++ const idx = args.indexOf(name);+ if (idx !== -1) return args[idx + 1];+ return undefined;+}++function expandHome(pathValue: string, home: string): string {+ if (pathValue === "~") return home;+ if (pathValue.startsWith("~/") || pathValue.startsWith("~\\")) {+ return join(home, pathValue.slice(2));+ }+ return pathValue;+}++function absoluteDataDir(pathValue: string, cwd: string, home: string): string {+ const expanded = expandHome(pathValue, home);+ return isAbsolute(expanded) ? expanded : resolve(cwd, expanded);+}++function platformDefaultDataDir(+ env: NodeJS.ProcessEnv,+ home: string,+ nodePlatform: NodeJS.Platform,+ useXdg = true,+): string {+ if (nodePlatform === "darwin") {+ return join(home, "Library", "Application Support", "agentmemory");+ }+ if (nodePlatform === "win32") {+ const appData = env["APPDATA"];+ return appData+ ? join(appData, "agentmemory")+ : join(home, ".agentmemory");+ }+ const xdgDataHome = env["XDG_DATA_HOME"];+ if (useXdg && xdgDataHome && isAbsolute(xdgDataHome)) {+ return join(xdgDataHome, "agentmemory");+ }+ return join(home, ".local", "share", "agentmemory");+}++function nearestGitParent(pathValue: string): string | undefined {+ let current = pathValue;+ while (true) {+ if (existsSync(join(current, ".git"))) return current;+ const parent = dirname(current);+ if (parent === current) return undefined;+ current = parent;+ }+}++function isWithin(parent: string, child: string): boolean {+ const pathFromParent = relative(parent, child);+ return (+ pathFromParent === "" ||+ (pathFromParent !== ".." &&+ !pathFromParent.startsWith(`..${sep}`) &&+ !isAbsolute(pathFromParent))+ );+}++export function resolveDataDir(options: ResolveDataDirOptions = {}): ResolvedDataDir {+ const args = options.args ?? process.argv.slice(2);+ const env = options.env ?? process.env;+ const cwd = options.cwd ?? process.cwd();+ const home = options.home ?? homedir();+ const nodePlatform = options.platform ?? platform();+ const parsedInstance = parseInt(argValue(args, "--instance") ?? "0", 10);+ const instance =+ parsedInstance > 0 && parsedInstance <= 50 ? parsedInstance : 0;+ const forInstance = (dataDir: string) =>+ instance ? join(dataDir, `instance-${instance}`) : dataDir;++ const flagValue = argValue(args, "--data-dir");+ if (flagValue) {+ return {+ dataDir: forInstance(absoluteDataDir(flagValue, cwd, home)),+ source: "flag",+ };+ }++ const envValue = env["AGENTMEMORY_DATA_DIR"];+ if (envValue) {+ return {+ dataDir: forInstance(absoluteDataDir(envValue, cwd, home)),+ source: "env",+ };+ }++ const legacyDir = resolve(cwd, "data");+ const hasLegacyStore =+ existsSync(join(legacyDir, "state_store.db")) ||+ existsSync(join(legacyDir, "iii-config.yaml"));+ if (instance === 0 && hasLegacyStore) {+ return { dataDir: legacyDir, source: "default" };+ }++ const defaultDir = platformDefaultDataDir(env, home, nodePlatform);+ const gitParent = nearestGitParent(cwd);+ if (gitParent && isWithin(gitParent, defaultDir)) {+ const relocated = platformDefaultDataDir(env, home, nodePlatform, false);+ if (relocated !== defaultDir) {+ return {+ dataDir: forInstance(relocated),+ source: "default",+ relocatedFrom: defaultDir,+ };+ }+ }++ return {+ dataDir: forInstance(defaultDir),+ source: "default",+ };+}diff --git a/src/cli.ts b/src/cli.tsindex 93b90749..d763eada 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -64,6 +64,7 @@ import { knownAgents } from "./cli/connect/index.js";const ALL_TOOLS_COUNT = getAllTools().length;const CORE_TOOLS_COUNT = getAllTools().filter((t) => ESSENTIAL_TOOLS.has(t.name)).length;+import { resolveDataDir } from "./cli-data-dir.js";const __dirname = dirname(fileURLToPath(import.meta.url));const args = process.argv.slice(2);@@ -198,10 +199,12 @@ Options:--instance <N> Shortcut for --port (3111 + N*100) to run multipledaemons side-by-side without env gymnastics.--instance 1 -> 3211/3212/3213/49234, etc. (max N=50)+ --data-dir <path> Store iii-engine state outside the current repoEnvironment:AGENTMEMORY_URL Full REST base URL (e.g. http://localhost:3111).Honored by status, doctor, and MCP shim commands.+ AGENTMEMORY_DATA_DIR State directory fallback when --data-dir is not set.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}).@@ -254,6 +257,11 @@ if (instanceIdx !== -1 && args[instanceIdx + 1]) {}}+const dataDirResolution = resolveDataDir({ args });+if (dataDirResolution.source !== "default") {+ process.env["AGENTMEMORY_DATA_DIR"] = dataDirResolution.dataDir;+}+const skipEngine = args.includes("--no-engine");function getRestPort(): number {@@ -402,6 +410,50 @@ function findIiiConfig(): string {return "";}+function yamlSingleQuoted(value: string): string {+ return `'${value.replace(/'/g, "''")}'`;+}++function renderIiiConfig(template: string, dataDir: string): string {+ return template+ .replace(+ "file_path: ./data/state_store.db",+ `file_path: ${yamlSingleQuoted(join(dataDir, "state_store.db"))}`,+ )+ .replace(+ "file_path: ./data/stream_store",+ `file_path: ${yamlSingleQuoted(join(dataDir, "stream_store"))}`,+ );+}++function writeRuntimeIiiConfig(configPath: string, dataDir: string): string {+ mkdirSync(dataDir, { recursive: true });+ const runtimeConfigPath = join(dataDir, "iii-config.yaml");+ writeFileSync(+ runtimeConfigPath,+ renderIiiConfig(readFileSync(configPath, "utf8"), dataDir),+ );+ return runtimeConfigPath;+}++function warnIfRelocatedDataDir(): void {+ if (!dataDirResolution.relocatedFrom) return;++ try {+ mkdirSync(dataDirResolution.dataDir, { recursive: true });+ const marker = join(dataDirResolution.dataDir, ".cwd-relocation-warning");+ if (existsSync(marker)) return;+ p.log.warn(+ `Default data dir ${dataDirResolution.relocatedFrom} is inside a git worktree; using ${dataDirResolution.dataDir} instead.`,+ );+ writeFileSync(marker, new Date().toISOString());+ } catch {+ p.log.warn(+ `Default data dir ${dataDirResolution.relocatedFrom} is inside a git worktree; using ${dataDirResolution.dataDir} instead.`,+ );+ }+}+function whichBinary(name: string): string | null {const cmd = IS_WINDOWS ? "where" : "which";try {@@ -925,8 +977,12 @@ function pickCompatibleIii(candidates: Array<string | null | undefined>): stringasync function startEngine(): Promise<boolean> {const configPath = findIiiConfig();+ warnIfRelocatedDataDir();+ const runtimeConfigPath = configPath+ ? writeRuntimeIiiConfig(configPath, dataDirResolution.dataDir)+ : "";const pathIii = whichBinary("iii");- vlog(`iii binary: ${pathIii ?? "(not on PATH)"}, config: ${configPath || "(not found)"}`);+ vlog(`iii binary: ${pathIii ?? "(not on PATH)"}, config: ${runtimeConfigPath || "(not found)"}`);const fallbacks = fallbackIiiPaths().filter((p) => existsSync(p));for (const f of fallbacks) {@@ -936,12 +992,12 @@ async function startEngine(): Promise<boolean> {let iiiBin = pickCompatibleIii([pathIii, ...fallbacks]);- if (iiiBin && configPath) {+ if (iiiBin && runtimeConfigPath) {if (iiiBin !== pathIii) {p.log.info(`Using iii at: ${c.dim(iiiBin)} (v${c.accent(IIPINNED_VERSION)})`);process.env["PATH"] = `${dirname(iiiBin)}${PATH_DELIMITER}${process.env["PATH"] ?? ""}`;}- return startIiiBin(iiiBin, configPath);+ return startIiiBin(iiiBin, runtimeConfigPath);}if (pathIii && !iiiBin) {@@ -959,6 +1015,7 @@ async function startEngine(): Promise<boolean> {const dockerBin = whichBinary("docker");vlog(`docker binary: ${dockerBin ?? "(not on PATH)"}`);+ mkdirSync(dataDirResolution.dataDir, { recursive: true });const dockerComposeCandidates = [join(__dirname, "..", "docker-compose.yml"),join(__dirname, "docker-compose.yml"),@@ -2659,7 +2716,7 @@ async function runImportJsonl(): Promise<void> {// consumed alongside the flag so they don't leak into positional// args (e.g. `--port 3112 import-jsonl` would otherwise turn// 3112 into pathArg).- const VALUE_FLAGS = new Set(["--port", "--tools"]);+ const VALUE_FLAGS = new Set(["--port", "--tools", "--data-dir"]);let maxFiles: number | undefined;const tail = args.slice(1);const positional: string[] = [];diff --git a/test/cli-data-dir.test.ts b/test/cli-data-dir.test.tsnew file mode 100644index 00000000..faf45367--- /dev/null+++ b/test/cli-data-dir.test.ts@@ -0,0 +1,150 @@+import { describe, expect, it } from "vitest";+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { resolveDataDir } from "../src/cli-data-dir.js";++describe("resolveDataDir", () => {+ it("prefers --data-dir over AGENTMEMORY_DATA_DIR", () => {+ const cwd = "/repo/project";+ const home = "/home/alex";+ const resolved = resolveDataDir({+ args: ["--data-dir", "~/flag-state"],+ env: { AGENTMEMORY_DATA_DIR: "~/env-state" },+ cwd,+ home,+ platform: "linux",+ });++ expect(resolved).toEqual({+ dataDir: join(home, "flag-state"),+ source: "flag",+ });+ });++ it("uses AGENTMEMORY_DATA_DIR when --data-dir is absent", () => {+ const cwd = "/repo/project";+ const home = "/home/alex";+ const resolved = resolveDataDir({+ args: [],+ env: { AGENTMEMORY_DATA_DIR: "~/env-state" },+ cwd,+ home,+ platform: "linux",+ });++ expect(resolved).toEqual({+ dataDir: join(home, "env-state"),+ source: "env",+ });+ });++ it("defaults to a platform data directory outside cwd", () => {+ const cwd = "/repo/project";+ const home = "/home/alex";+ const resolved = resolveDataDir({+ args: [],+ env: {},+ cwd,+ home,+ platform: "linux",+ });++ expect(resolved).toEqual({+ dataDir: join(home, ".local", "share", "agentmemory"),+ source: "default",+ });+ expect(resolved.dataDir.startsWith(cwd)).toBe(false);+ });++ it("uses the macOS Application Support default", () => {+ const home = "/Users/alex";+ const resolved = resolveDataDir({+ args: [],+ env: {},+ cwd: "/repo/project",+ home,+ platform: "darwin",+ });++ expect(resolved).toEqual({+ dataDir: join(home, "Library", "Application Support", "agentmemory"),+ source: "default",+ });+ });++ it("adopts legacy data without sharing it with another instance", () => {+ const cwd = mkdtempSync(join(tmpdir(), "agentmemory-data-"));+ mkdirSync(join(cwd, ".git"));+ mkdirSync(join(cwd, "data"));+ writeFileSync(join(cwd, "data", "iii-config.yaml"), "");+ const home = "/home/alex";+ const base = { cwd, home, platform: "linux" as const };+ const defaultDir = join(home, ".local", "share", "agentmemory");+ try {+ expect(resolveDataDir({ args: [], env: {}, ...base })).toEqual({+ dataDir: join(cwd, "data"),+ source: "default",+ });+ expect(+ resolveDataDir({+ args: ["--instance", "1"],+ env: { XDG_DATA_HOME: join(cwd, "xdg") },+ ...base,+ }),+ ).toEqual({+ dataDir: join(defaultDir, "instance-1"),+ source: "default",+ relocatedFrom: join(cwd, "xdg", "agentmemory"),+ });+ } finally {+ rmSync(cwd, { recursive: true, force: true });+ }+ });++ it("does not adopt an unrelated data directory", () => {+ const cwd = mkdtempSync(join(tmpdir(), "agentmemory-data-"));+ mkdirSync(join(cwd, ".git"));+ mkdirSync(join(cwd, "data"));+ const home = "/home/alex";+ try {+ expect(+ resolveDataDir({+ args: [],+ env: {},+ cwd,+ home,+ platform: "linux",+ }),+ ).toEqual({+ dataDir: join(home, ".local", "share", "agentmemory"),+ source: "default",+ });+ } finally {+ rmSync(cwd, { recursive: true, force: true });+ }+ });++ it("keeps an XDG data directory outside the current git worktree", () => {+ const cwd = mkdtempSync(join(tmpdir(), "agentmemory-data-"));+ mkdirSync(join(cwd, ".git"));+ const xdgDataHome = mkdtempSync(join(tmpdir(), "agentmemory-xdg-"));+ try {+ expect(+ resolveDataDir({+ args: [],+ env: { XDG_DATA_HOME: xdgDataHome },+ cwd,+ home: "/home/alex",+ platform: "linux",+ }),+ ).toEqual({+ dataDir: join(xdgDataHome, "agentmemory"),+ source: "default",+ });+ } finally {+ rmSync(cwd, { recursive: true, force: true });+ rmSync(xdgDataHome, { recursive: true, force: true });+ }+ });+});