Repository navigation
Description
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/agentmemoryThis works, but it's fragile because:
- The Claude Code plugin install instructions ("run
npx @agentmemory/agentmemoryin a separate terminal") don't mention cwd, so a typical user who pastes the install block into their project terminal will hit this. - There's no CLI flag or env var to override the data location (
--helplists--port,--no-engine,--tools,--verbose, but nothing for state). - 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:
- CLI flag + env var, defaulting to
~/.agentmemory/data(or platform-appropriate:$XDG_DATA_HOME/agentmemoryon Linux,~/Library/Application Support/agentmemoryon macOS):agentmemory --data-dir ~/.agentmemory/data AGENTMEMORY_DATA_DIR=~/.agentmemory/data npx @agentmemory/agentmemory
- Auto-relocate when started inside a git repo: detect
.gitin cwd or any ancestor, and if found, use~/.agentmemory/datainstead 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.
Activity
mvanhorn commentedon May 12, 2026
Implemented in #314 — adds
--data-dirandAGENTMEMORY_DATA_DIR, default to platform-appropriate user dir (~/Library/Application Support/agentmemoryon macOS,$XDG_DATA_HOME/agentmemoryon Linux).jonathanzhan1975 commentedon May 19, 2026
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/#dashboardappeared 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.yamlcontains relative paths:Starting agentmemory from different directories produced different state stores:
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:
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-localdata/state_store.db.Environment
0.9.20iii.exeengineSuggested fix / acceptance criteria
Even if
AGENTMEMORY_DATA_DIRexists, the default should not remain cwd-relative on Windows. The generatediii-config.yamlshould use an absolute state path by default, for example: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.
Ghostbird commentedon May 29, 2026
Oh, this weirded me out a lot. Suddenly I saw git changes in one specific repository, next to our database migration scripts. I finally figured out that I had to kill iii and restart agentmemory manually from another folder.
For now as a workaround I have set agent-memory to auto-start on login, from the ~/.agentmemory directory, moved the iii-config.yaml there as well, and updated the engine-state.json to reflect that move.
HaleTom commentedon Jun 9, 2026
Related to XDG part of this issue: #871 is about moving
~/.agentmemory/bin/iiito the XDGBDS directory:$HOME/.local/bin.I note that #314 remains unmerged and has a copilot code review comment that hasn't been addressed (@mvanhorn maybe you didn't see it?)
fix(cli): add --data-dir flag + AGENTMEMORY_DATA_DIR so engine state …
fix(cli): add --data-dir flag + AGENTMEMORY_DATA_DIR so engine state …
fix(cli): add --data-dir flag + AGENTMEMORY_DATA_DIR so engine state …