Content
# 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
| 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
```bash
# 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:
```bash
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:
```json
{
"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`):
```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:
```json
{
"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`:
```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
```json
{
"tool": "list_memory_sections",
"arguments": {}
}
```
### Read a section
```json
{
"tool": "read_memory",
"arguments": {
"section": "architecture"
}
}
```
### Record a decision
```json
{
"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
```json
{
"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
```json
{
"tool": "search_memory",
"arguments": {
"query": "PostgreSQL"
}
}
```
### Summarize all memory
```json
{
"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
```bash
# 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:
```bash
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](https://github.com/modelcontextprotocol/inspector):
```bash
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:
> ```bash
> 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.
