The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Cogmemory MCP listing page.
A unified Model Context Protocol server providing four context subsystems for AI coding agents:
Storage: SQLite via better-sqlite3. One .db file per scope.
Option A — npx (recommended, always latest):
Option B — Global install:
Option C — pnpm dlx:
Option D — From source (developers):
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):
Or use --workspace for multi-root support:
Add to .cursor/mcp.json:
Add to ~/.config/claude/claude_desktop_config.json (Linux/macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
Add to ~/.claude/mcp.json (user-level) or .claude/mcp.json (project-level):
In the Cline extension settings, add an MCP server:
cogmemorynpx -y cogmemory-mcp@latestOr in cline_mcp_settings.json:
MCP settings → Add server:
Add to opencode.json:
Add to Zed settings (settings.json):
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 workspace root:
Environment variable: COGMEMORY_SCOPE=global
Default: workspace
| Scope | Database Path |
|---|---|
| workspace | <workspace_root>/.cogmemory/memory.db |
| global | ~/.cogmemory/global.db |
CogMemory resolves the workspace root (where .cogmemory/memory.db lives) in this priority order:
--workspace <path> CLI argument (highest priority)COGMEMORY_WORKSPACE environment variable.cogmemory/ directoryCogMemory 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) |
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 7).
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:
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