MegaContext

突破 300 万 Token 上下文窗口

不改模型 · 不改引擎 · 纯外挂管线 · 零门槛

快速开始 · 为什么 · 怎么工作 · 安装 · 文档 · 贡献

---

💡 一句话说清楚

你要分析 300 万字的文档，但 LLM 一次只能看 10 万字。MegaContext 给 LLM 装了个超大型外挂记忆库——先把所有文档建好索引，你每次提问时自动找到最相关的几段喂给 LLM，让 LLM 精准回答。

你的 300 万字文档
      │
      ▼
  MegaContext 建索引（一次性，2-5 分钟）
      │
      ▼
你提问 → 自动检索最相关段落 → LLM 回答（每次 2-5 秒）

🎯 为什么需要这个

问题	MegaContext 的答案
文档太大塞不进上下文	索引任意规模文档，检索后精准注入
长上下文太贵	每次推理 ~140K token，比原生 1M 省 7 倍
长上下文太慢	2-5 秒，比原生长上下文推理快 10 倍
要改模型才能用	不改权重、不改引擎，任意 LLM 都行
数据不想上传云端	支持全本地部署，数据零外泄

🏗️ 架构

┌─────────────────────┐
│  Layer 3: Skill     │  ← Claude Code 专属 (/megacontext)
└──────────┬──────────┘
┌──────────┴──────────┐
│  Layer 2: MCP Server│  ← Claude Code / Codex / VS Code
└──────────┬──────────┘
┌──────────┴──────────┐
│  Layer 1: Python 库 │  ← 核心引擎，所有平台通用
│  + CLI 命令行        │
└─────────────────────┘

核心链路：智能分块 → BM25+向量+知识图谱三层索引 → MMR 多样性筛选 → LLM 重排序 → 递归检索 → 上下文注入 → 回答

🚀 快速开始

安装

pip install megacontext

三行上手

from megacontext import MegaContext

mc = MegaContext.from_document("my_docs/", "my_kb")
answer = mc.ask("数据安全法和GDPR在删除权上有什么异同？")
print(answer.text)

CLI 一行

# 建索引
megacontext index "docs/" --name kb

# 提问
megacontext ask kb "核心观点是什么？"

# 对话模式
megacontext chat kb

✨ 核心特性

• 🔍 三层索引: BM25 精确匹配 + 向量语义搜索 + 知识图谱跨块关联
• 🕸️ 知识图谱: 自动抽取实体和关系，支持多跳推理遍历
• 🧠 智能重排序: MMR 去冗余 + LLM 逐块打分 + 列表级验证
• 🔄 递归检索: 检测信息缺口 → 自动生成新查询 → 补充检索
• 💾 四级缓存: Embedding / 检索 / 重排序 / 答案缓存，越用越快
• 🏠 全本地可运行: 零 API 依赖（Ollama + BGE + cross-encoder）
• 📎 引用溯源: 每个回答标注来源文档和段落位置
• 🔌 多平台: CLI / Python SDK / MCP Server / Claude Code Skill

📊 性能

指标	数值
文档容量上限	无界（线性扩展，对数检索）
大海捞针召回率@10	~84-91%
2 跳推理成功率	~75%
单次推理延迟	冷启动 ~3s，热缓存 ~1s
Token 消耗/次	~140K (vs 原生 1M)
预处理时间（300万字）	2-5 分钟
索引磁盘占用	原文档的 5-10%

🔧 平台支持

平台	使用方式
Claude Code	MCP Server + Skill（/megacontext 命令）
Codex (OpenAI)	MCP Server
VS Code	MCP 扩展 + megacontext-mcp
Trae Solo	megacontext CLI
任意终端	pip install megacontext

🧪 本地模型部署

全部本地运行，零 API 费用，数据零泄露：

# megacontext.yaml
llm:
  model: ollama:qwen2.5:14b
  api_base: http://localhost:11434/v1

embedding:
  model: local:bge-m3

rerank:
  model: local:bge-reranker-v2-m3

mc = MegaContext.from_document(
    "internal_docs/",
    "local_kb",
    embed_model="local:bge-m3",
    rerank_model="local:bge-reranker-v2-m3",
    llm_model="ollama:qwen2.5:14b",
    llm_api_base="http://localhost:11434/v1",
)

📖 文档

文档	内容
TUTORIAL.md	安装与使用教程（面向用户）
design.md	完整算法设计文档（7 模块 + DeepSeek v4 适配）
mcp-server-design.md	MCP Server 设计（4 工具 + 部署配置）
skill-design.md	Claude Code Skill 设计
examples/	Python 代码示例（12 个场景）

🗺️ 路线图

• v0.1 — MVP：分块、BM25+向量索引、MMR+LLM 重排序、CLI
• v0.2 — 知识图谱、递归检索、多轮对话、缓存系统
• v0.3 — 本地 embedding、cross-encoder、Ollama 集成
• v0.4 — MCP Server、Claude Code Skill
• v1.0 — 全格式文档、知识图谱两跳、发布 PyPI

🤝 贡献

欢迎贡献！请先阅读 CONTRIBUTING.md。

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

📄 协议

MIT License · 详见 LICENSE

---

_{Built with ❤️ for developers who need more context than their LLM can handle.}