Dev Context Memory

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

Aspect	Traditional RAG	Dev Context Memory
Source	Indexes source code	Stores curated project knowledge
Format	Embeddings in a vector DB	Human-readable Markdown
Location	External service or local DB	Inside the project (.dev-context-memory/)
Persistence	Rebuilt on changes	Git-committed, always available
Human-readable	No	Yes — edit with any text editor
Content	Full code	Concise decisions, contracts, conventions

Memory Sections

The server manages these Markdown files:

Section	File	Purpose
overview	overview.md	High-level project description
architecture	architecture.md	System architecture and design patterns
api-contracts	api-contracts.md	API endpoint contracts
decisions	decisions.md	Architecture Decision Records
bugs	bugs.md	Known bugs and issues
todos	todos.md	Planned work and tasks
conventions	conventions.md	Coding standards and style guides
glossary	glossary.md	Project-specific terminology

MCP Tools

Tool	Description
list_memory_sections	List available memory sections
read_memory	Read a memory section
write_memory	Overwrite a memory section (use with care)
append_decision	Add an Architecture Decision Record
append_api_contract	Add an API endpoint contract
search_memory	Search all sections by keyword
summarize_memory	Get headings and excerpts from sections

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.