Overview
The Aider integration connects Aider’s terminal sessions to claude-mem through the one surface Aider actually offers: the conventions file it loads read-only into every session. The installer adds one entry — the per-project memory file.claude-mem/aider-memory.md — to the read: list
in the project’s .aider.conf.yml, and aider sync refreshes that file
from the claude-mem worker before a session. Aider then answers from past
decisions without you re-explaining them.
Capabilities
Catalog-ready description: Aider connects to claude-mem as a file-based
context integration. It injects per-project memory into every session
through
.aider.conf.yml read:; it does not automatically capture
sessions and has no MCP client.
How It Works
The installer merges one entry into theread: list of your project’s
.aider.conf.yml:
read: key yet, the installer appends a managed
block instead:
read: file read-only into the session (cached, and
re-read when it changes). The memory file itself is refreshed from the
worker — GET /api/context/inject, the same endpoint Cursor’s context
refresh uses — so the decisions other agents saved for this project show
up in Aider. The file lives under .claude-mem/ in the project, next to
nothing you own: it never collides with your files, and it stays local
(see “Keep the memory file local” below).
The merge is text-level: your other keys, comments, key order, and API
keys are preserved byte-for-byte. A config whose read: region is
ambiguous (duplicate read: keys, an unclosed flow list, tab
indentation) is refused — the file is left untouched and the installer
says why, instead of replacing it with an empty object.
Installation
Prerequisites: Aider 0.86.x (pip install aider-chat), a model key or local model (Aider needs one to run), and claude-mem installed with the worker running (npx claude-mem start).
Aider is set up per project, and only when you ask for it. The global
npx claude-mem install does not offer or preselect it. Run this from the
project root:
- Resolves your config: the project’s
.aider.conf.yml(git root first, then the working directory, then~/.aider.conf.yml— Aider’s own search order). - Backs up an existing
.aider.conf.ymlfirst, as.aider.conf.yml.bak-YYYYMMDD(owner-only, mode0600, one per day). - Merges
.claude-mem/aider-memory.mdintoread:, preserving every other key, comment, and entry. Re-running install is a no-op. - Creates
.claude-mem/aider-memory.mdwith a placeholder, then best-effort refreshes it from the worker. If the worker is not running, install still succeeds — runnpx claude-mem aider synconce it is. - Refuses to run when the project folder is your home directory: the
memory file would land in
~/.claude-mem/, claude-mem’s own data directory.
Keep the memory file local
The memory file holds past-session context for this project. In a git repo, install adds this line to the repo’s.git/info/exclude, so the
file never shows in git status and a git add -A does not commit it.
Your .gitignore is not touched:
.claude-mem/ out of whatever
version control you use.
Manual setup
If you prefer not to run the installer, add the entry yourself to the project’s.aider.conf.yml (create the file if it does not exist):
.claude-mem/aider-memory.md and run
npx claude-mem aider sync to fill it. The path is relative to the
directory you run Aider from — run Aider from the project root.
Refreshing memory
Before a session, refresh the memory file from the worker:GET /api/context/inject?projects=<key>&projects=<key>…&cwd=<project> (every
project key the checkout reads, including a worktree’s parent project) and
writes the result into the managed <claude-mem-context> block of
.claude-mem/aider-memory.md. Notes you write in that file outside the
block are preserved. If the worker is unreachable, sync fails honestly
with an error and leaves the file untouched — it never reports a refresh
it did not do. An empty result (no memory yet) leaves the file alone.
Verification
- Run
npx claude-mem aider status— it reports installed and the memory file path. - Have a session observation for this project first: finish a session in another agent (Claude Code, Cursor, …) where the decision was made — for example, “The project uses SQLite for local persistence.” The observer turns it into a concept-tagged observation, which is what the SessionStart rendering includes.
- Run
npx claude-mem aider sync, then open.claude-mem/aider-memory.mdand check the decision title is listed in it. The file carries the SessionStart index — decision titles and timeline, not full narratives (the worker renders full text only for the full-observation set, which defaults to zero). Full text is retrieved with search or the viewer. - Start Aider from the project root (
aider). Aider adds the memory file to the chat read-only —.aider.chat.history.mdrecords the lineAdded .claude-mem/aider-memory.md to the chat (read-only). - Ask Aider about the known decision (“What did we decide about local persistence in this project?”) — it should answer from the injected context. Then search from outside Aider to confirm the same memory is still there:
Explicit save (worker API)
Aider cannot save memory itself, so save from outside the session. The worker API accepts an explicit note:37700 + uid % 100 by default; check
~/.claude-mem/settings.json or CLAUDE_MEM_WORKER_PORT for yours.)
The note is searchable immediately with npx claude-mem search — but
note the limitation below: a manually saved note has no concepts, so the
SessionStart compiler does not render it into the memory file. Manual
notes are for search and the viewer; the injected file carries session
observations. A save-note CLI wrapper does not exist yet — that is an
open maintainer question, not a hidden feature.
Troubleshooting
- Aider does not load the memory file: run Aider from the project
root —
read:paths are relative to where Aider runs. Checknpx claude-mem aider statusand that.claude-mem/aider-memory.mdexists. read:entry missing after install: check the installer targeted the config you expected (npx claude-mem aider statusprints the path). Aider searches git root, then cwd, then$HOME— a~/.aider.conf.ymland a project.aider.conf.ymlare different files.- Install fails with “Duplicate top-level
read:key”: your.aider.conf.ymlhas tworead:keys. Remove one (your original bytes are also in the.aider.conf.yml.bak-YYYYMMDDbackup) and re-run install. - Install fails with a flow-list or indentation error: write
read:as a block list with space indentation (YAML forbids tabs) and re-run install. aider syncfails with “Worker is not running”: start it withnpx claude-mem start, then sync again. The memory file is untouched on failure.- Memory file is empty after sync: there is no session memory for this project yet. Finish a session in another agent (Claude Code, Cursor, …) where a decision is made, then sync again. A manually saved note does not populate the file (see Known limitations) — it is searchable, not injectable.
- API key in
.aider.conf.yml: never put keys in the config file itself if you can avoid it — use environment variables or a.envfile. The installer never prints config contents, but Aider writes a--api-keypassed on the command line into.aider.chat.history.md, so prefer env vars there too.
Uninstall
Run this from the project root:read: —
the managed block, or the list entry carrying the
# claude-mem (managed) comment. A read: entry you wrote yourself is
left alone, as are all your other settings. Your memory file is left
untouched (memory is never deleted as a side effect), and so is its
.git/info/exclude line, so the file stays out of git. Delete
.claude-mem/aider-memory.md yourself if you no longer want it, then run
npx claude-mem aider uninstall again to drop the exclude line. Or
remove the entry by hand from .aider.conf.yml.
Known limitations
- No automatic capture of Aider sessions (no host hook surface). A
transcript-file watcher on
.aider.chat.history.mdwas proposed in the scope comment on #5893 and is pending a maintainer ruling — it is deliberately not shipped here. - No MCP client in Aider as of 0.86.x, so no in-chat recall tools and no
in-chat explicit save. Recall is the injected file plus
npx claude-mem searchoutside Aider. - The injected file is the SessionStart index — decision titles and
timeline, not full narratives (the worker renders full text only for
the full-observation set, which defaults to zero). A note saved only
via
POST /api/memory/savenever appears in the file: manual saves carry no concepts, and the SessionStart compiler renders only concept-tagged session observations (only the Grok Bot index writer opts into manual saves). Manual notes are searchable immediately; the file carries session memory. - No
save-noteCLI wrapper exists; explicit save is the worker API call above. - The live Aider run could not get a model answer on this machine (no
model key available, and none is bundled or sought): with a dummy key,
Aider 0.86.2 loaded the generated
.aider.conf.yml(verbose dump:read: ['.claude-mem/aider-memory.md']) and added the memory file to the chat read-only (.aider.chat.history.md:Added .claude-mem/aider-memory.md to the chat (read-only).), then failed at the model call as expected. The in-session answer step needs a run with a real model key (yours or a maintainer’s). - Aider’s releases have stalled — latest package 0.86.2 (Feb 2026), no commits on main since 22 May 2026. If native MCP support lands, this integration should be revisited as an MCP recall client.
- Windows paths in
.aider.conf.yml(C:\...entries) are preserved by the merge but were not verified by running Aider on Windows.
Official reference
- Aider conventions /
read:files: https://aider.chat/docs/usage/conventions - Aider config file (
.aider.conf.yml): https://aider.chat/docs/config/aider_conf.html - Aider chat history files: https://aider.chat/docs/faq.html
- Aider MCP status (no native client as of 0.86.x; open RFC): https://github.com/Aider-AI/aider/issues/4506
- claude-mem worker API / platform integration: https://docs.claude-mem.ai/platform-integration

