claude-contextmesh 0.1.0__tar.gz

claude_contextmesh-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.contextmesh/
+

claude_contextmesh-0.1.0/CLAUDE.md

@@ -0,0 +1,18 @@
+# Project Context
+
+## ContextMesh Active
+
+This project uses ContextMesh for intelligent context management.
+
+**At the start of EVERY response**, call the `get_context` tool to load relevant context:
+
+```
+get_context(session_id="$CLAUDE_SESSION_ID", task_hint="<brief description of what you're about to do>", budget_tokens=15000)
+```
+
+When you make an important architectural decision or discover a key fact, call:
+```
+record_decision(session_id="$CLAUDE_SESSION_ID", content="<the decision>", consequence="<what it means>", files="<relevant files>")
+```
+
+Do NOT call get_context more than once per response. Do NOT explain that you're calling it.

claude_contextmesh-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gajanan Rathod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_contextmesh-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: claude-contextmesh
+Version: 0.1.0
+Summary: Intelligent context layer for Claude Code — infinite session memory, minimal active context
+Author: Gajanan Rathod
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: networkx>=3.4.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: python-dateutil>=2.9.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: scikit-learn>=1.5.0
+Requires-Dist: sentence-transformers>=3.3.0
+Requires-Dist: tiktoken>=0.8.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: tree-sitter-language-pack>=0.7.0
+Requires-Dist: tree-sitter>=0.23.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ContextMesh — Intelligent Context Layer for Claude Code
+
+> One coding session. Infinite memory. Minimal active context.
+
+ContextMesh sits between Claude Code and the model. It captures every event in your session, builds a structured knowledge graph of your work, and dynamically provides Claude with only the most relevant context for the current task — saving tokens, reducing cost, and preventing context overload.
+
+## How it works
+
+```
+Claude Code Hooks → ContextMesh Daemon → Session Graph + Repo Graph
+                                               ↓
+                              Context Router (multi-signal scoring)
+                                               ↓
+                              Claude Code ← MCP Server (get_context)
+                                               ↓
+                              Token Savings Tracker → Report
+```
+
+**The key insight**: semantic similarity alone fails for long coding sessions because everything related to the same feature looks similar. ContextMesh uses graph proximity + code dependency relationships + causal edges + recency + file overlap — not just vectors.
+
+## Installation
+
+```bash
+# Clone and install
+git clone https://github.com/you/ContextMesh
+cd ContextMesh
+pip install -e .
+
+# Run the install script (sets up hooks + config)
+bash scripts/install.sh
+
+# Index your project's codebase
+contextmesh index /path/to/your/project
+
+# Start the daemon
+contextmesh start
+
+# Start the MCP server (in a separate terminal)
+contextmesh mcp
+```
+
+### For exact token measurement (Claude Enterprise)
+
+```bash
+# Start the token proxy
+contextmesh proxy
+
+# Then set in your environment:
+export ANTHROPIC_BASE_URL=http://localhost:8099
+
+# This records EXACT token counts from actual API responses
+# including cache_creation_input_tokens and cache_read_input_tokens
+```
+
+## Adding ContextMesh to a project
+
+Copy `CLAUDE.md` from this repo to your project root. Claude Code will automatically instruct Claude to use the `get_context` tool at the start of each response.
+
+```bash
+cp /path/to/ContextMesh/CLAUDE.md /path/to/your/project/CLAUDE.md
+```
+
+## Register MCP server with Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "contextmesh": {
+      "command": "contextmesh",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+## View token savings
+
+```bash
+# Session summary
+contextmesh stats --session YOUR_SESSION_ID
+
+# Recent turns with savings breakdown
+contextmesh turns --session YOUR_SESSION_ID --limit 20
+
+# Global summary across all sessions
+contextmesh stats
+
+# If using proxy mode — actual API token counts
+contextmesh stats --proxy
+```
+
+## Token savings tracker
+
+Every time Claude calls `get_context()`, ContextMesh records:
+
+| Metric | What it is |
+|--------|-----------|
+| **Accumulated tokens** | What the full session history would have been |
+| **Routed tokens** | What ContextMesh actually provided |
+| **Tokens saved** | The difference |
+| **Compression ratio** | routed / accumulated |
+| **Cost saved** | Based on your configured per-MTok price |
+
+## Architecture
+
+### 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:
+- Functions, classes, methods, files (Tree-sitter parsed)
+- `calls`, `imports`, `same_file`, `tested_by`, `inherits` edges
+- Updated incrementally on every file write
+
+### Hot / Warm / Cold Memory
+
+```
+HOT   → Current task context (always injected)
+WARM  → Related tasks, decisions, nearby graph nodes (retrieved on demand)
+COLD  → Full historical transcripts (never auto-injected)
+```
+
+### Context Router
+
+Before every `get_context()` call:
+
+```
+context_score =
+    semantic_relevance   (embedding cosine similarity)
+  + graph_proximity      (BFS distance in session graph)
+  + file_overlap         (Jaccard similarity with current task files)
+  + recency              (exponential decay from now)
+  + causal_relevance     (DECISION/BUG/SOLUTION type bonus)
+  + unresolved_bonus     (UNRESOLVED_ISSUE always surfaces)
+```
+
+### Cache-aware assembly order
+
+```
+STATIC (cacheable)
+─────────────────────────────
+=== CURRENT TASK ===
+[hot nodes — current thread]
+
+=== RELEVANT DECISIONS ===
+[top-scored decisions]
+
+DYNAMIC
+─────────────────────────────
+=== RELATED CODE CONTEXT ===
+[repo graph: functions/classes in touched files]
+
+=== RECENT HISTORY ===
+[recent warm nodes]
+
+=== UNRESOLVED ISSUES ===
+[always surfaced]
+```
+
+## Configuration
+
+`.contextmesh/config.toml` in your project (or `~/.contextmesh/config.toml` globally):
+
+```toml
+[router]
+default_budget_tokens = 15000
+
+[tracker]
+input_price_per_mtok = 3.0       # Claude Enterprise cached input price
+uncached_price_per_mtok = 15.0
+
+[embeddings]
+model = "all-MiniLM-L6-v2"       # Local, no API key needed
+
+[tasks]
+topic_shift_threshold = 0.35     # Cosine distance to detect task switch
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+```

claude_contextmesh-0.1.0/README.md

@@ -0,0 +1,189 @@
+# ContextMesh — Intelligent Context Layer for Claude Code
+
+> One coding session. Infinite memory. Minimal active context.
+
+ContextMesh sits between Claude Code and the model. It captures every event in your session, builds a structured knowledge graph of your work, and dynamically provides Claude with only the most relevant context for the current task — saving tokens, reducing cost, and preventing context overload.
+
+## How it works
+
+```
+Claude Code Hooks → ContextMesh Daemon → Session Graph + Repo Graph
+                                               ↓
+                              Context Router (multi-signal scoring)
+                                               ↓
+                              Claude Code ← MCP Server (get_context)
+                                               ↓
+                              Token Savings Tracker → Report
+```
+
+**The key insight**: semantic similarity alone fails for long coding sessions because everything related to the same feature looks similar. ContextMesh uses graph proximity + code dependency relationships + causal edges + recency + file overlap — not just vectors.
+
+## Installation
+
+```bash
+# Clone and install
+git clone https://github.com/you/ContextMesh
+cd ContextMesh
+pip install -e .
+
+# Run the install script (sets up hooks + config)
+bash scripts/install.sh
+
+# Index your project's codebase
+contextmesh index /path/to/your/project
+
+# Start the daemon
+contextmesh start
+
+# Start the MCP server (in a separate terminal)
+contextmesh mcp
+```
+
+### For exact token measurement (Claude Enterprise)
+
+```bash
+# Start the token proxy
+contextmesh proxy
+
+# Then set in your environment:
+export ANTHROPIC_BASE_URL=http://localhost:8099
+
+# This records EXACT token counts from actual API responses
+# including cache_creation_input_tokens and cache_read_input_tokens
+```
+
+## Adding ContextMesh to a project
+
+Copy `CLAUDE.md` from this repo to your project root. Claude Code will automatically instruct Claude to use the `get_context` tool at the start of each response.
+
+```bash
+cp /path/to/ContextMesh/CLAUDE.md /path/to/your/project/CLAUDE.md
+```
+
+## Register MCP server with Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "contextmesh": {
+      "command": "contextmesh",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+## View token savings
+
+```bash
+# Session summary
+contextmesh stats --session YOUR_SESSION_ID
+
+# Recent turns with savings breakdown
+contextmesh turns --session YOUR_SESSION_ID --limit 20
+
+# Global summary across all sessions
+contextmesh stats
+
+# If using proxy mode — actual API token counts
+contextmesh stats --proxy
+```
+
+## Token savings tracker
+
+Every time Claude calls `get_context()`, ContextMesh records:
+
+| Metric | What it is |
+|--------|-----------|
+| **Accumulated tokens** | What the full session history would have been |
+| **Routed tokens** | What ContextMesh actually provided |
+| **Tokens saved** | The difference |
+| **Compression ratio** | routed / accumulated |
+| **Cost saved** | Based on your configured per-MTok price |
+
+## Architecture
+
+### 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:
+- Functions, classes, methods, files (Tree-sitter parsed)
+- `calls`, `imports`, `same_file`, `tested_by`, `inherits` edges
+- Updated incrementally on every file write
+
+### Hot / Warm / Cold Memory
+
+```
+HOT   → Current task context (always injected)
+WARM  → Related tasks, decisions, nearby graph nodes (retrieved on demand)
+COLD  → Full historical transcripts (never auto-injected)
+```
+
+### Context Router
+
+Before every `get_context()` call:
+
+```
+context_score =
+    semantic_relevance   (embedding cosine similarity)
+  + graph_proximity      (BFS distance in session graph)
+  + file_overlap         (Jaccard similarity with current task files)
+  + recency              (exponential decay from now)
+  + causal_relevance     (DECISION/BUG/SOLUTION type bonus)
+  + unresolved_bonus     (UNRESOLVED_ISSUE always surfaces)
+```
+
+### Cache-aware assembly order
+
+```
+STATIC (cacheable)
+─────────────────────────────
+=== CURRENT TASK ===
+[hot nodes — current thread]
+
+=== RELEVANT DECISIONS ===
+[top-scored decisions]
+
+DYNAMIC
+─────────────────────────────
+=== RELATED CODE CONTEXT ===
+[repo graph: functions/classes in touched files]
+
+=== RECENT HISTORY ===
+[recent warm nodes]
+
+=== UNRESOLVED ISSUES ===
+[always surfaced]
+```
+
+## Configuration
+
+`.contextmesh/config.toml` in your project (or `~/.contextmesh/config.toml` globally):
+
+```toml
+[router]
+default_budget_tokens = 15000
+
+[tracker]
+input_price_per_mtok = 3.0       # Claude Enterprise cached input price
+uncached_price_per_mtok = 15.0
+
+[embeddings]
+model = "all-MiniLM-L6-v2"       # Local, no API key needed
+
+[tasks]
+topic_shift_threshold = 0.35     # Cosine distance to detect task switch
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+```

claude_contextmesh-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "claude-contextmesh"
+version = "0.1.0"
+description = "Intelligent context layer for Claude Code — infinite session memory, minimal active context"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Gajanan Rathod" }]
+
+dependencies = [
+    # Web framework & async
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.32.0",
+    "httpx>=0.27.0",
+
+    # Async SQLite
+    "aiosqlite>=0.20.0",
+
+    # Graph
+    "networkx>=3.4.0",
+
+    # Code parsing (Tree-sitter)
+    "tree-sitter>=0.23.0",
+    "tree-sitter-language-pack>=0.7.0",
+
+    # Embeddings (local, no external API)
+    "sentence-transformers>=3.3.0",
+    "numpy>=1.26.0",
+
+    # Token counting
+    "tiktoken>=0.8.0",
+
+    # MCP server
+    "fastmcp>=2.0.0",
+
+    # Data models
+    "pydantic>=2.9.0",
+
+    # Config
+    "tomli>=2.0.0; python_version < '3.11'",
+    "tomli-w>=1.0.0",
+
+    # CLI & display
+    "rich>=13.9.0",
+    "click>=8.1.0",
+
+    # Utilities
+    "scikit-learn>=1.5.0",
+    "python-dateutil>=2.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.7.0",
+    "mypy>=1.13.0",
+]
+
+[project.scripts]
+contextmesh = "contextmesh.cli:main"
+claude-mesh = "contextmesh.wrapper:main"
+
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/contextmesh"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

claude_contextmesh-0.1.0/scripts/hook_event.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# ContextMesh hook relay script
+# Called by Claude Code hooks. Reads JSON payload from stdin, POSTs to daemon.
+# Usage: echo '{...}' | CONTEXTMESH_EVENT_TYPE=PostToolUse ./scripts/hook_event.sh
+
+set -euo pipefail
+
+DAEMON_URL="${CONTEXTMESH_DAEMON_URL:-http://127.0.0.1:8765}"
+EVENT_TYPE="${CONTEXTMESH_EVENT_TYPE:-Unknown}"
+SESSION_ID="${CLAUDE_SESSION_ID:-unknown}"
+PROJECT_PATH="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# Read the hook payload from stdin
+PAYLOAD=$(cat)
+
+# Merge with our envelope fields
+FULL_PAYLOAD=$(jq -n \
+  --arg event_type "$EVENT_TYPE" \
+  --arg session_id "$SESSION_ID" \
+  --arg project_path "$PROJECT_PATH" \
+  --argjson payload "$PAYLOAD" \
+  '($payload) + {event_type: $event_type, session_id: $session_id, project_path: $project_path}'
+)
+
+# Fire and forget — don't block Claude Code
+curl -s -f -X POST \
+  "${DAEMON_URL}/hook" \
+  -H 'Content-Type: application/json' \
+  -d "$FULL_PAYLOAD" \
+  --max-time 2 \
+  > /dev/null 2>&1 &
+
+# Always exit 0 — never block Claude Code
+exit 0

claude_contextmesh-0.1.0/scripts/install.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+CONTEXTMESH_DIR="${HOME}/.contextmesh"
+VENV_DIR="${CONTEXTMESH_DIR}/venv"
+SETTINGS_FILE="${HOME}/.claude/settings.json"
+CONFIG_FILE="${CONTEXTMESH_DIR}/config.toml"
+
+echo "Creating ContextMesh environment..."
+mkdir -p "$CONTEXTMESH_DIR"
+python3 -m venv "$VENV_DIR"
+
+echo "Installing contextmesh package..."
+"$VENV_DIR/bin/pip" install -e .
+
+echo "Setting up ContextMesh config..."
+if [ ! -f "$CONFIG_FILE" ]; then
+cat << 'EOF' > "$CONFIG_FILE"
+[daemon]
+port = 8765
+host = "127.0.0.1"
+
+[router]
+default_budget_tokens = 15000
+hot_budget_fraction = 0.20
+warm_budget_fraction = 0.50
+code_budget_fraction = 0.30
+
+[embeddings]
+model = "all-MiniLM-L6-v2"
+
+[tasks]
+topic_shift_threshold = 0.35
+min_turns_per_task = 3
+
+[tracker]
+input_price_per_mtok = 3.0
+uncached_price_per_mtok = 15.0
+
+[mcp]
+server_name = "contextmesh"
+
+[proxy]
+enabled = false
+port = 8099
+upstream = "https://api.anthropic.com"
+EOF
+fi
+
+echo "Setting up Claude Code hooks..."
+mkdir -p "$(dirname "$SETTINGS_FILE")"
+
+HOOK_SCRIPT="$(pwd)/scripts/hook_event.sh"
+chmod +x "$HOOK_SCRIPT"
+
+# We use a python script to merge the hooks section safely
+"$VENV_DIR/bin/python" - <<EOF
+import json
+import os
+
+settings_path = "$SETTINGS_FILE"
+hook_script = "$HOOK_SCRIPT"
+
+if os.path.exists(settings_path):
+    with open(settings_path, "r") as f:
+        try:
+            settings = json.load(f)
+        except json.JSONDecodeError:
+            settings = {}
+else:
+    settings = {}
+
+if "hooks" not in settings:
+    settings["hooks"] = {}
+
+hooks = settings["hooks"]
+
+events = ["UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop"]
+for event in events:
+    if event not in hooks:
+        hooks[event] = []
+    
+    # Check if our hook is already there
+    cmd = f"CONTEXTMESH_EVENT_TYPE={event} CLAUDE_SESSION_ID=\\$CLAUDE_SESSION_ID CLAUDE_PROJECT_DIR=\\$CLAUDE_PROJECT_DIR {hook_script}"
+    
+    exists = False
+    for item in hooks[event]:
+        if "hooks" in item:
+            for h in item["hooks"]:
+                if h.get("type") == "command" and h.get("command") == cmd:
+                    exists = True
+                    break
+    
+    if not exists:
+        hooks[event].append({
+            "hooks": [{
+                "type": "command",
+                "command": cmd
+            }]
+        })
+
+with open(settings_path, "w") as f:
+    json.dump(settings, f, indent=2)
+
+EOF
+
+echo "Installation complete!"
+echo "To start the daemon, run:"
+echo "$VENV_DIR/bin/uvicorn contextmesh.daemon.server:create_app --host 127.0.0.1 --port 8765"

claude_contextmesh-0.1.0/src/contextmesh/__init__.py

@@ -0,0 +1,4 @@
+"""ContextMesh — Intelligent context layer for Claude Code."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]