
devmemory
π§ Persistent local-first memory for AI coding agents β MCP server + CLI for Claude Code & Cursor. SQLite FTS5, secret redaction, project isolation.
Install with your AI
Paste into Claude Code, Cursor, or any agent β it reads the repo and wires the tool into your project.
Install and set up devmemory (npm project) into my current project. Found on https://claudeers.com/devmemory Repo: https://github.com/vasikmansuri/devmemory Homepage/docs: https://www.npmjs.com/package/@vasikmansuri/devmemory Detected install method: npm β npm install @vasikmansuri/devmemory Category: mcp-servers. Platforms: cli, api. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
npm install @vasikmansuri/devmemory
git clone https://github.com/vasikmansuri/devmemory
// compatibility
| Platforms | cli, api |
|---|---|
| Operating systems | β |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | TypeScript |
π§ DevMemory
Persistent, local-first memory for AI coding agents. An MCP server and CLI for Claude Code, Cursor and other MCP clients.
Stop re-explaining your codebase. DevMemory remembers your project's decisions, architecture, debugging lessons and conventions across AI sessions. It runs 100% on your machine.
Quick start Β· Claude Code Β· Cursor Β· MCP tools Β· CLI Β· Security Β· Docs
β¨ Why DevMemory?
AI coding assistants like Claude Code and Cursor forget everything when a session ends. Every new conversation, you explain the same architecture, the same "we tried X and it broke", the same team conventions.
DevMemory gives your AI agent long-term project memory through the Model Context Protocol (MCP):
| Without DevMemory | With DevMemory | |
|---|---|---|
| ποΈ Project decisions | Re-explained every session | Saved once, retrieved automatically |
| π Debugging lessons | Rediscovered the hard way | Recalled when the same symptom appears |
| π Conventions & constraints | Forgotten mid-task | Included in every relevant context bundle |
| π Privacy | Context pasted into chats | Stored locally in SQLite, never uploaded |
π Features
- π Local-first and private. A single SQLite file at
~/.devmemory/. No cloud, no account, no telemetry, no network port. - π MCP server. 9 tools over stdio, verified with Claude Code. Works with any MCP client.
- ποΈ Project-scoped memory. Each repository's knowledge is isolated, and no project can read another's.
- π·οΈ Structured memory types: decisions, architecture, debugging lessons, conventions, constraints, task context and facts. Each memory has tags, importance, confidence and an optional expiry.
- π Fast, explainable search. SQLite FTS5 full-text search with BM25 ranking, weighted by importance, confidence and recency. Every result explains its score.
- π§Ύ Provenance. Every memory records where it came from: source, client, file, PR or commit reference, and timestamps.
- π Secret redaction. API keys, tokens, passwords and private keys are redacted before anything is stored.
- π‘οΈ Prompt-injection aware. Retrieved memories are wrapped as untrusted data, and instruction-like content is flagged.
- β»οΈ Safe lifecycle. Duplicate detection, conflict surfacing, supersede chains, reversible archiving, and hard deletes that also purge the search index.
- π¦ Import and export. Portable JSON with validation, size limits and protection against path traversal and symlinks.
- π§° Developer CLI. 15 commands, JSON output and meaningful exit codes for automation.
ποΈ How it works
flowchart LR
subgraph Clients
CC[π€ Claude Code]
CU[π±οΈ Cursor]
CLI[β¨οΈ devmemory CLI]
end
subgraph DevMemory["DevMemory (local process)"]
MCP[MCP server<br/>9 tools Β· stdio]
ENG[Memory engine]
SEC[π Secret redaction<br/>+ validation]
RET[π FTS5 / BM25<br/>ranking]
end
DB[(SQLite<br/>~/.devmemory/devmemory.db)]
CC -- JSON-RPC over stdio --> MCP
CU -- JSON-RPC over stdio --> MCP
CLI --> ENG
MCP --> ENG
ENG --> SEC --> DB
ENG --> RET --> DB
Memory across sessions
sequenceDiagram
actor Dev as Developer
participant S1 as Session 1 (Claude Code)
participant DM as DevMemory
participant S2 as Session 2 (new day)
Dev->>S1: "We chose Drizzle over Prisma because of edge runtimes"
S1->>DM: memory_save(type: decision, ...)
DM-->>S1: β
saved (secrets redacted, provenance recorded)
Note over S1: Session ends, the agent forgets everything
Dev->>S2: "Add a new database table"
S2->>DM: memory_context("database table")
DM-->>S2: π Drizzle decision + conventions (with provenance)
S2-->>Dev: Uses Drizzle correctly, without being re-told
β‘ Quick start
Requires Node.js β₯ 22.12.
# 1. Install
npm install -g @vasikmansuri/devmemory
# 2. Verify the CLI is available
devmemory --version
# 3. Register your project
cd ~/code/my-app
devmemory init
# 4. Save knowledge
devmemory remember -t decision --title "Use Drizzle ORM" \
-c "Drizzle over Prisma: Prisma's engine binary breaks on edge runtimes." \
--tags db,orm -i 4 --source-ref docs/adr/0003.md
# 5. Find it again
devmemory search "which orm"
devmemory context "touching the data layer"
Install from source
git clone https://github.com/vasikmansuri/devmemory.git
cd devmemory
npm ci && npm run build && npm link
devmemory --version
π€ Connect Claude Code
β Verified end to end with Claude Code 2.1.294.
claude mcp add --transport stdio devmemory -- devmemory mcp
Share it with your team via .mcp.json:
claude mcp add --scope project --transport stdio devmemory -- devmemory mcp
Check the connection with claude mcp list or /mcp. Then try "Save to DevMemory: we deploy with Argo CD", start a new session, and ask "how do we deploy?"
π‘ Claude Code starts the server in your working directory, and DevMemory finds the nearest registered project automatically, even from subfolders.
π±οΈ Connect Cursor
β οΈ Configuration follows Cursor's documented format, but has not been tested end to end yet. Add this to .cursor/mcp.json:
{
"mcpServers": {
"devmemory": {
"type": "stdio",
"command": "devmemory",
"args": ["mcp", "--project", "${workspaceFolder}"]
}
}
}
π§© MCP tools
| Tool | Description |
|---|---|
memory_save | Save a memory. Reports duplicates and possible conflicts; can supersede older memories. |
memory_search | Ranked keyword search with type, tag and status filters. |
memory_get | Fetch one memory with links and lifecycle history. |
memory_update | Edit in place; previous values are kept in history. |
memory_forget | Archive (reversible) or permanently delete (confirm: true). |
memory_list | Paginated, filtered listing. |
memory_context | A token-budgeted context bundle for the current task. |
memory_link | Relate memories: depends_on, conflicts_with, β¦ |
memory_stats | Project statistics. |
β¨οΈ CLI reference
| Command | Purpose |
|---|---|
devmemory init | Register the current directory as a project |
devmemory remember | Save a memory (-c - reads stdin) |
devmemory search <query> | Ranked keyword search |
devmemory get <id> | Full memory with provenance and history |
devmemory list | Browse with filters and pagination |
devmemory context [query] | The context bundle an agent receives |
devmemory update <id> | Edit a memory |
devmemory forget <id> | Archive, or --hard --yes to delete |
devmemory link <a> <b> | Link two memories |
devmemory stats Β· projects Β· doctor | Statistics, project list, health checks |
devmemory export Β· import | Portable JSON backup and restore |
devmemory mcp | Run the MCP server (stdio) |
Add --json to any command for machine-readable output.
Exit codes: 0 ok Β· 1 internal error Β· 2 validation Β· 3 not found Β· 4 project not initialized Β· 5 conflict Β· 6 database error Β· 7 I/O or unsafe path.
π Search quality (measured, not claimed)
These numbers come from 36 labelled queries over a 46-memory test project (npm run eval):
| Metric | All queries | Direct wording | Paraphrased |
|---|---|---|---|
| Recall@5 | 0.944 | 1.000 | 0.750 |
| MRR | 0.922 | 1.000 | 0.650 |
| Precision@5 (max achievable 0.228) | 0.217 | 0.229 | 0.175 |
DevMemory uses keyword search, not semantic search, so paraphrased questions with no shared words can miss. Semantic search is on the roadmap.
π Security & privacy
- β Runs locally: no telemetry, no network listener, no external API calls.
- β Secrets are redacted before storage, covering AWS keys, GitHub tokens, OpenAI and Anthropic keys, JWTs, private keys and passwords.
- β
The database file is readable only by your user (mode
0600). - β Projects are isolated, and all SQL is parameterized.
- β Retrieved memories are treated as untrusted data, never as instructions.
- β οΈ The database is not encrypted at rest. Use full-disk encryption for extra protection.
Read more in the security model and SECURITY.md.
βοΈ Configuration
| Variable | Default | Purpose |
|---|---|---|
DEVMEMORY_HOME | ~/.devmemory | Data directory |
DEVMEMORY_PROJECT | current dir | Project to use |
DEVMEMORY_SECRET_POLICY | redact | redact or reject writes containing secrets |
DEVMEMORY_EXTRA_TYPES | β | Extra memory types, comma-separated |
DEVMEMORY_LOG_LEVEL | warn | Log level (stderr only) |
π Documentation
Architecture Β· Memory model Β· Security model Β· MCP integration Β· Troubleshooting Β· Retrieval evaluation Β· Roadmap Β· Contributing Β· Changelog
π£οΈ Roadmap
- Local MCP server, CLI, FTS5 search, secret redaction, project isolation
- Verified Claude Code integration
- Optional local embeddings for semantic search
- End-to-end verified Cursor integration
- Better tokenization for Chinese and Japanese text
- Opt-in encryption at rest
π€ Contributing
Contributions are welcome! Run npm run check (typecheck, lint, 129 tests, build) and see CONTRIBUTING.md.
β οΈ Known limitations
- Keyword search only (no semantic search yet).
- Chinese and Japanese text is tokenized coarsely.
- Moving a project folder requires running
devmemory initagain. - The Cursor integration is unverified.
π License
MIT Β© Vasik Mansuri
If DevMemory saves you from re-explaining your codebase, please β star the repo!
Keywords: AI memory Β· MCP server Β· Model Context Protocol Β· Claude Code memory Β· Cursor MCP Β· AI coding assistant Β· persistent context Β· long-term memory for LLM agents Β· local-first Β· SQLite FTS5 Β· developer tools
Support
If this project is useful to you, you can support my open-source work:
// faq
What is devmemory?
π§ Persistent local-first memory for AI coding agents β MCP server + CLI for Claude Code & Cursor. SQLite FTS5, secret redaction, project isolation.. It is open-source on GitHub.
Is devmemory free to use?
devmemory is open-source under the MIT license, so it is free to use.
What category does devmemory belong to?
devmemory is listed under mcp-servers in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/devmemory)
// retro hit counter
[](https://claudeers.com/devmemory)
// reviews
// guestbook
// related in MCP Servers
f.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source β self-host for your organization with completeβ¦
A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
πͺ¨ why use many token when few token do trick β Claude Code skill that cuts 65% of tokens by talking like caveman
An open-source AI agent that brings the power of Gemini directly into your terminal.