Engine writes data/ to caller's cwd — pollutes user repos when started from project root

[swiftugandan]

Summary

npx @agentmemory/agentmemory starts iii-engine with the current working directory as the state-store location. When the server is launched from inside a project (which is the default for the Claude Code plugin auto-start path, since Claude Code's cwd is the user's repo), the engine writes a data/ directory directly into the user's git working tree:

data/state_store.db/mem%3Aaccess.bin
data/state_store.db/mem%3Ahealth.bin
data/state_store.db/mem%3Amemories.bin
data/state_store.db/mem%3Aobs%3A<session-id>.bin
data/state_store.db/mem%3Aindex%3Abm25.bin
data/stream_store/stream%3Amem-live%3A<session-id>.bin
data/stream_store/stream%3Amem-live%3Aviewer.bin

These show up immediately in git status and are easy to accidentally commit. They also leak session ids and memory contents into whatever repo the user happened to be in when the server first started.

Repro

cd ~/some-project    # any git repo
npx -y @agentmemory/agentmemory   # let it become healthy
# in another shell:
cd ~/some-project && git status
# => Untracked: data/

Environment

• macOS 14 (darwin 23.6.0), x86_64
• agentmemory 0.9.9
• iii-engine 0.11.2 (the version agentmemory pins)
• Node from npx, no Docker fallback

Workaround

Start the server from a dedicated directory:

mkdir -p ~/.agentmemory
cd ~/.agentmemory && npx -y @agentmemory/agentmemory

This works, but it's fragile because:

1. The Claude Code plugin install instructions ("run npx @agentmemory/agentmemory in a separate terminal") don't mention cwd, so a typical user who pastes the install block into their project terminal will hit this.
2. There's no CLI flag or env var to override the data location (--help lists --port, --no-engine, --tools, --verbose, but nothing for state).
3. If/when any hook or skill auto-spawns the engine, it will inherit Claude Code's cwd (the repo) and recreate the problem.

Proposed fix

Make the state-store location explicit and default it outside any repo. A couple of equivalent shapes:

1. CLI flag + env var, defaulting to ~/.agentmemory/data (or platform-appropriate: $XDG_DATA_HOME/agentmemory on Linux, ~/Library/Application Support/agentmemory on macOS):

   agentmemory --data-dir ~/.agentmemory/data
   AGENTMEMORY_DATA_DIR=~/.agentmemory/data npx @agentmemory/agentmemory

2. Auto-relocate when started inside a git repo: detect .git in cwd or any ancestor, and if found, use ~/.agentmemory/data instead of ./data. Log a one-line warning so users aren't surprised.

(2) alone would catch every accidental case without needing users to set anything; (1) is still worth having for users who want to pin the location.

Happy to send a PR if you'd like — let me know which shape you prefer.

Why this matters

Plugin auto-installation is the headline path in the README ("/plugin marketplace add rohitg00/agentmemory and /plugin install agentmemory"). Anyone following that path from inside their repo gets engine state written into their working tree on the first run. The current default basically guarantees a footgun for the recommended install flow.

[mvanhorn]

Implemented in #314 — adds --data-dir and AGENTMEMORY_DATA_DIR, default to platform-appropriate user dir (~/Library/Application Support/agentmemory on macOS, $XDG_DATA_HOME/agentmemory on Linux).

[jonathanzhan1975]

I can still reproduce the practical impact of this on Windows with agentmemory 0.9.20, despite the comment that #314 added --data-dir / AGENTMEMORY_DATA_DIR.

Current impact

The dashboard at http://localhost:3113/#dashboard appeared to have no memories, even though the user had recorded ~200 observations the previous day.

The root cause was that the native engine state is still effectively tied to the process cwd because iii-config.yaml contains relative paths:

store_method: file_based
file_path: ./data/state_store.db

Starting agentmemory from different directories produced different state stores:

E:\文档\New project\data\state_store.db   # current dashboard, mostly empty
E:\works\data\state_store.db             # another empty/partial store
C:\Users\Lenovo\data\state_store.db      # previous real store

The previous real store contains the expected data:

{
  "sessions": 44,
  "validSessions": 14,
  "malformedSessions": 30,
  "memories": 143,
  "obsBuckets": 12,
  "observations": 212
}

The current dashboard/API was empty because it was reading a different cwd-local state store:

GET /agentmemory/sessions        -> []
GET /agentmemory/memories?latest=true -> []
GET /agentmemory/export          -> memories: [], observations: {}, sessions: []

Why this is worse than repo pollution

Besides creating data/ in arbitrary directories, this makes memories appear to disappear whenever the daemon is launched from a different cwd. Users can easily believe their memory data was lost, while it is actually stranded in another cwd-local data/state_store.db.

Environment

• Windows 11
• agentmemory 0.9.20
• native iii.exe engine
• Codex Desktop / PowerShell
• Engine command observed:

C:\Users\Lenovo\.local\bin\iii.exe --config C:\Users\Lenovo\AppData\Local\npm-cache\_npx\076f5982d055bff5\node_modules\@agentmemory\agentmemory\dist\iii-config.yaml

Suggested fix / acceptance criteria

Even if AGENTMEMORY_DATA_DIR exists, the default should not remain cwd-relative on Windows. The generated iii-config.yaml should use an absolute state path by default, for example:

%USERPROFILE%\.agentmemory\data\state_store.db
%USERPROFILE%\.agentmemory\data\stream_store

or a platform data dir equivalent. At minimum, startup should log the resolved data directory prominently, because this issue is otherwise very hard to diagnose.