Dev Context Memory MCP

A local-first MCP server that gives AI coding assistants persistent, structured, human-readable memory for a software project.

Why?

AI coding assistants lose context between sessions. They re-read files, forget decisions, and miss conventions. RAG solutions index source code — but source code isn't the right unit of memory. What agents actually need is durable project knowledge: architecture decisions, API contracts, conventions, bugs, and todos.

Dev Context Memory stores this knowledge as Markdown files inside your project, in a .dev-context-memory/ folder. No database, no vector store, no cloud service. Just files you can read, edit, and commit.

How it differs from RAG

Related MCP server: local-agent-context

Memory Sections

The server manages these Markdown files:

MCP Tools

Installation

# Clone or copy into your tools directory
cd dev-context-memory-mcp

# Install dependencies
npm install

# Build
npm run build

Running

The server communicates over stdio, which is the standard MCP transport:

node dist/index.js

The server will create a .dev-context-memory/ folder in the current working directory if it doesn't exist.

MCP Configuration

VS Code GitHub Copilot

Add to your .vscode/mcp.json file:

{
  "servers": {
    "dev-context-memory": {
      "command": "node",
      "args": ["/absolute/path/to/dev-context-memory-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

Claude Desktop / Claude Code

Add to your MCP settings (e.g., claude_desktop_config.json or .claude/settings.json):

{
  "mcpServers": {
    "dev-context-memory": {
      "command": "node",
      "args": ["/absolute/path/to/dev-context-memory-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "dev-context-memory": {
      "command": "node",
      "args": ["/absolute/path/to/dev-context-memory-mcp/dist/index.js"]
    }
  }
}

Gemini CLI / Antigravity

Add to your .gemini/settings.json:

{
  "mcpServers": {
    "dev-context-memory": {
      "command": "node",
      "args": ["/absolute/path/to/dev-context-memory-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

Important: Set cwd to the root of the project where you want memory stored. The .dev-context-memory/ folder will be created there.

Example Tool Calls

List available sections

{
  "tool": "list_memory_sections",
  "arguments": {}
}

Read a section

{
  "tool": "read_memory",
  "arguments": {
    "section": "architecture"
  }
}

Record a decision

{
  "tool": "append_decision",
  "arguments": {
    "title": "Use PostgreSQL for user data",
    "context": "We need a relational database for user profiles, permissions, and audit logs. SQLite is too limited for concurrent access in production.",
    "decision": "Use PostgreSQL 16 with Drizzle ORM. Deploy on Supabase for the MVP.",
    "consequences": "Requires a running PostgreSQL instance. Adds Drizzle as a dependency. Migration tooling needed.",
    "relatedFiles": ["src/db/schema.ts", "src/db/connection.ts", "docker-compose.yml"]
  }
}

Record an API contract

{
  "tool": "append_api_contract",
  "arguments": {
    "name": "Create User",
    "method": "POST",
    "path": "/api/v1/users",
    "purpose": "Creates a new user account and sends a welcome email.",
    "auth": "Bearer token, admin role required",
    "request": "{ email: string, name: string, role: 'admin' | 'user' }",
    "response": "{ id: string, email: string, createdAt: string }",
    "sideEffects": "Sends welcome email via SendGrid. Creates Stripe customer.",
    "frontendUsage": "Called from the admin dashboard user creation form.",
    "relatedFiles": ["src/routes/users.ts", "src/services/email.ts"]
  }
}

Search memory

{
  "tool": "search_memory",
  "arguments": {
    "query": "PostgreSQL"
  }
}

Summarize all memory

{
  "tool": "summarize_memory",
  "arguments": {}
}

Recommended Usage with AGENTS.md

To help AI agents understand how and when to use the Memory MCP server, it is highly recommended to include instructions in your project workspace.

We have provided a comprehensive example of these instructions in the AGENTS.md file included in this repository.

You can copy the contents of AGENTS.md and add them to your own project's AGENTS.md, .cursorrules, .github/copilot-instructions.md, or any equivalent agent instructions file supported by your editor. This ensures that the agent follows best practices regarding memory quality, security, and when to trust memory vs. source code.

Security Model

Dev Context Memory is designed to be safe by default:

• Filesystem containment: All reads and writes are scoped to .dev-context-memory/. Path traversal is blocked.

• Section whitelist: Only known section names are accepted. Unknown sections are rejected with clear errors.

• No shell execution: The server never runs shell commands.

• No network access: The server never makes network requests.

• No silent deletion: Write operations are explicit and clearly documented.

• No arbitrary file access: The server cannot read or write project source files.

• Input validation: All inputs are validated before use.

Development

# Watch mode for development
npm run dev

# Build for production
npm run build

Testing Manually

1. Build the project: npm run build

2. Run the server in a project directory:

   cd /path/to/your/project
   node /absolute/path/to/memory-mcp/dist/index.js

3. The server starts on stdio. You can test it using the MCP Inspector:

   npx @modelcontextprotocol/inspector node /absolute/path/to/memory-mcp/dist/index.js

   Bonus Tip: Fixing the Rotating Token Problem
   The MCP Inspector protects its local browser UI with an authorization token. When you start the Inspector with npx @modelcontextprotocol/inspector, it may generate a new random token each time. That means every restart can require opening a new URL, copying a new token, or reconnecting the browser session, which gets annoying while repeatedly testing tools.

   This project includes an inspector script that sets a stable local development token (stable-token-123) with MCP_PROXY_AUTH_TOKEN. Run it through npm's --prefix flag so you can launch the script from your target project while still using this repo's package script:

   npm --prefix /absolute/path/to/memory-mcp run inspector

4. Check that .dev-context-memory/ was created with default template files.

5. Use the Inspector UI to call tools like list_memory_sections, read_memory, and append_decision.

Future Improvements

• Embedding-based search: Replace keyword matching with vector similarity for semantic search.

• Git integration: Auto-commit memory changes, track history, detect drift.

• Section versioning: Keep a changelog of memory edits.

• Custom sections: Allow projects to define their own sections.

• Memory validation: Lint memory files for structure and completeness.

• Cross-project memory: Share conventions across multiple repositories.

• Conflict resolution: Detect and surface conflicting decisions or outdated contracts.

• MCP resources: Expose memory sections as MCP resources for read-only access.