CogMemory MCP Server

A unified Model Context Protocol server providing four context subsystems for AI coding agents:

1. Memory — decisions, conventions, errors, active context, changelog, plan, tasks, sessions
2. Knowledge Graph — entities, relations, observations
3. Specs — long-form documents (PRD/SRS), optionally linked to a KG entity
4. Code Graph — static structural graph (symbols/edges) + named execution traces + AI-generated annotations

Storage: SQLite via better-sqlite3. One .db file per scope.

Quick Start

Install

Option A — npx (recommended, always latest):

npx -y cogmemory-mcp@latest

Option B — Global install:

npm install -g cogmemory-mcp
cogmemory-mcp

Option C — pnpm dlx:

pnpm dlx cogmemory-mcp@latest

Option D — From source (developers):

git clone https://github.com/skylarng89/cogmemory-mcp.git
cd cogmemory-mcp
pnpm install
pnpm run build

Native Module Requirements

CogMemory depends on better-sqlite3 and tree-sitter, which compile native modules on install. You need:

• Python 3 (for node-gyp)
• C/C++ compiler (gcc/g++ on Linux, Xcode Command Line Tools on macOS, Visual Studio Build Tools on Windows)
• make (Linux/macOS, installed by default)

Most platforms have prebuilt binaries available, so compilation is usually skipped on:

• Linux x64 / arm64
• macOS x64 / arm64
• Windows x64

If installation fails, see Troubleshooting below.

IDE / Client Configuration

VS Code

Add to .vscode/mcp.json (workspace-scoped):

{
  "servers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Or use --workspace for multi-root support:

{
  "servers": {
    "cogmemory-frontend": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest", "--workspace", "/path/to/frontend"]
    },
    "cogmemory-backend": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest", "--workspace", "/path/to/backend"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json (Linux/macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Claude Code

Add to ~/.claude/mcp.json (user-level) or .claude/mcp.json (project-level):

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Cline

In the Cline extension settings, add an MCP server:

• Name: cogmemory
• Command: npx -y cogmemory-mcp@latest

Or in cline_mcp_settings.json:

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Windsurf

MCP settings → Add server:

{
  "mcpServers": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

OpenCode

Add to opencode.json:

{
  "mcp": {
    "cogmemory": {
      "command": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

Zed

Add to Zed settings (settings.json):

{
  "context_servers": {
    "cogmemory": {
      "binary": "npx",
      "args": ["-y", "cogmemory-mcp@latest"]
    }
  }
}

MCP Registry

CogMemory is published to the MCP Registry. Registry-aware clients can discover and install it automatically.

Scope Configuration

CogMemory resolves scope in priority order:

1. .cogmemory/config.json in workspace root:

   config.json

   Copy

   { "scope": "global" }
   

2. Environment variable: COGMEMORY_SCOPE=global

3. Default: workspace

Paths

Workspace Resolution & Multi-Root Support

CogMemory resolves the workspace root (where .cogmemory/memory.db lives) in this priority order:

1. --workspace <path> CLI argument (highest priority)
2. COGMEMORY_WORKSPACE environment variable
3. Walk up from CWD looking for the nearest parent containing a .cogmemory/ directory
4. Fallback to CWD

Upgrades & Migrations

CogMemory uses a versioned migration system. When a new version adds columns or tables, migrations run automatically on the next server startup — no manual action needed.

First-Time Migration (Pre-v1.1.0 Databases)

If you are upgrading from a version prior to v1.1.0 that used the old schema:

1. A backup file is created automatically: <db_path>.backup-pre-migrate-<timestamp>
2. Migrations apply within a transaction — if any step fails, the database is rolled back
3. If something goes wrong, you can restore from the backup: cp memory.db.backup-* memory.db
4. Set COGMEMORY_SKIP_BACKUP=1 to skip the backup (e.g., in CI or disk-constrained environments)

Opt-Out: Update Check Telemetry

By default, CogMemory checks the npm registry once every 24 hours to see if a newer version is available (via the check_for_updates tool). This makes a read-only HTTPS GET to registry.npmjs.org — the same call your package manager makes.

To disable this check:

• Environment variable: COGMEMORY_DISABLE_UPDATE_CHECK=1
• Config file: Add { "disable_update_check": true } to .cogmemory/config.json

Tool Reference (40 tools)

Memory Tools (14)

Knowledge Graph Tools (4)

Specs Tools (3)

Code Graph Tools (4)

Introspection Tools (2)

Code Analysis Tools (8)