Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

---
Expand Down Expand Up @@ -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)
Expand Down
4 changes: 2 additions & 2 deletions docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand All @@ -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:
Expand Down
3 changes: 2 additions & 1 deletion plugin/skills/agentmemory-config/REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,15 @@
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`
- `AGENTMEMORY_AUTO_COMPRESS`
- `AGENTMEMORY_COMMIT_SHA`
- `AGENTMEMORY_COPILOT_MCP_BLOCK`
- `AGENTMEMORY_CWD`
- `AGENTMEMORY_DATA_DIR`
- `AGENTMEMORY_DEBUG`
- `AGENTMEMORY_DROP_STALE_INDEX`
- `AGENTMEMORY_EXPORT_ROOT`
Expand Down
139 changes: 139 additions & 0 deletions src/cli-data-dir.ts
Original file line number Diff line number Diff line change
@@ -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,
};
}
}
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

return {
dataDir: forInstance(defaultDir),
source: "default",
};
}
65 changes: 61 additions & 4 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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}).
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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) {
Expand All @@ -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) {
Expand All @@ -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"),
Expand Down Expand Up @@ -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[] = [];
Expand Down
Loading