Cogmemory MCP

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. By default, each clone gets its own database under ~/.cogmemory/projects/.

---

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 (rarely needed — see Workspace Resolution):

{

"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"] } } }

Zero-config default: if you omit --workspace, CogMemory discovers the

project automatically from the working directory (git root first, then the

nearest .cogmemory/ parent). One server entry is enough for all projects —

each repo gets its own memory bucket. Only pin --workspace for monorepo

sub-root targeting.

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 the workspace root (project-level override):

   { "scope": "project" }

1. Environment variable: COGMEMORY_SCOPE=project, global, or workspace
2. User-level fallback: ~/.cogmemory/config.json (scope settings only)
3. Default: `project` — one database per clone under ~/.cogmemory/projects/

Default is clone-specific. Each clone receives a UUID in .cogmemory/config.json and stores its database at ~/.cogmemory/projects/memory- .db. The UUID, not the folder name or repository origin, identifies the clone. Use { "scope": "global" } or COGMEMORY_SCOPE=global to retain the legacy shared database, or { "scope": "workspace" } for a database inside the repository.

Paths

Upgrading? If a workspace has an existing memory.db but no config file, CogMemory logs a stderr advisory when the project default bypasses it — add { "scope": "workspace" } to that project's .cogmemory/config.json to keep using it. Existing data in global.db remains available when COGMEMORY_SCOPE=global is explicitly selected; it is not silently repartitioned.

---

Project Identity

Every project gets a stable, opaque slug (UUID) stored in .cogmemory/config.json under project_id. This slug — not the folder path or name — is the project's identity. All memories (decisions, conventions, errors, sessions, code graph, etc.) are stamped with a project_id foreign key, so:

• Renames and moves are safe. Moving a project folder does not sever access to its memories — the slug travels with the config file, and the path is metadata only.
• Fixed-path configs work. IDEs/clients that cannot expand ${workspaceFolder} can point at a single shared database path; each project's memories remain isolated by slug.
• Clone-specific project scope is the default. Each clone opens a separate database, so concurrent clients cannot switch one shared process between unrelated project rows.
• Global scope remains available. ~/.cogmemory/global.db can hold many projects, with every read/write implicitly scoped to the active project's slug.

.cogmemory/config.json & Git

Keep .cogmemory/config.json gitignored so each clone gets its own identity on first run. Copying or committing the file intentionally shares its UUID; starting or branching a chat does not create a new project identity.

Project Management Tools

cogmemory_status reports workspace_root, root_path_hint, resolution_source (override | git-root | dotcogmemory | cwd-fallback | runtime-switch), and active_project: { id, slug, label }, plus per-table counts in verbose mode.

Runtime Project Switching

If your client pins a fixed --workspace/cwd that doesn't match the repo you're actually working in (e.g. an agent opened a different repository mid-session), call switch_project with the target repo's absolute root:

{ "root_dir": "/mnt/repos/my-project" }

The target workspace's configured scope, database, UUID, numeric project ID, and root switch together after initialization succeeds. Status, indexing, and source snippets use the new root. An asynchronous call already in progress finishes using its original context. Invalid paths, corrupt configuration, or database initialization failures leave the previous context usable.

Branched Chats and Stale IDs

At the start of a new or branched chat:

1. Call cogmemory_status and compare workspace_root with the actual workspace. Chat history and cached numeric IDs are not authoritative.
2. If the root differs, call switch_project with the intended absolute root, then fetch memory again. Do not clear the identity file to resolve a client workspace mismatch.
3. Reuse the workspace UUID. Start a new memory session with start_session if needed; a chat branch is not a new project.

Tool JSON responses include project_identity: { id, slug, workspace_root }. Tools accept optional expected_project_id, containing the UUID slug, to reject stale context before reading or writing. This is especially useful because numeric IDs can coincide across separate databases. On PROJECT_MISMATCH, check status and switch to the intended root before retrying. Existing calls without the optional guard remain compatible. CogMemory cannot infer a chat's intended workspace when the client supplies neither a correct launch root nor a switch request.

Optional stale session/plan links on memory writes are ignored with a response warning; the memory still saves under the active project. Explicit session reads and updates are project-scoped and return a not-found response with recovery instructions for a stale session ID.

Recovering Earlier Identity Drift

Earlier project-scope startup could choose memory-A.db and then persist UUID B inside that database and the workspace config. Startup now keeps one UUID throughout initialization, serializes concurrent initialization, and publishes config changes atomically.

For existing affected stores, startup inspects project databases read-only. If exactly one stored identity matches the UUID or exact workspace root, it reuses that database in place, preserving its row IDs and memories. The config records project_database_id as the UUID from the existing database filename; this can legitimately differ from project_id. No database is renamed, merged, or deleted.

If several candidates match, PROJECT_IDENTITY_AMBIGUOUS lists { databaseId, slug } pairs and leaves the config unchanged. Select the intended pair in .cogmemory/config.json, preserving other settings:

{

"scope": "project", "project_id": " ", "project_database_id": " " }

Then restart the MCP server, or retry switch_project if it is already running. The selected database must contain that UUID. Other candidate databases remain available; combining fragmented histories is a separate, explicit operation.

Malformed JSON, invalid UUIDs, and invalid local scopes produce PROJECT_CONFIG_INVALID instead of silently replacing identity. Restore a valid config from backup. Initialization locks have a bounded wait and report PROJECT_BUSY; if a process crashed while holding a lock, inspect the reported directory's owner.json, confirm that owner has exited, remove only that abandoned lock directory, and retry. Never delete an active process's lock.

Run pnpm test:identity for isolated regression tests of restart/branch continuity, concurrent processes, recovery, switching, stale IDs, UUID guards, and in-flight calls.

Multi-Root / Monorepos

Git-root discovery takes precedenc