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.

Related MCP server: LumenCore

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

2. Environment variable: COGMEMORY_SCOPE=project, global, or workspace

3. User-level fallback: ~/.cogmemory/config.json (scope settings only)

4. 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-<project-id>.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": "<slug from the selected candidate>",
  "project_database_id": "<databaseId from the same candidate>"
}

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 precedence over ancestor .cogmemory/ discovery when walking up from CWD. In monorepos, pin the intended root explicitly with --workspace <path> or COGMEMORY_WORKSPACE to avoid silently attaching to the wrong project.

Workspace Resolution & Multi-Root Support

CogMemory resolves the workspace root (and thus the project identity anchor) in this priority order:

1. --workspace <path> CLI argument (explicit override, highest priority)

2. COGMEMORY_WORKSPACE environment variable (explicit override)

3. Git root — walk up from CWD looking for the nearest .git/ entry (default signal for git repositories)

4. Walk up from CWD looking for the nearest parent containing a .cogmemory/ directory

5. Fallback to CWD

For most clients no configuration is needed: launch CogMemory with no --workspace and it attaches to the git repository containing the client's working directory. Every repo therefore gets its own project identity automatically.

CogMemory refuses to bootstrap a project from the user's home directory or the filesystem root. This prevents a client that starts MCP servers from a generic process directory from silently storing memories under the wrong project. Configure the client with a workspace-scoped entry or set COGMEMORY_WORKSPACE to the literal project root when it cannot provide the correct working directory.

Pin --workspace/COGMEMORY_WORKSPACE only when the identity anchor must differ from the git root — e.g. targeting a subdirectory of a monorepo as a separate project.

cogmemory_status reports the active workspace_root, root_path_hint, database path, and UUID. Invalid explicit workspace overrides fail rather than falling back to an unrelated directory.

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 (41 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)

Project Tools (4)

Architecture

cogmemory-mcp/
├── src/
│   ├── index.ts                 # entry point, server bootstrap
│   ├── version.ts               # auto-generated version constant
│   ├── config.ts                # scope resolution, path resolution
│   ├── update-check.ts          # fail-safe startup update notifier (update-notifier)
│   ├── 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
│   │       ├── 008_project_scoping.sql
│   │       └── 009_project_scoped_uniques.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 9).

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

Release workflow and recovery

.github/workflows/publish.yml runs four separate jobs:

The pnpm store cache is keyed by the lockfile. node_modules is not shared between runners; approved native dependencies build on the build runner. The verified tarball, synchronized server.json, and release manifest are transferred as a 30-day workflow artifact, so rerunning only the MCP job does not rebuild or republish npm. The pinned MCP publisher archive is cached by version, OS, architecture, and checksum; the checksum is verified on every restore. That cache is saved before registration so a registry failure does not discard it.

Normal releases

1. Commit the intended version and push its matching vX.Y.Z tag. The tag must match package.json; the workflow rejects mismatches.

2. The build job runs both smoke-test and test:identity, records the source commit in package metadata, and packs the tested build.

3. npm publication submits that tarball without rerunning lifecycle builds. A successful submission may still be processing.

4. The MCP job checks the public npm version every 15 seconds for up to 10 minutes. Authentication errors or mismatched release contents fail immediately. Registry outages and transient MCP publication errors have bounded retries.

Publishing permissions are restricted to the npm and MCP jobs. The workflow filename remains publish.yml, preserving the existing trusted-publisher workflow identity. Releases remain serialized to avoid overlapping updates to npm's latest tag.

Rerun a failed stage

For runs using the new workflow, open the run in GitHub Actions and choose Re-run failed jobs, or rerun the Publish MCP Registry job specifically. Successful upstream jobs and their artifacts are reused. If the artifact has expired, start a new manual run instead. A complete rerun verifies an existing npm release rather than attempting to overwrite it; different contents for the same version fail safely.

Recover an older release, including v1.15.0

Once this workflow change is on the default branch:

1. Open Actions → Publish Package → Run workflow.

2. Select the default branch for the workflow implementation.

3. Enter the existing release tag, such as v1.15.0, and select mcp-only.

4. Run the workflow. It loads the current release helpers, checks out the selected tag for metadata, and skips dependency installation, the package build, and npm publishing.

MCP-only recovery verifies npm's package name, version, MCP name, repository, and gitHead against the selected tag before registering anything. It fails if the source commit cannot be verified. Old tagged server.json versions are synchronized from that tag's package.json. It does not move tags or change published packages. An existing MCP version with different metadata or an inactive status requires investigation rather than automatic replacement.

Rerunning the original old workflow run still uses its original workflow definition. Use this manual recovery path to recover old runs with the new logic.

Local release-helper checks

node --test scripts/release.test.mjs

These tests use temporary artifacts and mocked registries/commands; they never publish. Tests cover visibility delays, request failures, existing versions, integrity mismatches, source-commit verification, retry bounds, and summary accuracy. Hosted OIDC and publication still require a real GitHub Actions run.