Context-MCP

Persistent memory and codebase knowledge graph for AI coding assistants — delivered as a single MCP server.

One shared context store across Claude Code, VS Code Copilot, Google Antigravity (2.0 / IDE / CLI), Codex CLI, Hermes Agent, Claude.ai, and ChatGPT. Save context from one AI, pick it up in another.

The Problem

Every conversation with an AI assistant starts from zero. The AI re-reads files it already read yesterday, re-discovers architecture it already understood, re-derives decisions that were already made. You repeat context. You paste the same background.

This gets worse as projects grow — reading 20 files to answer "what calls this function?" burns thousands of tokens every time.

Related MCP server: hive-memory

What It Solves

• Persistent memory — decisions, bugs, notes, and config saved across sessions, loaded automatically at conversation start

• Shared store — ~/.context-mcp/projects/<name>/ per-project on your machine; all AI tools read and write it

• ContextGraph — build a knowledge graph of your codebase once, answer structural questions in ~500 tokens instead of ~50,000

The repository includes a reproducible offline benchmark for measuring context compression and retrieval quality; reported values are generated locally from the benchmark fixture.

Context Subgraph Pipeline

Code files ──Tree-sitter AST──> entities + relations ──> ContextGraph cache
                                                          │
AI task ──lexical seeds──> relation-aware BFS ──> rank + recency ──> token budget
                                                          │
                                                          └──> compact MCP context

codegraph_context keeps callers, dependencies, imports, inheritance and implementation paths together while enforcing the requested token budget. It returns tokens_used, candidate_count, dropped_count, drop_reasons, and path metadata so an agent can explain why context was selected or omitted.

Run the reproducible offline benchmark with:

python scripts/benchmark_context.py --budget 160

The benchmark reports Top-K recall, path accuracy, latency, budget compliance, and context compression using a fixed graph fixture. It does not call an external model or online API.

Installation

npm install -g context-mcp-server

Requires Node.js ≥ 18. Installs context-mcp, context-mcp-http, and the ctx CLI.

ContextGraph requires uv (Python runner). Memory tools work without it.

# macOS / Linux
curl -Ls https://astral.sh/uv/install.sh | sh

# Windows
winget install astral-sh.uv

Quick Start

Run from your project root:

ctx install --initial

This installs Node.js + Python (ContextGraph) dependencies. Run once after installing the npm package.

Then write MCP config + AI instruction files:

ctx install --all

To install for a specific platform only:

ctx install --claude      # Claude Code
ctx install --vscode      # VS Code Copilot
ctx install --antigravity # Google Antigravity (2.0 / IDE / CLI)
ctx install --codex       # Codex CLI
ctx install --hermes      # Hermes Agent

For Codex project installs, ctx install --codex writes:

• .codex/config.toml with [mcp_servers.context-mcp] MCP configuration.

• AGENTS.md with Context-MCP usage rules for Codex.

• .codex/hooks/ pre/post shell hook scripts for project-local Codex sessions.

For web clients (Claude.ai, ChatGPT), start the HTTP server:

ctx online               # start in background, prints OAuth credentials + URL
ctx online --restart     # force restart
ctx online --port 3200   # different port

Claude Code plugin

This repo is also a self-hosted Claude Code plugin marketplace — an alternative to ctx install --claude that doesn't require cloning or npm-installing anything yourself:

claude plugin marketplace add yesheng-oss/789
claude plugin install context-mcp@context-mcp-marketplace

or from inside a session: /plugin marketplace add yesheng-oss/789 then /plugin install context-mcp@context-mcp-marketplace. This installs the context-mcp skill, the Bash pre/post-tool-use hooks, and registers the MCP server (still launched via npx context-mcp-server@latest) — everything ctx install --claude writes into ~/.claude/, bundled as one installable unit. ctx install --initial is still required once to install the ContextGraph Python environment.

CLI Reference

Both ctx and context are aliases for the same CLI.

ctx                            # interactive mode (UI)

# Context
ctx list [project]             # list entries by tree: graph / context / summary / plans
ctx projects                   # all projects with graph status + recent entries
ctx search "query"             # keyword → semantic fallback search
ctx add                        # add entry interactively
ctx summary [project]          # summarize recent entries

# Delete
ctx delete <id-prefix>         # delete one entry
ctx delete project <name>      # delete all entries for a project

# Server
ctx online                     # start HTTP server (idempotent)
ctx online --restart           # force stop + restart
ctx settings                   # view and edit config interactively

# Install
ctx install --initial          # install / update Node.js + Python deps
ctx install --all              # write config + rules for all platforms

Security

File and git tools are sandboxed to your project root. Pass rootPath when calling context.resume:

{ "action": "resume", "project": "my-app", "rootPath": "/home/user/my-app" }

Any file or git operation outside that directory is rejected. Applies to all HTTP-connected clients.

Features

Memory

• context.resume — loads recent entries, active plans, and graph status; registers rootPath for sandboxing

• context.save — store context as note (or compaction for session summaries); categorize with free-form tags

• context.get / context.update / context.delete — full CRUD, single or batch

• search — keyword-first, semantic fallback

• plan — auto-triggered when AI makes any plan; saves a markdown summary to a planDir you specify

• Auto-deduplication on save; auto-compact at 20 entries → stored in summary.json

ContextGraph

Also called CodeGraph. MCP tools use the codegraph_* prefix — both names mean the same thing.

Step 1 — Build (once per project, runs locally, no API cost):

codegraph_build(path)

Parses codebase via tree-sitter AST (16 languages, regex fallback). Extracts functions, classes, imports, call edges, and inheritance. Every node carries a full enriched schema: signature, params, return_type, docstring, side_effect, exported, complexity, last_modified. PageRank scores all nodes by connectivity. Metadata saved to <project>/codegraph-cache/.

Step 2 — Query (instant, forever):

codegraph_arch(path, limit?)                     → module map: every file, its exports, its imports
codegraph_query(path, question?, node?)          → structural question OR single-node lookup (or both)
codegraph_nodes(path, type, token_budget?)       → all nodes of a type, sorted by PageRank
codegraph_filter(path, node_type?, exported?,    → predicate filter: side_effect, return_type,
  side_effect?, return_type?, called_by?,          called_by, file_pattern — rank-sorted output
  calls?, file_pattern?, token_budget?)
codegraph_report(path)                           → god nodes, clusters, surprising connections
codegraph_affected(path, node, depth?)           → BFS blast radius — what breaks if you change X?

codegraph_query accepts question (natural language), node (exact/partial name), or both. codegraph_filter answers property questions ("which functions have side effects?", "all exported async handlers") without reading any files. Pass token_budget to any tool to get the highest-rank results within a token limit.

What's in each node (v1.2+):

Step 3 — Visualize (auto-generated on every build):

codegraph_html(path, formats?)            → regenerate visualizations on demand

Every codegraph_build automatically writes to <project>/codegraph-cache/:

• graph.html — interactive vis.js force graph (dark theme, search, community toggle)

• tree.html — D3 collapsible file hierarchy

• callflow.html — Mermaid architecture diagrams per community

• graph.graphml — Gephi / yEd export

• obsidian/ — per-node .md vault with [[wikilinks]]

File & Git Tools

Available to HTTP-connected clients (Claude.ai, ChatGPT). Local AI clients use their native IDE tools.

• read_file, write_file, patch_file, create_dir, list_dir, delete_file

• git_status, git_diff, git_log, git_add, git_commit, git_push, git_pull, git_branch, git_stash, git_reset, git_show

Enable git tools with --access-git flag or access_git: true in config.

Server Flags

context-mcp [--data-dir <path>]

context-mcp-http [--port <number>] [--host <string>] [--access-git] [--data-dir <path>]

Default port: 3100. Default data dir: ~/.context-mcp.

Config Reference

~/.context-mcp/contextconfig.json — auto-created on first run:

Edit with ctx settings.