sharp-context 0.1.0__tar.gz

sharp_context-0.1.0/.gitignore

@@ -0,0 +1,75 @@
+# Node/JS
+node_modules/
+npm-debug.log*
+.next/
+web/.next/
+
+# Editor
+.vscode/
+.idea/
+
+# Python
+__pycache__/
+.venv/
+*.pyc
+.env
+
+# Rust / Cargo
+target/
+Cargo.lock
+
+# Data / Temp
+*.log
+.DS_Store
+
+# Model caches / generated
+.fastembed_cache/
+server/.fastembed_cache/
+*.onnx
+*.lock
+
+# Environment secrets (never commit)
+web/.env.local
+web/.env.production
+.env.local
+
+# =========================================================
+# ALLOWLIST — only these directories are tracked
+# =========================================================
+
+# Core engine (Rust)
+# openrustswarm-core/ — tracked
+
+# Web dashboard (Next.js)
+# web/ — tracked
+
+# CogOps Skill (OpenClaw integration)
+# cogops-skill/ — tracked
+
+# WASM bridge
+# cogops-wasm/ — tracked
+
+# Python server
+# server/ — tracked
+
+# Public assets
+# demo/, examples/, dist/ — tracked
+
+# =========================================================
+# EXCLUDED (internal / generated / one-off)
+# =========================================================
+openrustswarm/
+benchmarks/
+scripts/
+docs/
+hacker_news_launch.md
+eval_*.py
+test_*.py
+medieval_demo.py
+real_10k_log_swarm.py
+CODEBASE_AUDIT.md
+LAUNCH.md
+*.jsonl
+server/diagnose_api.py
+server/verify_ui.py
+server/run_task_help.txt

sharp_context-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: sharp-context
+Version: 0.1.0
+Summary: Information-theoretic context optimization for AI coding agents. Knapsack-optimal token budgeting, Shannon entropy scoring, SimHash dedup, predictive pre-fetch. MCP server.
+Project-URL: Homepage, https://github.com/juyterman1000/sharp-context
+Project-URL: Documentation, https://github.com/juyterman1000/sharp-context#readme
+Project-URL: Repository, https://github.com/juyterman1000/sharp-context
+Project-URL: Bug Tracker, https://github.com/juyterman1000/sharp-context/issues
+Project-URL: Full Framework, https://github.com/juyterman1000/ebbiforge
+Author-email: Ebbiforge Team <fastrunner10090@gmail.com>
+License: MIT
+Keywords: agentic-ai,checkpoint,claude,context-optimization,copilot,cursor,deduplication,entropy,knapsack,llm,mcp,token-cost
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: memory
+Requires-Dist: hippocampus-sharp-memory>=1.0.0; extra == 'memory'
+Description-Content-Type: text/markdown
+
+# SharpContext
+
+**Information-theoretic context optimization for AI coding agents.**
+
+Every AI coding tool manages context with dumb FIFO truncation — stuffing tokens until the window is full, then cutting from the top. SharpContext applies mathematics to select the **optimal** context subset.
+
+```
+pip install sharp-context
+```
+
+## What It Does
+
+An MCP server that sits between your AI coding tool and the LLM, providing:
+
+| Engine | What it does | How it works |
+|--------|-------------|--------------|
+| 🎒 **Knapsack Optimizer** | Selects mathematically optimal context subset | 0/1 Knapsack DP — maximizes relevance within token budget |
+| 📊 **Entropy Scorer** | Measures information density per fragment | Shannon entropy + token surprisal + boilerplate detection |
+| 🔍 **SimHash Dedup** | Catches near-duplicate content in O(1) | 64-bit SimHash with LSH banding (Proximity 2026) |
+| 🔮 **Predictive Pre-fetch** | Pre-loads context before the agent asks | Static analysis + learned co-access patterns |
+| 💾 **Checkpoint & Resume** | Crash recovery for multi-step tasks | Gzipped JSON state serialization |
+
+## Setup
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sharp-context": {
+      "command": "sharp-context"
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add sharp-context -- sharp-context
+```
+
+### Cline / Any MCP Client
+
+```json
+{
+  "sharp-context": {
+    "command": "sharp-context",
+    "args": []
+  }
+}
+```
+
+## MCP Tools
+
+### `remember_fragment`
+Store context with auto-dedup and entropy scoring.
+
+```
+remember_fragment(content="def process_payment(...)...", source="file:payments.py")
+→ {"status": "ingested", "entropy_score": 0.82}
+
+remember_fragment(content="def process_payment(...)...")  # same content
+→ {"status": "duplicate", "duplicate_of": "a1b2c3", "tokens_saved": 45}
+```
+
+### `optimize_context`
+Select the optimal context subset for a token budget.
+
+```
+optimize_context(token_budget=128000, query="fix payment bug")
+→ {
+    "selected_fragments": [...],
+    "optimization_stats": {"method": "exact_dp", "budget_utilization": 0.73},
+    "tokens_saved_this_call": 42000
+  }
+```
+
+### `recall_relevant`
+Semantic recall of stored fragments.
+
+```
+recall_relevant(query="database connection pooling", top_k=5)
+→ [{"fragment_id": "...", "relevance": 0.87, "content": "..."}]
+```
+
+### `checkpoint_state` / `resume_state`
+Save and restore full session state.
+
+```
+checkpoint_state(task_description="Refactoring auth module", current_step="Step 5/8")
+→ {"status": "checkpoint_saved", "fragments_saved": 47}
+
+resume_state()
+→ {"status": "resumed", "restored_fragments": 47, "metadata": {"step": "Step 5/8"}}
+```
+
+### `prefetch_related`
+Predict and pre-load likely-needed context.
+
+```
+prefetch_related(file_path="src/payments.py", source_content="from utils import...")
+→ [{"path": "src/utils.py", "reason": "import", "confidence": 0.70}]
+```
+
+### `get_stats`
+Session statistics and cost savings.
+
+```
+get_stats()
+→ {
+    "savings": {
+      "total_tokens_saved": 284000,
+      "total_duplicates_caught": 12,
+      "estimated_cost_saved_usd": 0.85
+    }
+  }
+```
+
+## The Math
+
+### Knapsack Context Selection
+
+Context selection is the 0/1 Knapsack Problem:
+
+```
+Maximize:   Σ r(fᵢ) · x(fᵢ)     for selected fragments
+Subject to: Σ c(fᵢ) · x(fᵢ) ≤ B  (token budget)
+```
+
+Where relevance `r(f)` is a weighted combination of:
+- **Recency** (Ebbinghaus forgetting curve decay)
+- **Frequency** (spaced repetition boost)
+- **Semantic similarity** (SimHash Hamming distance)
+- **Information density** (Shannon entropy)
+
+Solved via DP with budget quantization: O(N × 1000) instead of O(N × B).
+
+### Shannon Entropy Scoring
+
+```
+H(fragment) = -Σ p(char) · log₂(p(char))
+```
+
+High entropy = unique, surprising content (prioritize).
+Low entropy = boilerplate, repetitive patterns (deprioritize).
+
+### SimHash Deduplication
+
+64-bit fingerprints with 4-band LSH bucketing:
+- Hamming distance ≤ 3 → near-duplicate (99% recall)
+- Hamming distance ≥ 10 → genuinely different (<1% false positive)
+
+## References
+
+- Shannon (1948) — Information Theory
+- Charikar (2002) — SimHash
+- Ebbinghaus (1885) — Forgetting Curve
+- ICPC (arXiv 2025) — In-context Prompt Compression
+- Proximity (arXiv 2026) — LSH-bucketed Semantic Caching
+- RCC (ICLR 2025) — Recurrent Context Compression
+- ILRe (ICLR 2026) — Intermediate Layer Retrieval
+- Agentic Plan Caching (arXiv 2025)
+
+## Part of the Ebbiforge Ecosystem
+
+SharpContext uses techniques from the [hippocampus-sharp-memory](https://pypi.org/project/hippocampus-sharp-memory/) engine and the [Ebbiforge](https://pypi.org/project/ebbiforge/) Rust core.
+
+## License
+
+MIT

sharp_context-0.1.0/README.md

@@ -0,0 +1,173 @@
+# SharpContext
+
+**Information-theoretic context optimization for AI coding agents.**
+
+Every AI coding tool manages context with dumb FIFO truncation — stuffing tokens until the window is full, then cutting from the top. SharpContext applies mathematics to select the **optimal** context subset.
+
+```
+pip install sharp-context
+```
+
+## What It Does
+
+An MCP server that sits between your AI coding tool and the LLM, providing:
+
+| Engine | What it does | How it works |
+|--------|-------------|--------------|
+| 🎒 **Knapsack Optimizer** | Selects mathematically optimal context subset | 0/1 Knapsack DP — maximizes relevance within token budget |
+| 📊 **Entropy Scorer** | Measures information density per fragment | Shannon entropy + token surprisal + boilerplate detection |
+| 🔍 **SimHash Dedup** | Catches near-duplicate content in O(1) | 64-bit SimHash with LSH banding (Proximity 2026) |
+| 🔮 **Predictive Pre-fetch** | Pre-loads context before the agent asks | Static analysis + learned co-access patterns |
+| 💾 **Checkpoint & Resume** | Crash recovery for multi-step tasks | Gzipped JSON state serialization |
+
+## Setup
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sharp-context": {
+      "command": "sharp-context"
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add sharp-context -- sharp-context
+```
+
+### Cline / Any MCP Client
+
+```json
+{
+  "sharp-context": {
+    "command": "sharp-context",
+    "args": []
+  }
+}
+```
+
+## MCP Tools
+
+### `remember_fragment`
+Store context with auto-dedup and entropy scoring.
+
+```
+remember_fragment(content="def process_payment(...)...", source="file:payments.py")
+→ {"status": "ingested", "entropy_score": 0.82}
+
+remember_fragment(content="def process_payment(...)...")  # same content
+→ {"status": "duplicate", "duplicate_of": "a1b2c3", "tokens_saved": 45}
+```
+
+### `optimize_context`
+Select the optimal context subset for a token budget.
+
+```
+optimize_context(token_budget=128000, query="fix payment bug")
+→ {
+    "selected_fragments": [...],
+    "optimization_stats": {"method": "exact_dp", "budget_utilization": 0.73},
+    "tokens_saved_this_call": 42000
+  }
+```
+
+### `recall_relevant`
+Semantic recall of stored fragments.
+
+```
+recall_relevant(query="database connection pooling", top_k=5)
+→ [{"fragment_id": "...", "relevance": 0.87, "content": "..."}]
+```
+
+### `checkpoint_state` / `resume_state`
+Save and restore full session state.
+
+```
+checkpoint_state(task_description="Refactoring auth module", current_step="Step 5/8")
+→ {"status": "checkpoint_saved", "fragments_saved": 47}
+
+resume_state()
+→ {"status": "resumed", "restored_fragments": 47, "metadata": {"step": "Step 5/8"}}
+```
+
+### `prefetch_related`
+Predict and pre-load likely-needed context.
+
+```
+prefetch_related(file_path="src/payments.py", source_content="from utils import...")
+→ [{"path": "src/utils.py", "reason": "import", "confidence": 0.70}]
+```
+
+### `get_stats`
+Session statistics and cost savings.
+
+```
+get_stats()
+→ {
+    "savings": {
+      "total_tokens_saved": 284000,
+      "total_duplicates_caught": 12,
+      "estimated_cost_saved_usd": 0.85
+    }
+  }
+```
+
+## The Math
+
+### Knapsack Context Selection
+
+Context selection is the 0/1 Knapsack Problem:
+
+```
+Maximize:   Σ r(fᵢ) · x(fᵢ)     for selected fragments
+Subject to: Σ c(fᵢ) · x(fᵢ) ≤ B  (token budget)
+```
+
+Where relevance `r(f)` is a weighted combination of:
+- **Recency** (Ebbinghaus forgetting curve decay)
+- **Frequency** (spaced repetition boost)
+- **Semantic similarity** (SimHash Hamming distance)
+- **Information density** (Shannon entropy)
+
+Solved via DP with budget quantization: O(N × 1000) instead of O(N × B).
+
+### Shannon Entropy Scoring
+
+```
+H(fragment) = -Σ p(char) · log₂(p(char))
+```
+
+High entropy = unique, surprising content (prioritize).
+Low entropy = boilerplate, repetitive patterns (deprioritize).
+
+### SimHash Deduplication
+
+64-bit fingerprints with 4-band LSH bucketing:
+- Hamming distance ≤ 3 → near-duplicate (99% recall)
+- Hamming distance ≥ 10 → genuinely different (<1% false positive)
+
+## References
+
+- Shannon (1948) — Information Theory
+- Charikar (2002) — SimHash
+- Ebbinghaus (1885) — Forgetting Curve
+- ICPC (arXiv 2025) — In-context Prompt Compression
+- Proximity (arXiv 2026) — LSH-bucketed Semantic Caching
+- RCC (ICLR 2025) — Recurrent Context Compression
+- ILRe (ICLR 2026) — Intermediate Layer Retrieval
+- Agentic Plan Caching (arXiv 2025)
+
+## Part of the Ebbiforge Ecosystem
+
+SharpContext uses techniques from the [hippocampus-sharp-memory](https://pypi.org/project/hippocampus-sharp-memory/) engine and the [Ebbiforge](https://pypi.org/project/ebbiforge/) Rust core.
+
+## License
+
+MIT

sharp_context-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sharp-context"
+version = "0.1.0"
+description = "Information-theoretic context optimization for AI coding agents. Knapsack-optimal token budgeting, Shannon entropy scoring, SimHash dedup, predictive pre-fetch. MCP server."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Ebbiforge Team", email = "fastrunner10090@gmail.com" },
+]
+keywords = [
+    "mcp", "context-optimization", "token-cost", "agentic-ai",
+    "knapsack", "entropy", "deduplication", "checkpoint",
+    "cursor", "claude", "copilot", "llm",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=1.0.0",
+]
+
+[project.optional-dependencies]
+memory = ["hippocampus-sharp-memory>=1.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/juyterman1000/sharp-context"
+Documentation = "https://github.com/juyterman1000/sharp-context#readme"
+Repository = "https://github.com/juyterman1000/sharp-context"
+"Bug Tracker" = "https://github.com/juyterman1000/sharp-context/issues"
+"Full Framework" = "https://github.com/juyterman1000/ebbiforge"
+
+[project.scripts]
+sharp-context = "sharp_context.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sharp_context"]

sharp_context-0.1.0/sharp_context/__init__.py

@@ -0,0 +1,27 @@
+"""
+SharpContext — Information-Theoretic Context Optimization for Agentic AI
+========================================================================
+
+An MCP server that mathematically optimizes what goes into an LLM's
+context window. Uses knapsack dynamic programming, Shannon entropy scoring,
+SimHash deduplication, and predictive pre-fetching to cut token costs by
+50–70% while improving agent accuracy.
+
+Quick Setup (Cursor)::
+
+    Add to .cursor/mcp.json:
+    {
+      "mcpServers": {
+        "sharp-context": {
+          "command": "sharp-context"
+        }
+      }
+    }
+
+Quick Setup (Claude Code)::
+
+    claude mcp add sharp-context -- sharp-context
+
+"""
+
+__version__ = "0.1.0"