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:

   { "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)

List & Delete Tools (5)

---

Architecture

cogmemory-mcp/
├── src/
│   ├── index.ts                 # entry point, server bootstrap
│   ├── version.ts               # auto-generated version constant
│   ├── config.ts                # scope resolution, path resolution
│   ├── types.ts                 # shared TS types mirroring schema
│   ├── db/
│   │   ├── connection.ts        # DB open/close, pragma setup
│   │   ├── migration-runner.ts  # versioned migration engine (PRAGMA user_version)
│   │   ├── migrate.ts           # legacy idempotent migration (deprecated)
│   │   └── migrations/
│   │       ├── 001_baseline.sql         # full v1 schema
│   │       ├── 002_symbol_export_hash.sql
│   │       ├── 003_index_errors.sql
│   │       ├── 004_symbol_embeddings.sql
│   │       ├── 005_edge_metadata.sql
│   │       ├── 006_symbol_tokens.sql
│   │       └── 007_symbol_minhash.sql
│   ├── tools/
│   │   ├── memory.ts            # decisions/conventions/errors/context/changelog/recall
│   │   ├── plan-tasks.ts        # plan + tasks tools
│   │   ├── sessions.ts          # start/end session, summary
│   │   ├── knowledge-graph.ts   # entities/relations/observations
│   │   ├── specs.ts             # spec CRUD
│   │   ├── code-graph.ts        # index_codebase, query_code_graph
│   │   ├── codemap.ts           # generate_codemap, annotate_symbol
│   │   ├── code-analysis.ts     # dead code, duplicates, related, graph query, impact, snippet, coverage, search
│   │   ├── introspection.ts     # cogmemory_status, check_for_updates
│   │   ├── list-delete.ts       # list_items, delete_item, purge_subsystem
│   │   └── utils.ts             # wrapHandler, jsonOk, jsonFail, jsonErr
│   └── indexing/
│       ├── ts-analyzer.ts       # ts-morph symbol/edge extraction (JS/TS)
│       ├── py-analyzer.ts       # tree-sitter symbol/edge extraction (Python)
│       ├── edge-types.ts        # edge type constants (calls, imports, extends, implements, similarto, semrelated)
│       └── walker.ts            # file discovery, gitignore respect
├── package.json
├── tsconfig.json
└── README.md

---

Schema (25 tables)

Base tables (21):

• Memory (8): sessions, decisions, conventions, errors, context, changelog, plan, tasks
• Knowledge Graph (3): entities, relations, observations
• Specs (1): specs
• Code Graph (5): symbols (with is_exported, body_hash, token_count columns), edges (with metadata JSON column), execution_traces, codemap_annotations, file_index
• Code Analysis (3): index_errors, symbol_tokens (TF-IDF), symbol_minhash (MinHash signatures)
• Future (1): symbol_embeddings (stub — vector embeddings for Phase 2)

FTS5 tables (4):

• Recall FTS: recall_docs (content table) + recall_fts (FTS5 virtual table) — powers recall
• Knowledge Graph FTS: kg_docs (content table) + kg_fts (FTS5 virtual table) — powers search_knowledge

Schema migrations are automatic via PRAGMA user_version (currently at version 7).

---

Supported Languages

The Code Graph (index_codebase) extracts symbols and edges from source files using language-specific analyzers:

Structural edges: calls, imports, extends, implements

Analysis edges: similarto (clone detection), semrelated (semantic relation discovery)

---

Pragmas

Set on every connection open:

PRAGMA journal_mode = WAL;
PRAGMA foreign_keys = ON;

---

Development

pnpm run dev        # Run with tsx (no build step)
pnpm run build      # Compile TypeScript (regenerates version.ts via prebuild)
pnpm run start      # Run compiled output
pnpm run inspect    # Launch MCP Inspector
pnpm run smoke-test # Run smoke test script (43 checks)

---

Troubleshooting

Native module build failure

If npm install or pnpm install fails with node-gyp errors:

1. Install Python 3: python3 --version — if missing, install via your package manager
2. Install C++ build tools:
   • macOS: xcode-select --install
   • Ubuntu/Debian: sudo apt-get install build-essential
   • Windows: Install Visual Studio Build Tools with the "C++ build tools" workload
3. Retry: npm rebuild better-sqlite3 (or npm rebuild tree-sitter)

Migration failure

If the server exits with a migration error:

1. Check stderr for the error message and the migration file number
2. Restore from backup: cp .cogmemory/memory.db.backup-* .cogmemory/memory.db
3. Try again — the migration will re-run from the current user_version

Large workspace performance

For workspaces with 50k+ files:

1. Use .gitignore to exclude vendored/generated code (CogMemory respects it)
2. The walker skips node_modules, .git, dist, build, .next, .cogmemory, __pycache__, .venv, venv, *.min.js, *.min.css, *.map by default
3. Index coverage: the check_index_coverage tool paginates unindexed file reports at 1000 entries

analyze_impact — git not available

If the workspace is not a git repository, analyze_impact with auto-detection will fail. Pass changed_files manually instead.

---

License

MIT