🧠 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):

Related MCP server: Cortex

🚀 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"

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

⌨️ CLI reference

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):

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

📚 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 init again.

• 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: