Skip to content

Getting Started

The Problem

AI agents work in a black box. You don't see what they remember. You can't edit their memories when they're wrong. You can't fix a mistaken belief without restarting from scratch.

devmcp-context solves this. Your agent's memory is now visible, editable, and persistent - stored as plain Markdown files in your project folder.

How It Works

  1. You install devmcp-context in your project
  2. You register devmcp-context in your agent's MCP config (one-time setup)
  3. Your agent automatically wakes up the memory server when you start a session
  4. The agent can now see, save, update, and search its memories across conversations
  5. You can manually inspect and edit memories in ai-context/ folder anytime
graph LR
    A["1. Install<br/>devmcp-context"]
    B["2. Register<br/>in MCP config"]
    C["3. Agent Starts<br/>Memory Server"]
    D["4. Agent Uses<br/>6 Tools"]
    E["5. You Edit<br/>Files Manually"]
    F["ai-context/<br/>Storage"]

    A --> B --> C --> D
    D --> F
    E --> F

    style A fill:#f0f0f0
    style B fill:#f0f0f0
    style C fill:#f0f0f0
    style D fill:#60a5fa,color:#0f172a
    style E fill:#f0f0f0
    style F fill:#f0f0f0

Step 1: Install devmcp-context

pip install devmcp-context
# or
uv add devmcp-context

Step 2: Initialize your project

cd your-project
devmcp-context init

This single command:

  1. Creates ai-context/ with category files
  2. Detects your MCP client (opencode, Cursor, Claude Desktop)
  3. Writes the config with correct paths
  4. Handles multi-project setups automatically

That's it. Restart your MCP client and the tools are available.

Step 3: Register with Your Agent

The init command handles registration for you:

cd your-project
devmcp-context init                    # auto-detect client
devmcp-context init --client opencode  # force specific client
devmcp-context init --client cursor    # force specific client
devmcp-context init --client claude    # force specific client

Manual Setup

If you prefer to edit config files directly:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS): 

{
  "mcpServers": {
    "context": {
      "command": "uv",
      "args": ["--directory", "/path/to/context-mcp", "run", "context-mcp"],
      "env": { "CONTEXT_MCP_PROJECT_ROOT": "/path/to/your/project" }
    }
  }
}

opencode (opencode.json in project root): 

{
  "mcp": {
    "context": {
      "type": "local",
      "command": ["uv", "--directory", "/path/to/context-mcp", "run", "context-mcp"],
      "cwd": ".",
      "enabled": true
    }
  }
}

Cursor (.cursor/mcp.json in project root): 

{
  "mcpServers": {
    "context": {
      "command": "uv",
      "args": ["--directory", "/path/to/context-mcp", "run", "context-mcp"]
    }
  }
}

Docker/Container: 

docker run -d \
  -v /path/to/project:/project \
  -e CONTEXT_MCP_PROJECT_ROOT=/project \
  my-mcp-agent

Step 4: Restart Your Agent

Close and reopen your agent application. The devmcp-context server is now available.

Step 5: Test the Setup

Start a new session and ask your agent to check memory:

Prompt: "Use context_status to show me the memory tools"

Your agent should respond with: - Available categories (project, decisions, errors, tasks, ephemeral) - Entry counts per category - Tip about using context_load to retrieve entries

Where Are My Memories?

After saving memories, they appear as Markdown files:

your-project/
├── ai-context/
│   ├── project.md        (permanent knowledge)
│   ├── decisions.md      (architecture/design choices)
│   ├── errors.md         (bugs fixed, expires in 30 days)
│   ├── tasks.md          (current tasks, expires in 14 days)
│   ├── ephemeral.md      (temporary notes, expires in 1 day)
│   └── _meta.md          (category descriptions)
├── src/
├── tests/
└── ... your project files

You can open and edit these files directly in any text editor. The format is plain Markdown.

Example: Using Memory with Your Agent

Save memory:

"Save to project memory: Database is PostgreSQL 15 with connection pooling."

Agent calls context_save behind the scenes.

Retrieve memory:

"What database are we using?"

Agent calls context_search and finds your saved note.

Manually fix memory: Open ai-context/project.md and edit the entry directly. Agent sees the change on next read.

Understanding Memory Categories

Category Auto-Expires Purpose
project Never Architecture, stack, critical facts
decisions Never Why you chose something, trade-offs
errors 30 days Bugs fixed, what went wrong, solutions
tasks 14 days Current work, in-progress items
ephemeral 1 day Temporary notes, scratchpad, tests

Expired entries are kept until you run context_purge_expired.

Using Multiple Projects

Each project gets independent memory. Run init in each project:

cd ~/projects/project-a && devmcp-context init
cd ~/projects/project-b && devmcp-context init

Each gets a unique entry name. For Claude Desktop, the config looks like:

{
  "mcpServers": {
    "context-project-a": {
      "command": "uv",
      "args": ["--directory", "/path/to/context-mcp", "run", "context-mcp"],
      "env": { "CONTEXT_MCP_PROJECT_ROOT": "/path/to/project-a" }
    },
    "context-project-b": {
      "command": "uv",
      "args": ["--directory", "/path/to/context-mcp", "run", "context-mcp"],
      "env": { "CONTEXT_MCP_PROJECT_ROOT": "/path/to/project-b" }
    }
  }
}

For opencode/Cursor, each project gets its own config file with cwd: "." - no env var needed.

Troubleshooting

"MCP server not found"

  • Verify config file path is correct for your OS
  • Check that cwd is an absolute path (not relative like ./project)
  • Restart your agent completely
  • Check agent logs for detailed error messages

"Command 'uv' not found"

  • Make sure uv is installed: curl -LsSf https://astral.sh/uv/install.sh | sh
  • Restart your terminal after installing uv
  • Use full path to uv if needed: /usr/local/bin/uv or C:\path\to\uv.exe

Memory files not created

  • Check that cwd exists and is readable
  • Verify the path is absolute, not relative
  • ai-context/ folder is created automatically on first memory save

Path confusion

  • The cwd in MCP config is where the server starts
  • Memory lives in {cwd}/ai-context/
  • Use absolute paths only - no ~, no relative paths like ./project
  • To override, set CONTEXT_MCP_PROJECT_ROOT environment variable

Next Steps