diff --git a/README.md b/README.md index 84d747f9b0..247511929b 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 ` 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=` | 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=` | 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 6b1176521d..a74cd82a1a 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 08c873a444..e56e8743e1 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. -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 0000000000..e27fc60a90 --- /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 93b907491d..d763eada3d 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 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 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 async function startEngine(): Promise { 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 { 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 { 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 { // 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 0000000000..faf453676f --- /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 }); + } + }); +});