massive-context-mcp

Massive Context MCP

借助分块、子查询和通过 Ollama 免费进行本地推理，处理超大上下文（超过 1,000 万个 token）。

flowchart TD
    A[Claude Code] --> B[RLM MCP Server]
    B --> C{rlm_ollama_status}
    C -->|cached 60s| D{provider = auto}

    D -->|Ollama running| E[🦙 Ollama<br/>gemma3:12b]
    D -->|Ollama unavailable| F[☁️ Claude SDK<br/>claude-haiku-4-5]

    E --> G[["💰 $0<br/>Free local inference"]]
    F --> H[["💰 ~$0.80/1M<br/>Cloud inference"]]

    style A fill:#ff922b,color:#fff
    style B fill:#339af0,color:#fff
    style E fill:#51cf66,color:#fff
    style F fill:#748ffc,color:#fff
    style G fill:#51cf66,color:#fff
    style H fill:#748ffc,color:#fff

基于递归语言模型模式。灵感来自 richardwhiteii/rlm。

📸 截图

核心思路

不要将超大上下文直接输入大模型，而是：

1. 加载上下文作为外部变量（不放入提示词）
2. 以编程方式检查结构
3. 按策略分块（按行、字符或段落）
4. 对各块递归进行子查询
5. 汇总结果，生成最终综合内容

快速开始

安装

选项 1：PyPI（推荐）

uvx massive-context-mcp
# or
pip install massive-context-mcp

使用可选扩展：

# With Code Firewall integration (security filter for rlm_exec)
pip install massive-context-mcp[firewall]

# With Claude Agent SDK (for programmatic Claude API access)
pip install massive-context-mcp[claude]

# With all extras
pip install massive-context-mcp[firewall,claude]

选项 2：Claude Desktop 一键安装

从 Releases 下载 .mcpb，然后双击安装。

选项 3：从源代码安装

git clone https://github.com/egoughnour/massive-context-mcp.git
cd massive-context-mcp
uv sync

连接到 Claude Code / Claude Desktop

添加到 ~/.claude/.mcp.json（Claude Code）或 claude_desktop_config.json（Claude Desktop）：

{
  "mcpServers": {
    "massive-context": {
      "command": "uvx",
      "args": ["massive-context-mcp"],
      "env": {
        "RLM_DATA_DIR": "~/.rlm-data",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

工具

设置与状态工具

工具	用途
rlm_system_check	检查系统要求 — 验证 macOS、Apple Silicon、16GB 以上内存和 Homebrew
rlm_setup_ollama	通过 Homebrew 安装 — 受管理的服务、自动更新，需要 Homebrew
rlm_setup_ollama_direct	通过直接下载安装 — 无需 sudo，完全无头运行，可在受限机器上使用
rlm_ollama_status	检查 Ollama 是否可用 — 检测是否可进行免费的本地推理

分析工具

工具	用途
rlm_auto_analyze	一步分析 — 自动检测类型、分块并查询
rlm_load_context	将上下文加载为外部变量
rlm_inspect_context	获取结构信息，而不将其加载到提示词中
rlm_chunk_context	按行、字符或段落分块
rlm_get_chunk	获取指定分块
rlm_filter_context	使用正则表达式筛选（保留或移除匹配行）
rlm_exec	对已加载的上下文执行 Python 代码（沙箱隔离）
rlm_sub_query	对分块发起子 LLM 调用
rlm_sub_query_batch	并行处理多个分块
rlm_store_result	存储子调用结果以供汇总
rlm_get_results	获取已存储的结果
rlm_list_contexts	列出所有已加载的上下文

使用 rlm_auto_analyze 快速分析

对于大多数使用场景，只需使用 rlm_auto_analyze——它会自动处理所有工作：

rlm_auto_analyze(
    name="my_file",
    content=file_content,
    goal="find_bugs"  # or: summarize, extract_structure, security_audit, answer:<question>
)

自动执行的操作：

1. 检测内容类型（Python、JSON、Markdown、日志、散文、代码）
2. 选择最优分块策略
3. 根据内容类型调整查询
4. 运行并行子查询
5. 返回汇总结果

支持的目标：

目标	描述
summarize	总结内容目的和要点
find_bugs	找出错误、问题和潜在隐患
extract_structure	列出函数、类、架构和标题
security_audit	查找漏洞和安全问题
answer:<question>	回答有关内容的自定义问题

使用 rlm_exec 进行编程分析

对于确定性的模式匹配和数据提取，可使用 rlm_exec 对已加载的上下文直接运行 Python 代码。这种方式更接近论文中的 REPL 方法，并能让你完全控制分析逻辑。

工具：rlm_exec

用途：在沙箱子进程中对已加载的上下文执行任意 Python 代码。

参数：

• code（必填）：要执行的 Python 代码。设置 result 变量以捕获输出。
• context_name（必填）：先前已加载的上下文名称。
• timeout（可选，默认值为 30）：最长执行时间，单位为秒。

特性：

• 上下文可通过只读变量 context 访问
• 预导入模块：re、json、collections
• 子进程隔离（不会导致服务崩溃）
• 强制执行超时限制
• 可在任何安装了 Python 的系统上运行（无需 Docker）

示例 — 在已加载的上下文中查找模式：

# After loading a context
rlm_exec(
    code="""
import re
amounts = re.findall(r'\$[\d,]+', context)
result = {'count': len(amounts), 'sample': amounts[:5]}
""",
    context_name="bill"
)

响应示例：

{
  "result": {
    "count": 1247,
    "sample": ["$500", "$1,000", "$250,000", "$100,000", "$50"]
  },
  "stdout": "",
  "stderr": "",
  "return_code": 0,
  "timed_out": false
}

示例 — 提取结构化数据：

rlm_exec(
    code="""
import re
import json

# Find all email addresses
emails = re.findall(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', context)

# Count by domain
from collections import Counter
domains = [e.split('@')[1] for e in emails]
domain_counts = Counter(domains)

result = {
    'total_emails': len(emails),
    'unique_domains': len(domain_counts),
    'top_domains': domain_counts.most_common(5)
}
""",
    context_name="dataset",
    timeout=60
)

何时使用 rlm_exec，何时使用 rlm_sub_query：

使用场景	工具	原因
提取所有日期、ID、金额	rlm_exec	正则表达式具有确定性且速度快
查找安全漏洞	rlm_sub_query	需要推理和上下文
解析 JSON/XML 结构	rlm_exec	标准库能够完美胜任
总结主题或语气	rlm_sub_query	需要自然语言理解
统计词频	rlm_exec	简单计算，无需 AI
回答“X 为什么会发生？”	rlm_sub_query	需要推断和推理

提示：对于大型上下文，可结合使用两者——先用 rlm_exec 筛选或提取内容，再用 rlm_sub_query 对筛选结果进行语义分析。

Code Firewall 集成（可选）

为增强安全性，可集成 code-firewall-mcp，在执行前过滤危险代码模式：

pip install massive-context-mcp[firewall]

安装后，rlm_exec 可自动检查代码是否包含已知危险模式的黑名单条目（例如，os.system()、eval()、使用 shell=True 的 subprocess）。防火墙使用结构相似度匹配：将代码规范化为骨架，再通过嵌入与黑名单模式进行比对。

工作原理：

1. 将代码解析为语法树并进行规范化（标识符 → _，字符串 → "S"）
2. 使用 Ollama 对规范化后的结构进行嵌入
3. 在 ChromaDB 中检查其与黑名单模式的相似度
4. 如果相似度超过阈值（默认值：0.85），则阻止代码

配置（环境变量）：

• RLM_FIREWALL_ENABLED=true — 启用防火墙检查（安装软件包后自动启用）
• RLM_FIREWALL_MODE=warn|block — 匹配时发出警告或阻止（默认值：warn）

被阻止模式示例：

• os.system(user_input) — 命令注入
• eval(untrusted_data) — 代码注入
• subprocess.Popen(..., shell=True) — Shell 注入

使用 rlm_firewall_status 检查防火墙是否可用及其配置。

提供方与自动检测

RLM 会自动检测并使用当前可用的最佳提供方：

提供方	默认模型	费用	用途
auto	（当前可用的最佳模型）	$0 或 ~$0.80/1M	默认 — 优先使用可用的 Ollama
ollama	gemma3:12b	$0	本地推理，需要 Ollama
claude-sdk	claude-haiku-4-5	~$0.80/1M 输入	云端推理，始终可用

自动检测的工作原理

使用 provider="auto"（默认值）时，RLM 会：

1. 检查 Ollama 是否正在运行，地址为 OLLAMA_URL（默认值：http://localhost:11434）
2. 检查 gemma3:12b 是否可用（或任何 gemma3 变体）
3. 如果 Ollama 可用，则使用 Ollama；否则回退到 Claude SDK

状态会缓存 60 秒，以避免重复进行网络检查。

检查 Ollama 状态

使用 rlm_ollama_status 查看可用内容：

rlm_ollama_status()

Ollama 已就绪时的响应：

{
  "running": true,
  "models": ["gemma3:12b", "llama3:8b"],
  "default_model_available": true,
  "best_provider": "ollama",
  "recommendation": "Ollama is ready! Sub-queries will use free local inference by default."
}

Ollama 不可用时的响应：

{
  "running": false,
  "error": "connection_refused",
  "best_provider": "claude-sdk",
  "recommendation": "Ollama not available. Sub-queries will use Claude API. To enable free local inference, install Ollama and run: ollama serve"
}

透明的提供方选择

所有子查询响应都会包含实际使用的提供方：

{
  "provider": "ollama",
  "model": "gemma3:12b",
  "requested_provider": "auto",
  "response": "..."
}

自主使用

启用 Claude 自动使用 RLM 工具，无需手动调用：

1. 集成 CLAUDE.md 将 CLAUDE.md.example 的内容复制到项目的 CLAUDE.md（或全局配置文件 ~/.claude/CLAUDE.md），以指导 Claude 在何时自动使用 RLM 工具。

2. 安装 Hook 将 .claude/hooks/ 目录复制到项目中，以便在读取大于 10KB 的文件时自动建议使用 RLM：

cp -r .claude/hooks/ /Users/your_username/your-project/.claude/hooks/

该 Hook 会提供指导，但不会阻止读取。

3. Skill 参考 复制 .claude/skills/ 目录，以获取全面的 RLM 使用指导：

cp -r .claude/skills/ /Users/your_username/your-project/.claude/skills/

完成这些设置后，Claude 会自主判断何时使用 RLM，而不是将大型文件直接读入上下文。

设置 Ollama（免费本地推理）

RLM 可以在配备 Apple Silicon 的 macOS 上自动安装和配置 Ollama。有两种安装方式，各有不同的取舍：

选择安装方式

方面	rlm_setup_ollama（Homebrew）	rlm_setup_ollama_direct（直接下载）
是否需要 sudo	仅在未安装 Homebrew 时需要	❌ 从不需要
是否需要 Homebrew	✅ 是	❌ 否
自动更新	✅ 是（brew upgrade）	❌ 手动更新
服务管理	✅ brew services（launchd）	⚠️ ollama serve（前台运行）
安装位置	/opt/homebrew/	~/Applications/
受限机器	⚠️ 可能失败	✅ 可运行
完全无头运行	⚠️ 可能会提示输入 sudo	✅ 可以

建议：

• 如果已安装 Homebrew 且希望自动管理更新，请使用 Homebrew 方式
• 对于自动化、受限机器或没有管理员访问权限的情况，请使用 直接下载

方法 1：通过 Homebrew 安装（已安装 Homebrew 时推荐）

# 1. Check if your system meets requirements
rlm_system_check()

# 2. Install via Homebrew
rlm_setup_ollama(install=True, start_service=True, pull_model=True)

此操作会：

• 通过 Homebrew 安装 Ollama（brew install ollama）
• 将 Ollama 作为托管后台服务启动（brew services start ollama）
• 下载 gemma3:12b 模型（约 8GB）

要求：

• 搭载 Apple Silicon（M1/M2/M3/M4）的 macOS
• 16GB 及以上内存（运行 gemma3:12b 需要约 8GB）
• 已安装 Homebrew

方法 2：直接下载（完全无头运行，无需 sudo）

# 1. Check system (Homebrew NOT required for this method)
rlm_system_check()

# 2. Install via direct download - no sudo, no Homebrew
rlm_setup_ollama_direct(install=True, start_service=True, pull_model=True)

此操作会：

• 从 https://ollama.com/download/Ollama-darwin.zip 下载 Ollama
• 解压到 ~/Applications/Ollama.app（用户目录，无需管理员权限）
• 通过 ollama serve 启动 Ollama（后台进程）
• 下载 gemma3:12b 模型

要求：

• 搭载 Apple Silicon（M1/M2/M3/M4）的 macOS
• 16GB 及以上内存
• 无需特殊权限！

**关于 PATH 的说明：**直接安装后，CLI 位于：

~/Applications/Ollama.app/Contents/Resources/ollama

如有需要，请将其添加到 shell 配置中：

export PATH="$HOME/Applications/Ollama.app/Contents/Resources:$PATH"

内存较少的系统

使用任一种安装方式时，都可以改用较小的模型：

rlm_setup_ollama(install=True, start_service=True, pull_model=True, model="gemma3:4b")
# or
rlm_setup_ollama_direct(install=True, start_service=True, pull_model=True, model="gemma3:4b")

手动设置

如果你倾向于手动安装，或使用其他平台：

1. 安装 Ollama，从 https://ollama.ai 下载或通过 Homebrew 安装：

   brew install ollama
   

2. 启动服务：

   brew services start ollama
   # or: ollama serve
   

3. 下载模型：

   ollama pull gemma3:12b
   

4. 验证是否正常运行：

   rlm_ollama_status()
   

选择提供方

RLM 会在 Ollama 可用时自动使用它。你也可以指定提供方：

# Auto-detection (default) - uses Ollama if available
rlm_sub_query(query="Summarize", context_name="doc")

# Explicitly use Ollama
rlm_sub_query(query="Summarize", context_name="doc", provider="ollama")

# Explicitly use Claude SDK
rlm_sub_query(query="Summarize", context_name="doc", provider="claude-sdk")

使用示例

基本模式

# 0. (Optional) First-time setup on macOS - choose ONE method:

# Option A: Homebrew (if you have it)
rlm_system_check()
rlm_setup_ollama(install=True, start_service=True, pull_model=True)

# Option B: Direct download (no sudo, fully headless)
rlm_system_check()
rlm_setup_ollama_direct(install=True, start_service=True, pull_model=True)

# 0b. (Optional) Check if Ollama is available for free inference
rlm_ollama_status()

# 1. Load a large document
rlm_load_context(name="report", content=<large document>)

# 2. Inspect structure
rlm_inspect_context(name="report", preview_chars=500)

# 3. Chunk into manageable pieces
rlm_chunk_context(name="report", strategy="paragraphs", size=1)

# 4. Sub-query chunks in parallel (auto-uses Ollama if available)
rlm_sub_query_batch(
    query="What is the main topic? Reply in one sentence.",
    context_name="report",
    chunk_indices=[0, 1, 2, 3],
    concurrency=4
)

# 5. Store results for aggregation
rlm_store_result(name="topics", result=<response>)

# 6. Retrieve all results
rlm_get_results(name="topics")

处理 2MB 文档

使用 H.R.1 法案（2MB）进行测试：

# Load
rlm_load_context(name="bill", content=<2MB XML>)

# Chunk into 40 pieces (50K chars each)
rlm_chunk_context(name="bill", strategy="chars", size=50000)

# Sample 8 chunks (20%) with parallel queries
# (auto-uses Ollama if running, otherwise Claude SDK)
rlm_sub_query_batch(
    query="What topics does this section cover?",
    context_name="bill",
    chunk_indices=[0, 5, 10, 15, 20, 25, 30, 35],
    concurrency=4
)

结果：全面提取主题，费用为 $0（使用 Ollama）或约 $0.02（使用 Claude）。

分析《战争与和平》（3.3MB）

对来自 Project Gutenberg 的托尔斯泰史诗小说进行文学分析：

# Download the text
curl -o war_and_peace.txt https://www.gutenberg.org/files/2600/2600-0.txt

# Load into RLM (3.3MB, 66K lines)
rlm_load_context(name="war_and_peace", content=open("war_and_peace.txt").read())

# Chunk by lines (1000 lines per chunk = 67 chunks)
rlm_chunk_context(name="war_and_peace", strategy="lines", size=1000)

# Sample 10 chunks evenly across the book (15% coverage)
sample_indices = [0, 7, 14, 21, 28, 35, 42, 49, 56, 63]

# Extract characters from each sampled section
rlm_sub_query_batch(
    query="List major characters in this section with brief descriptions.",
    context_name="war_and_peace",
    chunk_indices=sample_indices,
    provider="claude-sdk",  # Haiku 4.5
    concurrency=8
)

结果：完整梳理全书人物弧光——皮埃尔从理想主义者到囚犯再到丈夫的历程、娜塔莎的成长、尼古拉·罗斯托夫从士兵到地主的历程——总费用约 $0.03。

指标	数值
文件大小	3.35 MB
行数	66,033
分块数	67
采样数	10（15%）
费用	约 $0.03

数据存储

graph TD
    A[("$RLM_DATA_DIR")] --> B["📁 contexts/"]
    A --> C["📁 chunks/"]
    A --> D["📁 results/"]

    B --> B1[".txt files"]
    B --> B2[".meta.json"]
    C --> C1["by context name"]
    D --> D1[".jsonl files"]

    style A fill:#339af0,color:#fff
    style B fill:#51cf66,color:#fff
    style C fill:#51cf66,color:#fff
    style D fill:#51cf66,color:#fff

上下文会在不同会话间保留。分块后的上下文会缓存以供重复使用。

学习提示词

使用这些提示词，通过 Claude Code 探索代码库并学习 RLM 模式。代码是唯一可信来源。

了解工具

Read src/rlm_mcp_server.py and list all RLM tools with their parameters and purpose.

Explain the chunking strategies available in rlm_chunk_context.
When would I use each one?

What's the difference between rlm_sub_query and rlm_sub_query_batch?
Show me the implementation.

了解架构

Read src/rlm_mcp_server.py and explain how contexts are stored and persisted.
Where does the data live?

How does the claude-sdk provider extract text from responses?
Walk me through _call_claude_sdk.

What happens when I call rlm_load_context? Trace the full flow.

动手学习

Load the README as a context, chunk it by paragraphs,
and run a sub-query on the first chunk to summarize it.

Show me how to process a large file in parallel using rlm_sub_query_batch.
Use a real example.

I have a 1MB log file. Walk me through the RLM pattern to extract all errors.

扩展 RLM

Read the test file and explain what scenarios are covered.
What edge cases should I be aware of?

How would I add a new chunking strategy (e.g., by regex delimiter)?
Show me where to modify the code.

How would I add a new provider (e.g., OpenAI)?
What functions need to change?

许可证

MIT