{
  "markdown": "# CogMemory MCP Server\n\nA unified [Model Context Protocol](https://modelcontextprotocol.io/) server providing four context subsystems for AI coding agents:\n\n1. **Memory** — decisions, conventions, errors, active context, changelog, plan, tasks, sessions\n2. **Knowledge Graph** — entities, relations, observations\n3. **Specs** — long-form documents (PRD/SRS), optionally linked to a KG entity\n4. **Code Graph** — static structural graph (symbols/edges) + named execution traces + AI-generated annotations\n\nStorage: **SQLite** via `better-sqlite3`. One `.db` file per scope.\n\n---\n\n## Quick Start\n\n### Install\n\n**Option A — npx (recommended, always latest):**\n\n```bash\nnpx -y cogmemory-mcp@latest\n```\n\n**Option B — Global install:**\n\n```bash\nnpm install -g cogmemory-mcp\ncogmemory-mcp\n```\n\n**Option C — pnpm dlx:**\n\n```bash\npnpm dlx cogmemory-mcp@latest\n```\n\n**Option D — From source (developers):**\n\n```bash\ngit clone https://github.com/skylarng89/cogmemory-mcp.git\ncd cogmemory-mcp\npnpm install\npnpm run build\n```\n\n### Native Module Requirements\n\nCogMemory depends on `better-sqlite3` and `tree-sitter`, which compile native modules on install. You need:\n\n- **Python 3** (for `node-gyp`)\n- **C/C++ compiler** (`gcc`/`g++` on Linux, Xcode Command Line Tools on macOS, Visual Studio Build Tools on Windows)\n- **`make`** (Linux/macOS, installed by default)\n\nMost platforms have **prebuilt binaries** available, so compilation is usually skipped on:\n\n- Linux x64 / arm64\n- macOS x64 / arm64\n- Windows x64\n\nIf installation fails, see [Troubleshooting](#troubleshooting) below.\n\n---\n\n## IDE / Client Configuration\n\n### VS Code\n\nAdd to `.vscode/mcp.json` (workspace-scoped):\n\n```json\n{\n  \"servers\": {\n    \"cogmemory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cogmemory-mcp@latest\"]\n    }\n  }\n}\n```\n\nOr use `--workspace` for multi-root support:\n\n```json\n{\n  \"servers\": {\n    \"cogmemory-frontend\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cogmemory-mcp@latest\", \"--workspace\", \"/path/to/frontend\"]\n    },\n    \"cogmemory-backend\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cogmemory-mcp@latest\", \"--workspace\", \"/path/to/backend\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"cogmemory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cogmemory-mcp@latest\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to `~/.config/claude/claude_desktop_config.json` (Linux/macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"cogmemory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cogmemory-mcp@latest\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\nAdd to `~/.claude/mcp.json` (user-level) or `.claude/mcp.json` (project-level):\n\n```json\n{\n  \"mcpServers\": {\n    \"cogmemory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cogmemory-mcp@latest\"]\n    }\n  }\n}\n```\n\n### Cline\n\nIn the Cline extension settings, add an MCP server:\n\n- **Name:** `cogmemory`\n- **Command:** `npx -y cogmemory-mcp@latest`\n\nOr in `cline_mcp_settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"cogmemory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cogmemory-mcp@latest\"]\n    }\n  }\n}\n```\n\n### Windsurf\n\nMCP settings → Add server:\n\n```json\n{\n  \"mcpServers\": {\n    \"cogmemory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cogmemory-mcp@latest\"]\n    }\n  }\n}\n```\n\n### OpenCode\n\nAdd to `opencode.json`:\n\n```json\n{\n  \"mcp\": {\n    \"cogmemory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cogmemory-mcp@latest\"]\n    }\n  }\n}\n```\n\n### Zed\n\nAdd to Zed settings (`settings.json`):\n\n```json\n{\n  \"context_servers\": {\n    \"cogmemory\": {\n      \"binary\": \"npx\",\n      \"args\": [\"-y\", \"cogmemory-mcp@latest\"]\n    }\n  }\n}\n```\n\n### MCP Registry\n\nCogMemory is published to the [MCP Registry](https://registry.modelcontextprotocol.io/). Registry-aware clients can discover and install it automatically.\n\n---\n\n## Scope Configuration\n\nCogMemory resolves scope in priority order:\n\n1. **`.cogmemory/config.json`** in workspace root:\n\n   ```json\n   { \"scope\": \"global\" }\n   ```\n\n2. **Environment variable**: `COGMEMORY_SCOPE=global`\n3. **Default**: `workspace`\n\n### Paths\n\n| Scope     | Database Path                           |\n| --------- | --------------------------------------- |\n| workspace | `<workspace_root>/.cogmemory/memory.db` |\n| global    | `~/.cogmemory/global.db`                |\n\n---\n\n## Workspace Resolution & Multi-Root Support\n\nCogMemory resolves the workspace root (where `.cogmemory/memory.db` lives) in this priority order:\n\n1. **`--workspace <path>`** CLI argument (highest priority)\n2. **`COGMEMORY_WORKSPACE`** environment variable\n3. **Walk up from CWD** looking for the nearest parent containing a `.cogmemory/` directory\n4. **Fallback to CWD**\n\n---\n\n## Upgrades & Migrations\n\nCogMemory 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.\n\n### First-Time Migration (Pre-v1.1.0 Databases)\n\nIf you are upgrading from a version prior to v1.1.0 that used the old schema:\n\n1. A **backup file** is created automatically: `<db_path>.backup-pre-migrate-<timestamp>`\n2. Migrations apply within a transaction — if any step fails, the database is rolled back\n3. If something goes wrong, you can restore from the backup: `cp memory.db.backup-* memory.db`\n4. Set `COGMEMORY_SKIP_BACKUP=1` to skip the backup (e.g., in CI or disk-constrained environments)\n\n### Opt-Out: Update Check Telemetry\n\nBy 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.\n\nTo disable this check:\n\n- **Environment variable:** `COGMEMORY_DISABLE_UPDATE_CHECK=1`\n- **Config file:** Add `{ \"disable_update_check\": true }` to `.cogmemory/config.json`\n\n---\n\n## Tool Reference (40 tools)\n\n### Memory Tools (14)\n\n| Tool                  | Description                                                    |\n| --------------------- | -------------------------------------------------------------- |\n| `start_session`       | Begin a work session (returns session ID)                      |\n| `end_session`         | Close session, store summary                                   |\n| `get_session_summary` | Recall session details including decisions, errors, changelog  |\n| `remember_decision`   | Log a decision with rationale and tags                         |\n| `remember_convention` | Log/update a convention (design token, pattern, style, naming) |\n| `log_error`           | Record an error with signature and resolution                  |\n| `set_active_context`  | Upsert current focus/task by key                               |\n| `get_active_context`  | Read current focus by key                                      |\n| `log_change`          | Append changelog entry                                         |\n| `add_plan_item`       | Add a roadmap item                                             |\n| `update_plan_status`  | Change plan item status                                        |\n| `create_task`         | Create a task, optionally linked to a plan                     |\n| `update_task_status`  | Change task status                                             |\n| `recall`              | Unified search across decisions/conventions/errors/changelog   |\n\n### Knowledge Graph Tools (4)\n\n| Tool               | Description                             |\n| ------------------ | --------------------------------------- |\n| `create_entity`    | Add entity (deduped on name+type)       |\n| `create_relation`  | Link two entities with a typed relation |\n| `add_observation`  | Attach a fact to an entity              |\n| `search_knowledge` | Query entities, relations, observations |\n\n### Specs Tools (3)\n\n| Tool          | Description                              |\n| ------------- | ---------------------------------------- |\n| `create_spec` | Store a long-form document               |\n| `get_spec`    | Retrieve by ID or exact title            |\n| `update_spec` | Update content/title, auto-bumps version |\n\n### Code Graph Tools (4)\n\n| Tool               | Description                                                                          |\n| ------------------ | ------------------------------------------------------------------------------------ |\n| `index_codebase`   | Walk workspace, extract symbols + edges (JS/TS via ts-morph, Python via tree-sitter) |\n| `query_code_graph` | Look up a symbol's callers/callees/imports (1-hop)                                   |\n| `generate_codemap` | BFS from entry symbol, bounded subgraph with optional traces + annotations           |\n| `annotate_symbol`  | Attach narrative text to a symbol or trace                                           |\n\n### Introspection Tools (2)\n\n| Tool                | Description                                                                                                                |\n| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| `cogmemory_status`  | Show runtime config: package version, schema version, db path, workspace root, scope, index coverage, and subsystem counts |\n| `check_for_updates` | Check if a newer version is available on npm (HTTPS GET to registry, cached 24h)                                           |\n\n### Code Analysis Tools (8)\n\n| Tool                   | Description                                                                                                                       |\n| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `semantic_code_search` | TF-IDF based semantic code search — natural language query returns ranked symbols by relevance                                    |\n| `find_dead_code`       | Find symbols with zero inbound callers, excluding exported symbols and configurable entry points                                  |\n| `find_duplicates`      | Detect duplicate/clone symbol pairs via exact hash + MinHash similarity, inserts `SIMILAR_TO` edges                               |\n| `find_related`         | Discover semantically-related symbols via shared callers/imports/same-file heuristics, inserts `SEMANTICALLY_RELATED` edges       |\n| `query_graph`          | Multi-hop structural graph query using recursive CTE — supports arbitrary depth, edge-type filters, direction                     |\n| `analyze_impact`       | Analyze impact of uncommitted changes (`git diff`) — maps changed files to symbols and computes reverse transitive caller closure |\n| `get_code_snippet`     | Fetch source code lines for a symbol by ID or name, with optional context padding                                                 |\n| `check_index_coverage` | Report indexed vs. unindexed vs. stale files with per-language breakdowns                                                         |\n\n### List & Delete Tools (5)\n\n| Tool              | Description                                                    |\n| ----------------- | -------------------------------------------------------------- |\n| `list_items`      | Browse stored entries from any subsystem with optional filters |\n| `delete_item`     | Delete a single row by ID from any subsystem                   |\n| `delete_by_key`   | Delete a context entry by its string key                       |\n| `delete_by_path`  | Remove a file from the code graph file_index                   |\n| `purge_subsystem` | Remove ALL rows from a subsystem (requires `confirm=true`)     |\n\n---\n\n## Architecture\n\n```plain\ncogmemory-mcp/\n├── src/\n│   ├── index.ts                 # entry point, server bootstrap\n│   ├── version.ts               # auto-generated version constant\n│   ├── config.ts                # scope resolution, path resolution\n│   ├── types.ts                 # shared TS types mirroring schema\n│   ├── db/\n│   │   ├── connection.ts        # DB open/close, pragma setup\n│   │   ├── migration-runner.ts  # versioned migration engine (PRAGMA user_version)\n│   │   ├── migrate.ts           # legacy idempotent migration (deprecated)\n│   │   └── migrations/\n│   │       ├── 001_baseline.sql         # full v1 schema\n│   │       ├── 002_symbol_export_hash.sql\n│   │       ├── 003_index_errors.sql\n│   │       ├── 004_symbol_embeddings.sql\n│   │       ├── 005_edge_metadata.sql\n│   │       ├── 006_symbol_tokens.sql\n│   │       └── 007_symbol_minhash.sql\n│   ├── tools/\n│   │   ├── memory.ts            # decisions/conventions/errors/context/changelog/recall\n│   │   ├── plan-tasks.ts        # plan + tasks tools\n│   │   ├── sessions.ts          # start/end session, summary\n│   │   ├── knowledge-graph.ts   # entities/relations/observations\n│   │   ├── specs.ts             # spec CRUD\n│   │   ├── code-graph.ts        # index_codebase, query_code_graph\n│   │   ├── codemap.ts           # generate_codemap, annotate_symbol\n│   │   ├── code-analysis.ts     # dead code, duplicates, related, graph query, impact, snippet, coverage, search\n│   │   ├── introspection.ts     # cogmemory_status, check_for_updates\n│   │   ├── list-delete.ts       # list_items, delete_item, purge_subsystem\n│   │   └── utils.ts             # wrapHandler, jsonOk, jsonFail, jsonErr\n│   └── indexing/\n│       ├── ts-analyzer.ts       # ts-morph symbol/edge extraction (JS/TS)\n│       ├── py-analyzer.ts       # tree-sitter symbol/edge extraction (Python)\n│       ├── edge-types.ts        # edge type constants (calls, imports, extends, implements, similarto, semrelated)\n│       └── walker.ts            # file discovery, gitignore respect\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n---\n\n## Schema (25 tables)\n\n**Base tables (21):**\n\n- **Memory (8):** `sessions`, `decisions`, `conventions`, `errors`, `context`, `changelog`, `plan`, `tasks`\n- **Knowledge Graph (3):** `entities`, `relations`, `observations`\n- **Specs (1):** `specs`\n- **Code Graph (5):** `symbols` (with `is_exported`, `body_hash`, `token_count` columns), `edges` (with `metadata` JSON column), `execution_traces`, `codemap_annotations`, `file_index`\n- **Code Analysis (3):** `index_errors`, `symbol_tokens` (TF-IDF), `symbol_minhash` (MinHash signatures)\n- **Future (1):** `symbol_embeddings` (stub — vector embeddings for Phase 2)\n\n**FTS5 tables (4):**\n\n- **Recall FTS:** `recall_docs` (content table) + `recall_fts` (FTS5 virtual table) — powers `recall`\n- **Knowledge Graph FTS:** `kg_docs` (content table) + `kg_fts` (FTS5 virtual table) — powers `search_knowledge`\n\nSchema migrations are automatic via `PRAGMA user_version` (currently at version 7).\n\n---\n\n## Supported Languages\n\nThe Code Graph (`index_codebase`) extracts symbols and edges from source files using language-specific analyzers:\n\n| Language   | Extensions                    | Analyzer    | Symbols Extracted                                                                                   |\n| ---------- | ----------------------------- | ----------- | --------------------------------------------------------------------------------------------------- |\n| TypeScript | `.ts`, `.tsx`                 | ts-morph    | files, functions, classes, interfaces, methods, type aliases, enums, variables (with `is_exported`) |\n| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | ts-morph    | files, functions, classes, methods, variables                                                       |\n| Python     | `.py`                         | tree-sitter | files, functions, classes, methods (with `is_exported` via `__all__` / underscore rule)             |\n\n**Structural edges:** calls, imports, extends, implements\n\n**Analysis edges:** `similarto` (clone detection), `semrelated` (semantic relation discovery)\n\n---\n\n## Pragmas\n\nSet on every connection open:\n\n```sql\nPRAGMA journal_mode = WAL;\nPRAGMA foreign_keys = ON;\n```\n\n---\n\n## Development\n\n```bash\npnpm run dev        # Run with tsx (no build step)\npnpm run build      # Compile TypeScript (regenerates version.ts via prebuild)\npnpm run start      # Run compiled output\npnpm run inspect    # Launch MCP Inspector\npnpm run smoke-test # Run smoke test script (43 checks)\n```\n\n---\n\n## Troubleshooting\n\n### Native module build failure\n\nIf `npm install` or `pnpm install` fails with `node-gyp` errors:\n\n1. **Install Python 3:** `python3 --version` — if missing, install via your package manager\n2. **Install C++ build tools:**\n   - **macOS:** `xcode-select --install`\n   - **Ubuntu/Debian:** `sudo apt-get install build-essential`\n   - **Windows:** Install Visual Studio Build Tools with the \"C++ build tools\" workload\n3. **Retry:** `npm rebuild better-sqlite3` (or `npm rebuild tree-sitter`)\n\n### Migration failure\n\nIf the server exits with a migration error:\n\n1. Check stderr for the error message and the migration file number\n2. Restore from backup: `cp .cogmemory/memory.db.backup-* .cogmemory/memory.db`\n3. Try again — the migration will re-run from the current `user_version`\n\n### Large workspace performance\n\nFor workspaces with 50k+ files:\n\n1. Use `.gitignore` to exclude vendored/generated code (CogMemory respects it)\n2. The walker skips `node_modules`, `.git`, `dist`, `build`, `.next`, `.cogmemory`, `__pycache__`, `.venv`, `venv`, `*.min.js`, `*.min.css`, `*.map` by default\n3. Index coverage: the `check_index_coverage` tool paginates unindexed file reports at 1000 entries\n\n### `analyze_impact` — git not available\n\nIf the workspace is not a git repository, `analyze_impact` with auto-detection will fail. Pass `changed_files` manually instead.\n\n---\n\n## License\n\nMIT\n",
  "bytes": 17684,
  "sha": "055cf172be4891685c4bceab2c9d38367ac90e855e93f241cb2a0dca399c1773",
  "repo_slug": "skylarng89/cogmemory-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_skylarng89_cogmemory_mcp_161d2ad4/readme"
}