Documentation
DevMemory is a persistent memory layer for AI coding tools. It saves your project context as you work and restores it in whatever tool you switch to next.
Overview
When your AI credits run out mid-task, the next tool starts from zero — unless your context was saved before the credits died. DevMemory makes saving deterministic: it does not rely on the model remembering to call a tool.
It captures work three ways depending on the tool:
- Transcript hooks — Claude Code and Windsurf fire an OS hook that hands over a plaintext transcript; a small script POSTs each turn.
- Watch daemon — Cursor, Cline, Kilo and Codex persist conversations locally;
devmemory starttails those stores. - MCP + rules — where no verified hook exists (Antigravity), an always-on rules file drives save/restore through the MCP tools.
Installation
Pick whichever fits your setup — none of these require you to create a virtual environment by hand.
# Node — nothing to install (recommended, no Python needed) npx -y @commanderzero/devmemory --help
# Python — pipx manages an isolated environment for you pipx install devmemory-ai # or, with uv: uv tool install devmemory-ai
Plain pip install devmemory-ai also works, but on modern Debian/Ubuntu (PEP 668) it errors unless you're in a virtual environment — use pipx, uv, or npx to skip that.
Quick start
Get running in under a minute:
# 1 — connect DevMemory to your tool (use --tool all for every detected tool) devmemory install --tool cursor --api-key YOUR_KEY --host https://devmemory.io # 2 — attach the project you're working on devmemory start # 3 — hit a wall? open the same project in another tool and continue devmemory continue
Get your API key from the dashboard. Point clients at your server with --host.
The attach model
Auto-save is opt-in and scoped to one project at a time. Nothing is saved until you attach — no background daemon quietly recording every repo you touch.
devmemory start— attach the current project (resolved from its git remote), restore its saved context, and begin auto-saving. Runs until you stop; long idle gaps are fine.devmemory continue— re-attach the active project to a new tool, restore its context there, and resume saving from that tool.devmemory stop— detach and stop auto-saving.devmemory status— show the active project, the attached tool, and the daemon state.
Both the watch daemon and the deterministic hooks respect the active project. If nothing is attached, they save nothing and log a hint to run devmemory start.
CLI commands
| Command | What it does |
|---|---|
devmemory install | Wire DevMemory into a tool via MCP + hooks. --tool all configures every detected tool. |
devmemory start | Attach a project, restore context, begin auto-saving. |
devmemory continue | Re-attach the active project to a new tool and resume saving. |
devmemory stop | Detach and stop the watch daemon. |
devmemory status | Show the active session and daemon state. |
devmemory inject | Manually load context into CLAUDE.md / rules files for a project. |
devmemory watch --list | Show the auto-save mechanism and detected stores per tool. |
devmemory --rest | Run the REST API + dashboard locally (self-hosting). |
Supported tools
DevMemory never fakes support. Each tool is captured by a real, verified mechanism:
| Tool | Mechanism | Status |
|---|---|---|
| Claude Code | Stop hook (transcript) | ✔ deterministic |
| Windsurf | post_cascade_response_with_transcript hook + global_rules.md | ✔ deterministic |
| Cursor | watch daemon (SQLite store) | ✔ verified |
| Cline / Kilo | watch daemon (JSON task history) | ✔ supported |
| Codex | watch daemon (state_*.sqlite + rollout JSONL) | ✔ supported |
| Antigravity | MCP tools + ~/.gemini/GEMINI.md rules | ✔ agent-driven |
| Augment | SessionStart hook (restore) + MCP save | ✔ supported |
| any JSONL tool | generic adapter (~/.devmemory/watch_adapters.json) | ✔ config-driven |
Windsurf and Antigravity encrypt conversations on disk. DevMemory doesn't try to crack that — Windsurf hands its hook a plaintext transcript, and Antigravity saves through the MCP tools + a rules file.
MCP tools
Once connected, your AI tool can call these directly. The one you'll use most:
continue_here— attach this project and load its context in one call. Trigger it by saying "continue" or "pick up where we left off".save_context— save a typed block (goal, decision, code, error, next_step, note).get_context— retrieve saved blocks for the project or session.generate_resume_prompt— build a "continue here" prompt tuned for a target tool.start_session/end_session/list_sessions_tool— manage development sessions.save_tasks/update_task— track a task list across tools.list_projects_tool— list all projects on your account.
Self-hosting
Run DevMemory entirely on your own infrastructure. SQLite for local use, PostgreSQL for production.
# start the REST API + dashboard on http://localhost:8765 devmemory --rest --host 0.0.0.0 --port 8765
Then point clients at it with --host http://your-server:8765 during devmemory install. The dashboard lives at /app; the API reference is at /api-docs.
Troubleshooting
Nothing is being saved
Auto-save is opt-in. Run devmemory start in your project first, then check devmemory status. If the daemon isn't running, start will relaunch it.
Which tools are actually captured on this machine?
Run devmemory watch --list — it reports the exact mechanism per tool and which local stores were detected.
Context isn't loading in the new tool
Make sure you run devmemory continue from the same project directory, and that the tool was connected with devmemory install.
Need the API reference? See /api-docs. Prefer the dashboard? Open the app.