ContextMesh — Intelligent Context Layer for Claude Code

One coding session. Infinite memory. 90% fewer tokens.

ContextMesh is a transparent AI proxy + memory engine that sits between Claude Code and the Anthropic API. It automatically compresses token waste, maintains a persistent knowledge graph of your work, and gives Claude perfect memory across sessions — all without changing how you use Claude.

Just run contextmesh init once. Then use claude normally forever.

How it works

Your Terminal
    │
    ▼
┌──────────────────────────────────────────┐
│         ContextMesh Smart Proxy          │  ← Intercepts every request
│  ┌─────────────────────────────────┐     │
│  │  RTK Output Compressor          │     │  ← Crushes terminal noise
│  │  Anti-Context Auto-Flusher      │     │  ← Removes old resolved turns
│  │  Session Resumption Injector    │     │  ← Injects last session memory
│  └─────────────────────────────────┘     │
└──────────────────────────────────────────┘
    │
    ▼
Anthropic API  (only sees clean, compressed, focused context)
    │
    ▼
┌──────────────────────────────────────────┐
│         ContextMesh Daemon               │  ← Background brain
│  ┌───────────────┐  ┌─────────────────┐  │
│  │ Session Graph │  │   AST RepoMap   │  │  ← NetworkX + Tree-sitter
│  │ (your memory) │  │ (code structure)│  │
│  └───────────────┘  └─────────────────┘  │
│  ┌─────────────────────────────────┐     │
│  │  File Watcher (auto-reindex)    │     │  ← Keeps repomap always fresh
│  └─────────────────────────────────┘     │
└──────────────────────────────────────────┘
    │
    ▼ MCP Server
Claude Code ← get_context() | get_project_architecture() | record_decision()

Features

Installation

# Install globally
pipx install claude-contextmesh

# One-time transparent setup (like RTK/Headroom — no wrapper needed after this!)
cd /path/to/your/project
contextmesh init

contextmesh init does 4 things automatically:

1. Shell Profile — writes ANTHROPIC_BASE_URL to ~/.zshrc so every claude session routes through the proxy
2. Claude Code Hooks — installs PreToolUse/PostToolUse hooks in ~/.claude/settings.json
3. Persistent Service — installs a macOS LaunchAgent (or Linux systemd unit) so the proxy auto-starts on login
4. MCP Server — connects the ContextMesh brain to Claude Code

Then reload your shell once:

source ~/.zshrc   # or source ~/.bashrc

From now on just use claude normally. ContextMesh intercepts everything transparently.

Commands

Core

contextmesh init          # One-time transparent setup (run once per machine)
contextmesh start         # Start the daemon manually (if not using the service)
contextmesh stop          # Stop the proxy service
contextmesh stop --all    # Stop both proxy AND daemon
contextmesh uninstall     # Remove all ContextMesh integrations cleanly

Stats & Monitoring

contextmesh stats                           # Global token savings report
contextmesh stats --session SESSION_ID      # Per-session breakdown
contextmesh turns --session SESSION_ID      # Per-turn savings table
contextmesh status                          # Check if daemon + proxy are running
contextmesh dashboard                       # Open live web dashboard in browser

Codebase

contextmesh index .                         # Manually index the current project
contextmesh proxy                           # Start the proxy manually (foreground)
contextmesh mcp                             # Run the MCP server (stdio)

Live Dashboard

After running contextmesh start, open your browser to:

http://127.0.0.1:8765/dashboard

You'll see a live, auto-refreshing dark-themed dashboard with:

• 4 stat cards: Raw tokens sent, Compressed tokens, Total saved (green), USD saved (green)
• SVG bar chart: Tokens saved per last 10 turns
• RTK Interception Log: Every compression event with timestamps and savings %

Or use the CLI shortcut:

contextmesh dashboard

Token Savings Report

$ contextmesh stats

╭─ ContextMesh Global Token Savings Report ─╮
│  Sessions tracked           │       12    │
│  Turns tracked              │      284    │
│  Total baseline tokens      │  2,847,000  │
│  Total routed tokens        │    391,000  │
│  Tokens saved               │  2,456,000  │
│  Net saved (after overhead) │  2,412,000  │
│  Avg compression ratio      │       14%   │
│  Estimated cost saved       │    $7.3680  │
╰────────────────────────────────────────────╯

MCP Tools available to Claude

Architecture

Memory Tiers

HOT   → Current task context (always in every request)
WARM  → Related decisions, nearby graph nodes (retrieved on demand)
COLD  → Full historical archive (never auto-injected, always searchable)

Context Scoring

Before every get_context() call, every node in the graph is scored:

score =
    semantic_relevance   (local embedding cosine similarity)
  + graph_proximity      (BFS distance — depth 1=1.0, depth 2=0.7, depth 3=0.4)
  + file_overlap         (Jaccard similarity with current task files)
  + recency              (exponential decay from last_active)
  + causal_relevance     (DECISION/BUG/SOLUTION type bonus)
  + unresolved_bonus     (UNRESOLVED_ISSUE always surfaces)

Dual Graph

Session Graph — captures every meaningful event:

• User prompts, tool results, file reads/writes
• Decisions, bugs, solutions, errors, test results
• Typed edges: caused_by, solved_by, depends_on, same_task

Repo Graph — deterministic code relationships (Tree-sitter):

• Functions, classes, methods across .py, .ts, .js, .go, .rs
• calls, imports, same_file, tested_by, inherits edges
• Auto-updated by the file watcher on every save

Configuration

~/.contextmesh/config.toml (global) or .contextmesh/config.toml (per project):

[router]
default_budget_tokens = 15000

[tracker]
input_price_per_mtok = 3.0        # Claude cached input price (USD per million)
uncached_price_per_mtok = 15.0

[embeddings]
model = "all-MiniLM-L6-v2"        # Local model, no API key needed (~22MB)

[tasks]
topic_shift_threshold = 0.35      # Cosine distance to auto-detect task switch

[proxy]
port = 8099

Supported Claude Auth Modes

ContextMesh auto-detects how you authenticate and behaves accordingly:

Development

git clone https://github.com/gajanansr/ContextMesh
cd ContextMesh
pip install -e ".[dev]"

License

MIT