cogmemory-mcp
Advanced tools
A unified Model Context Protocol server providing four context subsystems for AI coding agents:
Storage: SQLite via better-sqlite3. By default, each clone gets its own
database under ~/.cogmemory/projects/.
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
CogMemory depends on better-sqlite3 and tree-sitter, which compile native modules on install. You need:
node-gyp)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:
If installation fails, see Troubleshooting below.
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--workspacefor monorepo sub-root targeting.
Add to .cursor/mcp.json:
{
"mcpServers": {
"cogmemory": {
"command": "npx",
"args": ["-y", "cogmemory-mcp@latest"]
}
}
}
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"]
}
}
}
Add to ~/.claude/mcp.json (user-level) or .claude/mcp.json (project-level):
{
"mcpServers": {
"cogmemory": {
"command": "npx",
"args": ["-y", "cogmemory-mcp@latest"]
}
}
}
In the Cline extension settings, add an MCP server:
cogmemorynpx -y cogmemory-mcp@latestOr in cline_mcp_settings.json:
{
"mcpServers": {
"cogmemory": {
"command": "npx",
"args": ["-y", "cogmemory-mcp@latest"]
}
}
}
MCP settings → Add server:
{
"mcpServers": {
"cogmemory": {
"command": "npx",
"args": ["-y", "cogmemory-mcp@latest"]
}
}
}
Add to opencode.json:
{
"mcp": {
"cogmemory": {
"command": "npx",
"args": ["-y", "cogmemory-mcp@latest"]
}
}
}
Add to Zed settings (settings.json):
{
"context_servers": {
"cogmemory": {
"binary": "npx",
"args": ["-y", "cogmemory-mcp@latest"]
}
}
}
CogMemory is published to the MCP Registry. Registry-aware clients can discover and install it automatically.
CogMemory resolves scope in priority order:
.cogmemory/config.json in the workspace root (project-level override):
{ "scope": "project" }
Environment variable: COGMEMORY_SCOPE=project, global, or workspace
User-level fallback: ~/.cogmemory/config.json (scope settings only)
Default: project — one database per clone under ~/.cogmemory/projects/
Default is clone-specific. Each clone receives a UUID in
.cogmemory/config.jsonand 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" }orCOGMEMORY_SCOPE=globalto retain the legacy shared database, or{ "scope": "workspace" }for a database inside the repository.
| Scope | Database Path |
|---|---|
| project | ~/.cogmemory/projects/memory-<project-id>.db |
| workspace | <workspace_root>/.cogmemory/memory.db |
| global | ~/.cogmemory/global.db |
Upgrading? If a workspace has an existing
memory.dbbut no config file, CogMemory logs a stderr advisory when the project default bypasses it — add{ "scope": "workspace" }to that project's.cogmemory/config.jsonto keep using it. Existing data inglobal.dbremains available whenCOGMEMORY_SCOPE=globalis explicitly selected; it is not silently repartitioned.
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:
${workspaceFolder} can point at a single shared database path; each project's memories remain isolated by slug.~/.cogmemory/global.db can hold many projects, with every read/write implicitly scoped to the active project's slug..cogmemory/config.json & GitKeep .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.
| Tool | Purpose |
|---|---|
list_projects | All projects with row counts, last-seen timestamps, staleness flags |
rename_project | Change a project's display label (slug is immutable) |
prune_projects | Permanently delete a project and all of its rows (requires confirm) |
switch_project | Re-resolve the active project at runtime from a workspace root |
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.
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.
At the start of a new or branched chat:
cogmemory_status and compare workspace_root with the actual workspace. Chat history and cached numeric IDs are not authoritative.switch_project with the intended absolute root, then fetch memory again. Do not clear the identity file to resolve a client workspace mismatch.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.
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.
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.
CogMemory resolves the workspace root (and thus the project identity anchor) in this priority order:
--workspace <path> CLI argument (explicit override, highest priority)COGMEMORY_WORKSPACE environment variable (explicit override).git/ entry (default signal for git repositories).cogmemory/ directoryFor 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.
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.
If you are upgrading from a version prior to v1.1.0 that used the old schema:
<db_path>.backup-pre-migrate-<timestamp>cp memory.db.backup-* memory.dbCOGMEMORY_SKIP_BACKUP=1 to skip the backup (e.g., in CI or disk-constrained environments)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:
COGMEMORY_DISABLE_UPDATE_CHECK=1{ "disable_update_check": true } to .cogmemory/config.json| Tool | Description |
|---|---|
start_session | Begin a work session (returns session ID) |
end_session | Close session, store summary |
get_session_summary | Recall session details including decisions, errors, changelog |
remember_decision | Log a decision with rationale and tags |
remember_convention | Log/update a convention (design token, pattern, style, naming) |
log_error | Record an error with signature and resolution |
set_active_context | Upsert current focus/task by key |
get_active_context | Read current focus by key |
log_change | Append changelog entry |
add_plan_item | Add a roadmap item |
update_plan_status | Change plan item status |
create_task | Create a task, optionally linked to a plan |
update_task_status | Change task status |
recall | Unified search across decisions/conventions/errors/changelog |
| Tool | Description |
|---|---|
create_entity | Add entity (deduped on name+type) |
create_relation | Link two entities with a typed relation |
add_observation | Attach a fact to an entity |
search_knowledge | Query entities, relations, observations |
| Tool | Description |
|---|---|
create_spec | Store a long-form document |
get_spec | Retrieve by ID or exact title |
update_spec | Update content/title, auto-bumps version |
| Tool | Description |
|---|---|
index_codebase | Walk workspace, extract symbols + edges (JS/TS via ts-morph, Python via tree-sitter) |
query_code_graph | Look up a symbol's callers/callees/imports (1-hop) |
generate_codemap | BFS from entry symbol, bounded subgraph with optional traces + annotations |
annotate_symbol | Attach narrative text to a symbol or trace |
| Tool | Description |
|---|---|
cogmemory_status | Show runtime config: package version, schema version, db path, workspace root, scope, index coverage, and subsystem counts |
check_for_updates | Check if a newer version is available on npm (HTTPS GET to registry, cached 24h) |
| Tool | Description |
|---|---|
semantic_code_search | TF-IDF based semantic code search — natural language query returns ranked symbols by relevance |
find_dead_code | Find symbols with zero inbound callers, excluding exported symbols and configurable entry points |
find_duplicates | Detect duplicate/clone symbol pairs via exact hash + MinHash similarity, inserts SIMILAR_TO edges |
find_related | Discover semantically-related symbols via shared callers/imports/same-file heuristics, inserts SEMANTICALLY_RELATED edges |
query_graph | Multi-hop structural graph query using recursive CTE — supports arbitrary depth, edge-type filters, direction |
analyze_impact | Analyze impact of uncommitted changes (git diff) — maps changed files to symbols and computes reverse transitive caller closure |
get_code_snippet | Fetch source code lines for a symbol by ID or name, with optional context padding |
check_index_coverage | Report indexed vs. unindexed vs. stale files with per-language breakdowns |
| Tool | Description |
|---|---|
list_items | Browse stored entries from any subsystem with optional filters |
delete_item | Delete a single row by ID from any subsystem |
delete_by_key | Delete a context entry by its string key |
delete_by_path | Remove a file from the code graph file_index |
purge_subsystem | Remove ALL rows from a subsystem (requires confirm=true) |
| Tool | Description |
|---|---|
list_projects | List all projects with row counts, staleness flags; active project marked |
rename_project | Rename a project's display label (slug is immutable) |
prune_projects | Permanently delete a project and all of its rows (requires confirm=true) |
switch_project | Re-resolve the active project at runtime from a workspace root (fail-closed) |
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
Base tables (21):
sessions, decisions, conventions, errors, context, changelog, plan, tasksentities, relations, observationsspecssymbols (with is_exported, body_hash, token_count columns), edges (with metadata JSON column), execution_traces, codemap_annotations, file_indexindex_errors, symbol_tokens (TF-IDF), symbol_minhash (MinHash signatures)symbol_embeddings (stub — vector embeddings for Phase 2)FTS5 tables (4):
recall_docs (content table) + recall_fts (FTS5 virtual table) — powers recallkg_docs (content table) + kg_fts (FTS5 virtual table) — powers search_knowledgeSchema migrations are automatic via PRAGMA user_version (currently at version 9).
The Code Graph (index_codebase) extracts symbols and edges from source files using language-specific analyzers:
| Language | Extensions | Analyzer | Symbols Extracted |
|---|---|---|---|
| TypeScript | .ts, .tsx | ts-morph | files, functions, classes, interfaces, methods, type aliases, enums, variables (with is_exported) |
| JavaScript | .js, .jsx, .mjs, .cjs | ts-morph | files, functions, classes, methods, variables |
| Python | .py | tree-sitter | files, functions, classes, methods (with is_exported via __all__ / underscore rule) |
Structural edges: calls, imports, extends, implements
Analysis edges: similarto (clone detection), semrelated (semantic relation discovery)
Set on every connection open:
PRAGMA journal_mode = WAL;
PRAGMA foreign_keys = ON;
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)
If npm install or pnpm install fails with node-gyp errors:
python3 --version — if missing, install via your package managerxcode-select --installsudo apt-get install build-essentialnpm rebuild better-sqlite3 (or npm rebuild tree-sitter)If the server exits with a migration error:
cp .cogmemory/memory.db.backup-* .cogmemory/memory.dbuser_versionFor workspaces with 50k+ files:
.gitignore to exclude vendored/generated code (CogMemory respects it)node_modules, .git, dist, build, .next, .cogmemory, __pycache__, .venv, venv, *.min.js, *.min.css, *.map by defaultcheck_index_coverage tool paginates unindexed file reports at 1000 entriesanalyze_impact — git not availableIf the workspace is not a git repository, analyze_impact with auto-detection will fail. Pass changed_files manually instead.
MIT
.github/workflows/publish.yml runs four separate jobs:
| Job | Work | Rerun behavior |
|---|---|---|
| Build and verify / prepare recovery | Validate tag against package.json, synchronize registry metadata, build, run smoke and identity tests, and pack once | Uploads an artifact unique to this run attempt |
| Publish npm | Verify artifact integrity, then publish the tarball with OIDC/provenance | Skips only an existing release with identical npm metadata and tarball integrity |
| Publish MCP Registry | Wait for the exact npm version to be public, authenticate with OIDC, and register it | Verifies matching existing registrations; retries transient publication failures |
| Release summary | Read actual job results and publication outputs | Reports failed/skipped jobs and distinguishes npm submission from confirmed availability |
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.
vX.Y.Z tag. The tag must match package.json; the workflow rejects mismatches.smoke-test and test:identity, records the source commit in package metadata, and packs the tested build.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.
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.
Once this workflow change is on the default branch:
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.
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.
FAQs
CogMemory MCP Server — Unified context subsystems for AI coding agents
The npm package cogmemory-mcp receives a total of 410 weekly downloads. As such, cogmemory-mcp popularity was classified as not popular.
We found that cogmemory-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.