# 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.