Skip to content

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

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.md
index 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.yml
index 6b117652..a74cd82a 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -9,7 +9,7 @@ services:
image: busybox:1.36
user: "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:ro
restart: unless-stopped
logging:
diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md
index 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.ts
new file mode 100644
index 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.ts
index 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 multiple
daemons 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 repo
Environment:
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 the
native 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>): string
async 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.ts
new file mode 100644
index 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 });
+ }
+ });
+});