Knowledge & Memory Python ★ 45,699

chopratejas/headroom

AI ajanlar için bağlam sıkıştırma katmanı. Tool çıktılarını, logları, RAG chunk'larını, dosyaları ve konuşma geçmişini LLM'ye ulaşmadan önce sıkıştırır ve MCP tool'ları aracılığıyla geri alınabilir şekilde depolar.

Claude Desktop config.json'a ekle

{
  "mcpServers": {
    "chopratejas-headroom": {
      "command": "python",
      "args": [
        "-m",
        "headroom"
      ]
    }
  }
}

Bu MCP sunucusu hakkında

  ██╗  ██╗███████╗ █████╗ ██████╗ ██████╗  ██████╗  ██████╗ ███╗   ███╗
  ██║  ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║
  ███████║█████╗  ███████║██║  ██║██████╔╝██║   ██║██║   ██║██╔████╔██║
  ██╔══██║██╔══╝  ██╔══██║██║  ██║██╔══██╗██║   ██║██║   ██║██║╚██╔╝██║
  ██║  ██║███████╗██║  ██║██████╔╝██║  ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║
  ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚═╝     ╚═╝
                  AI ajanları için bağlam sıkıştırma katmanı

60–95% daha az token · library · proxy · MCP · 6 algoritma · yerel-öncelikli · tersine çevrilebilir

Dokümanlar · Kurulum · Kanıt · Ajanlar · Discord · llms.txt · Kurumsal

AI ajanları / LLM'ler: /llms.txt dosyasını okuyun ya da canlı indeksi / tam doküman blobunu getirin.

Headroom, AI ajanınızın okuduğu her şeyi — tool çıktılarını, logları, RAG parçalarını, dosyaları ve konuşma geçmişini — LLM'e ulaşmadan önce sıkıştırır. Aynı cevaplar, çok daha az token.


Canlı: 10.144 → 1.260 token — aynı FATAL bulundu.

Ne yapar

  • Library — Python veya TypeScript'te compress(messages), herhangi bir uygulamaya inline yerleştir
  • Proxy — headroom proxy --port 8787, sıfır kod değişikliği, herhangi bir dil
  • Agent wrap — headroom wrap claude|codex|cursor|aider|copilot tek komutla
  • MCP server — headroom_compress, headroom_retrieve, headroom_stats herhangi bir MCP istemcisi için
  • Cross-agent memory — Claude, Codex, Gemini arasında paylaşılan depo, otomatik dedup
  • headroom learn — başarısız oturumları inceler, CLAUDE.md / AGENTS.md dosyasına düzeltmeler yazar
  • Tersine çevrilebilir (CCR) — orijinalleri istendiğinde retrieval için önbelleğe alır

Nasıl çalışır (30 saniye)

 Ajanınız / uygulamanız
   (Claude Code, Cursor, Codex, LangChain, Agno, Strands, kendi kodunuz…)
        │   promptlar · tool çıktıları · loglar · RAG sonuçları · dosyalar
        ▼
    ┌────────────────────────────────────────────────────┐
    │  Headroom   (yerel olarak çalışır — veriniz burada kalır)  │
    │  ────────────────────────────────────────────────  │
    │  CacheAligner  →  ContentRouter  →  CCR            │
    │                    ├─ SmartCrusher   (JSON)        │
    │                    ├─ CodeCompressor (AST)         │
    │                    └─ Kompress-base  (metin, HF)   │
    │                                                    │
    │  Cross-agent memory  ·  headroom learn  ·  MCP     │
    └────────────────────────────────────────────────────┘
        │   sıkıştırılmış prompt  +  retrieval tool
        ▼
 LLM sağlayıcısı  (Anthropic · OpenAI · Bedrock · …)
  • ContentRouter — içerik türünü algılar, doğru compressor'ı seçer
  • SmartCrusher / CodeCompressor / Kompress-base — JSON, AST veya metin sıkıştırır
  • CacheAligner — prefixleri stabilize eder böylece sağlayıcı KV cache'leri gerçekten hit eder
  • CCR — orijinalleri yerel olarak saklar; LLM'e ihtiyacı varsa headroom_retrieve çağırır

→ Mimari · CCR tersine çevrilebilir sıkıştırma · Kompress-v2-base model kartı

Başlayın (60 saniye)

# 1 — Kurun
pip install "headroom-ai[all]"          # Python
npm install headroom-ai                 # Node / TypeScript

# 2 — Modunuzu seçin
headroom wrap claude                    # bir coding ajanını wrap et
headroom proxy --port 8787              # drop-in proxy, sıfır kod değişikliği
# veya: from headroom import compress   # inline library

# 3 — Tasarruflara bakın
headroom perf

Detaylı ekstralar: [proxy], [mcp], [ml], [code], [memory], [relevance], [image], [agno], [langchain], [evals], [pytorch-mps] (Apple-GPU hafıza-embedder offload — HEADROOM_EMBEDDER_RUNTIME=pytorch_mps ayarla). Python 3.10+ gerektirir.

Kanıt

Gerçek agent iş yükleri üzerine tasarruflar:

İş yükü Önce Sonra Tasarruf
Kod arama (100 sonuç) 17.765 1.408 92%
SRE olay hata ayıklaması 65.694 5.118 92%
GitHub issue sınıflandırması 54.174 14.761 73%
Kod tabanı keşfi 78.502 41.254 47%

Standart benchmark'lerde doğruluk korunur:

Benchmark Kategori N Başlangıç Headroom Delta
GSM8K Matematik 100 0.870 0.870 ±0.000
TruthfulQA Faktsal 100 0.530 0.560 +0.030
SQuAD v2 QA 100 — 97% 19% sıkıştırma
BFCL Araçlar 100 — 97% 32% sıkıştırma

Çoğalt: python -m headroom.evals suite --tier 1 · Tam benchmark'ler & metodoloji

Agent uyumluluğu matrisi

Ajan headroom wrap Notlar
Claude Code ✅ --memory · --code-graph
Codex ✅ Claude ile hafıza paylaşır
Cursor ✅ yapılandırmayı yazdırır — bir kez yapıştır
Aider ✅ proxy başlatır + başlatır
Copilot CLI ✅ proxy başlatır + başlatır
OpenClaw ✅ ContextEngine plugin olarak yükler

Herhangi bir OpenAI-uyumlu istemci headroom proxy aracılığıyla çalışır. MCP-native: headroom mcp install.

GitHub Copilot CLI abonelik modu

Headroom, GitHub Copilot CLI abonelik trafiğini yerel proxy aracılığıyla yönlendirebilir:

headroom copilot-auth login
headroom wrap copilot --subscription -- --model gpt-4o

Bu, Headroom'un OpenAI-uyumlu Copilot CLI isteklerini kesmesine ve GitHub Copilot'un barındırılan API'sine iletmeden önce aynı proxy sıkıştırma boru hattını uygulamasına izin verir. Wrapper, Headroom'un yeniden kullanılabilir GitHub OAuth token'ını Copilot'un kısa ömürlü API token'ı ile değiştirir ve başlatma sırasında upstream endpoint'i COPILOT_PROVIDER_API_URL=... olarak yazdırır.

headroom copilot-auth login, Headroom'a özgü bir Copilot OAuth token'ı depolar. Bu, Copilot hesap metadatasını okuyabilen ancak yine de Copilot'un token-exchange endpoint'i tarafından reddedebilecek genel GitHub veya Copilot CLI token'larına güvenmeyi önler.

GitHub Enterprise Server veya özel-domain Copilot dağıtımları için, başlatmadan önce dağıtım etki alanını ayarlayın:

export GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com

github.com/enterprises/your-enterprise gibi GitHub.com Enterprise Cloud URL'leri için, bir enterprise-domain geçersiz kılması ayarlamayın. Headroom, GitHub'ın normal token-exchange endpoint'ini ve oturum açan hesap için advertised Copilot API endpoint'ini kullanır.

Platform destek notu: macOS auth yeniden kullanımı Copilot CLI Keychain depolama aracılığıyla smoke-test edilmiştir. Windows Credential Manager, Linux Secret Service / secret-tool ve Docker/CI token-injection yolları auth-discovery yolları olarak uygulanmış veya planlanmıştır, ancak tam olarak onaylanmış kabul edilmeden önce gerçek OS doğrulamasına ihtiyaç duyarlar. Docker ve CI için, host keychain erişimine güvenmek yerine açık bir GITHUB_COPILOT_TOKEN veya GITHUB_COPILOT_GITHUB_TOKEN geçmeyi tercih edin.

Ne zaman kullanılır · Ne zaman atlanır

Eğer şunları yapıyorsanız harika bir seçim…

  • her gün AI coding ajanları çalıştırıyor ve kodunuzu değiştirmeden tasarruf istiyorsunuz
  • birden fazla ajan arasında çalışıyor ve paylaşılan hafıza istiyorsunuz
  • tersine çevrilebilir sıkıştırmaya ihtiyacınız var — orijinalleri yapılandırılmış TTL içinde CCR aracılığıyla alabilirsiniz

Atlayın eğer…

  • sadece tek bir sağlayıcının yerel sıkıştırmasını kullanıyor ve cross-agent hafızaya ihtiyacınız yoksa
  • yerel işlemlerin çalışamadığı sandboxed bir ortamda çalışıyorsanız
İntegrasyonlar — Headroom'u herhangi bir stack'e yerleştir
Kurulumunuz Bağlanın
Herhangi bir Python app compress(messages, model=…)
Herhangi bir TypeScript app await compress(messages, { model })
Anthropic / OpenAI SDK withHeadroom(new Anthropic()) · withHeadroom(new OpenAI())
Vercel AI SDK wrapLanguageModel({ model, middleware: headroomMiddleware() })
LiteLLM litellm.callbacks = [HeadroomCallback()]
LangChain HeadroomChatModel(your_llm)
Agno HeadroomAgnoModel(your_model)
Strands Strands rehberi
ASGI apps app.add_middleware(CompressionMiddleware)
Multi-agent SharedContext().put / .get
MCP clients headroom mcp install
İçinde neler var
  • SmartCrusher — evrensel JSON: dicts dizileri, iç içe nesneler, karışık türler.
  • CodeCompressor — Python, JS, Go, Rust, Java, C++ için AST-farkındır.
  • Kompress-base — HuggingFace modelimiz, agentic izleri üzerinde eğitildi.
  • Görüntü sıkıştırması — eğitilmiş ML router aracılığıyla 40–90% indirim.
  • CacheAligner — prefixleri stabilize eder böylece Anthropic/OpenAI KV cache'leri hit eder.
  • IntelligentContext — öğrenilen önem ile puan tabanlı bağlam uydurmak.
  • CCR — tersine çevrilebilir sıkıştırma; LLM talep halinde orijinalleri alır.
  • Cross-agent memory — paylaşılan depo, agent provenance, otomatik dedup.
  • SharedContext — multi-agent iş akışları arasında sıkıştırılmış bağlam geçişi.
  • headroom learn — Claude, Codex, Gemini için plugin-tabanlı başarısızlık madenciliği.
Pipeline iç işleyişi

Headroom, compress(), SDK ve proxy arasında bir sabit request yaşam döngüsü ortaya koyar:

Setup → Pre-Start → Post-Start → Input Received → Input Cached → Input Routed → Input Compressed → Input Remembered → Pre-Send → Post-Send → Response Received

  • Transforms işi yapar: CacheAligner, ContentRouter, SmartCrusher, CodeCompressor, Kompress-base, IntelligentContext / RollingWindow.
  • Pipeline extensions yaşam döngüsü aşamalarını gözlemler veya özelleştirir on_pipeline_event(...) aracılığıyla.
  • Compression hooks kanonik yaşam döngüsünün yanında ek bir extension dikiş olarak oturur.
  • Proxy extensions ASGI middleware, rotalar ve başlangıç politikası için sunucu/uygulama integrasyon dikiş olarak kalır.

Sağlayıcı ve tool-specific davranış headroom/providers/ altında yaşar böylece core orchestration yaşam döngüsü, sıralama ve politika üzerine odaklanır.

  • CLI/tool slices: headroom/providers/claude, copilot, codex, openclaw
  • Provider runtime slices: headroom/providers/claude, gemini, artı headroom/providers/registry.py içinde paylaşılan backend/runtime dispatch
  • Core dosyalar orchestration-first kalır: wrap.py, client.py, cli/proxy.py ve proxy/server.py sağlayıcı-spesifik env şekillendirme, API hedef normalizasyonu, backend seçimi ve transport dispatch'e devret.

Kurulum

pip install "headroom-ai[all]"          # Python, her şey
npm install headroom-ai                 # TypeScript / Node
docker pull ghcr.io/chopratejas/headroom:latest

Detaylı ekstralar: [proxy], [mcp], [ml] (Kompress-base), [code], [memory], [relevance], [image], [agno], [langchain], [evals], [pytorch-mps] (Apple-GPU hafıza-embedder offload — HEADROOM_EMBEDDER_RUNTIME=pytorch_mps ayarla). Python 3.10+ gerektirir.

pipx kullanıyor musunuz? Desteklenen bir yorumlamacıyı açıkça seçin:

pipx install --python python3.13 "headroom-ai[all]"

→ Kurulum rehberi — Docker etiketleri, kalıcı hizmet, PowerShell, devcontainers.

Kurumsal / SSL-inceleme ortamları

pip install "headroom-ai[all]" CERTIFICATE_VERIFY_FAILED ile başarısız olursa (unable to get local issuer certificate), ağınız SSL incelemesi kullanıyor — bir şirket tarafından verilen CA sunan MITM proxy'si. Build backend'i (maturin) rustup'ı TLS stack'inizin güvenmediği bir bağlantı üzerinden indirir. Rust'ı önce kurun böylece build onu getirmez:

# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && rustup default stable
# Windows
winget install Rustlang.Rustup && rustup default stable

Shell'inizi yeniden başlatın, sonra pip install "headroom-ai[all]". Önceden derlenmiş bir wheel, mevcut olduğu yerlerde Rust build'ini tamamen önler: pip install --only-binary headroom-ai headroom-ai.

İki runtime asset'i TLS üzerinden alınır; bloke edilerlerse, kurumsal CA'nız aracılığıyla güvenin REQUESTS_CA_BUNDLE / SSL_CERT_FILE / CURL_CA_BUNDLE:

  • cdn.pyke.io — Rust core'u için ONNX Runtime'ı. Alternatif olarak onu ORT_STRATEGY=system ve ORT_LIB_LOCATION=/path/to/onnxruntime ile önceden sağlayın.
  • huggingface.co — kompress-base sıkıştırma modeli. Önceden indirin ve HF_HUB_OFFLINE=1 ile çalıştırın, veya HF_ENDPOINT'i güvenilir bir aynaya ayarlayın.

Sıkıştırma devre dışı bırakılarak çalıştırma (saf gateway) hiçbir asset gerektiremez.

headroom learn

headroom learn — başarısız oturumları inceler, CLAUDE.md / AGENTS.md / GEMINI.md dosyasına düzeltmeler yazar.

Dokümanlar

Buradan başlayın Daha derin
Hızlı başlangıç Mimari
Proxy Sıkıştırma nasıl çalışır
MCP araçları CCR — tersine çevrilebilir sıkıştırma
Hafıza Cache optimizasyonu
Başarısızlık öğrenmesi Benchmark'ler
Yapılandırma Sınırlamalar

Karşılaştırma

Headroom yerel olarak çalışır, her içerik türünü kapsar, her büyük framework ile çalışır ve tersine çevrilebilir.

Kapsam Dağıtım Yerel Tersine Çevrilebilir
Headroom Tüm bağlam — araçlar, RAG, loglar, dosyalar, geçmiş Proxy · library · middleware · MCP Evet Evet
RTK CLI komut çıktıları CLI wrapper Evet Hayır
lean-ctx CLI komutları, MCP araçları, editor kuralları CLI wrapper · MCP Evet Hayır
Compresr, Token Co. API'lerine gönderilen metin Barındırılan API çağrısı Hayır Hayır
OpenAI Sıkıştırması Konuşma geçmişi Sağlayıcı-native Hayır Hayır

Atıf. Headroom, shell-output yeniden yazması için mükemmel RTK binary'si ile birlikte gelir — git show --short, scoped ls, özetlenmiş yükleyiciler. RTK takımına çok teşekkür; onların araçı stack'imizin first-class bir parçasıdır ve Headroom onun akışında her şeyi sıkıştırır. Headroom ayrıca lean-ctx kullanabilir seçilen CLI bağlam aracı olarak; headroom wrap ... çalıştırmadan önce HEADROOM_CONTEXT_TOOL=lean-ctx ayarlayın.

Katkı

git clone https://github.com/chopratejas/headroom.git && cd headroom
uv sync --extra dev && uv run pytest

Devcontainers .devcontainer/ içinde (default + memory-stack ile Qdrant & Neo4j). CONTRIBUTING.md dosyasına bakın.

Topluluk

Lisans

Apache 2.0 — LICENSE dosyasına bakın.

Benzer MCP sunucuları

upstash/context7 Knowledge & Memory

LLM'ler ve yapay zeka kod editörleri için güncel kod dokümantasyonu.

upstash/context7 ★ 57,846
topoteretes/cognee Knowledge & Memory

AI uygulamaları ve Ajanlar için bellek yöneticisi, çeşitli graph ve vector store'ları destekler ve 30+ veri kaynağından veri alımına olanak tanır.

topoteretes/cognee ★ 18,856
bitbonsai/mcpvault Knowledge & Memory

Obsidian vault'larınız için evrensel bir AI köprüsü sunan MCP tabanlı araç. Notlarınıza güvenli okuma/yazma erişimi sağlar ve arama, toplu işlemler, etiket yönetimi ile frontmatter işleme gibi 11 kapsamlı işlem sunur. Claude, ChatGPT ve tüm MCP uyumlu AI asistanlarıyla çalışır.

bitbonsai/mcpvault ★ 1,446
apecloud/ApeRAG Knowledge & Memory

Grafik RAG, vektör arama ve tam metin aramasını birleştiren, üretime hazır RAG platformu. Kendi Knowledge Graph'ınızı oluşturmak ve Context Engineering için en iyi seçim.

apecloud/ApeRAG ★ 1,193
mem0ai/mem0-mcp Knowledge & Memory

Mem0 için bir Model Context Protocol sunucusu; IDE'ler (Cursor, Windsurf gibi) içinde kodlama tercihlerini ve desenlerini yönetmeye, kod implementasyonlarını, best practices'leri ve teknik dokümantasyonu semantik olarak depolamaya ve erişmeye yarayan araçlar sunuyor.

mem0ai/mem0-mcp ★ 656
graphlit/graphlit-mcp-server Knowledge & Memory

Slack, Discord, web siteleri, Google Drive, Linear veya GitHub'dan her türlü içeriği bir Graphlit projesine aktarın ve ardından Cursor, Windsurf veya Cline gibi MCP client'ları içinde ilgili bilgileri arayıp alın.

graphlit/graphlit-mcp-server ★ 375
Daha fazla: Knowledge & Memory →