bpcontext (Blakethefn)

bpcontext

AI编码代理的上下文窗口优化器。

LLM编码代理通过其上下文窗口读取大文件、命令输出和网页。bpcontext位于代理和这些源之间——它捕获全部内容，将其索引到本地SQLite FTS5数据库中，并仅返回一个紧凑的预览。然后，代理可以按需搜索索引内容，精确地提取所需的块，而不是将所有内容都保存在上下文中。

在实践中，这将文件读取、命令输出和web获取的上下文使用率降低了50-80%，而不会丢失对任何内容的访问。

第2版 添加了语义搜索（通过Candle进行本地嵌入）和智能上下文管理器，该管理器可以在线跟踪利用率和表面优化建议。

问题

典型的Claude Code会话可能会：

• 读取2600行文件→ 5.5万个代币 在上下文中
• 跑 git log --oneline -100 → 数千个令牌用于快速查找
• 从URL获取API文档→ 将整个页面转储到上下文中

这些加起来很快。当你做真正的工作时，你的上下文窗口有一半被你已经阅读过的参考资料占据了。

bpcontext如何解决这个问题

1. 捕捉 --命令输出、文件内容或网页被完整捕获
2. 块 --内容被分成语义上有意义的部分
3. 索引 --块通过FTS5全文索引存储在SQLite中
4. 预览 --截断的头部/尾部预览返回给代理（可配置比率）
5. 搜索 --代理通过多层搜索（BM25+三元组+模糊+向量相似性）按需检索特定块
6. 轨道 --上下文分类账跟踪返回的内容，并在利用率超过阈值时发出警报

完整内容始终可用。代理不需要一次将所有内容保存在内存中。

安装

# CPU only
cargo build --release

# With CUDA support (requires CUDA toolkit)
cargo build --release --features cuda

二进制文件位于 target/release/bpcontext.生成默认配置：

bpcontext --init

配置位置： ~/.config/bpcontext/config.toml

首次运行模型下载

首次使用时，bpcontext会下载 all-MiniLM-L6-v2 从拥抱脸到 ~/.local/share/bpcontext/models/。这是一次性下载-不需要API密钥或帐户。如果下载失败（例如，没有互联网），搜索将退回到仅关键字模式。

快速开始

作为MCP服务器（推荐）

添加到您的克劳德代码 .mcp.json:

{
  "mcpServers": {
    "bpcontext": {
      "command": "/path/to/bpcontext",
      "args": ["serve"]
    }
  }
}

然后配置Claude Code，使其更喜欢bpcontext工具而不是内置工具。添加到您的 CLAUDE.md:

# bpcontext Tool Routing

- **`bpx_execute`** instead of `Bash` for commands producing >20 lines
- **`bpx_execute_file`** instead of `Read` when analyzing a file (not editing it)
- **`bpx_batch_execute`** instead of multiple Bash/Read/Grep calls when exploring
- **`bpx_fetch_and_index`** instead of `WebFetch` for any URL

作为CLI

# Run a command and index its output
bpcontext execute "git log --oneline -50"

# Search indexed content
bpcontext search "authentication"

# Filter by source or content type
bpcontext search "error" --source "git log" --content-type code --limit 5

# Index raw text from stdin
echo "some notes" | bpcontext index "my-notes"

# Fetch and index a web page
bpcontext fetch https://docs.rs/some-crate

# Check context savings
bpcontext stats

# List what's been indexed this session
bpcontext sources

# Backfill embeddings for previously indexed content
bpcontext embed-backfill

# Show context budget and per-source breakdown
bpcontext context-status

MCP工具

知识存储工具（跨会话持久）：

知识库（RAG）

知识库是一个持久的RAG层，在会话中生存。与会话范围索引（每次都会重建）不同，知识存储将目录注册为持久源，并且只对已更改的文件重新索引（通过SHA-256内容哈希进行增量同步）。

这意味着您可以注册一次项目的源目录，并在未来的任何会话中搜索它，而无需重新索引。

命令行界面

# Register a directory as a knowledge source
bpcontext knowledge add /path/to/project/src --label myproject

# Filter by file type
bpcontext knowledge add /path/to/docs --label mydocs --glob "**/*.md"

# Enable enrichments (for Obsidian vaults)
bpcontext knowledge add /path/to/vault --label vault --enrichments frontmatter,wikilinks,folder_tags

# Re-sync all sources (re-indexes changed files only)
bpcontext knowledge sync

# Re-sync a specific source
bpcontext knowledge sync --label myproject

# Check status
bpcontext knowledge status

# Search
bpcontext knowledge search "authentication flow"

# Remove a source
bpcontext knowledge remove --label myproject

会话索引与知识库

bpx_search 查询 两者 同时分层并通过RRF合并结果，因此您可以在一次调用中获得会话上下文结果和持久知识。

富集

增强功能在索引时提取结构化元数据，以进行更丰富的过滤：

丰富内容存储在每个块旁边，可用于搜索结果中的元数据过滤。

数据存储

知识库使用与每个会话内容数据库分离的单个全局数据库：

• 知识数据库： ~/.local/share/bpcontext/knowledge.db --注册源、文件哈希、块和嵌入

克劳德代码挂钩

bpcontext也可以作为Claude Code钩子运行，以自动拦截工具输出：

• 预工具使用 --工具执行前的拦截
• posttooluse --执行后处理和压缩工具输出
• 准紧的 --在上下文压缩之前运行

语义搜索

bpcontextv2增加了第四个搜索层：使用局部嵌入的向量相似性。

• 型号： sentence-transformers/all-MiniLM-L6-v2 （384个维度，约80MB）
• 推断： 蜡烛 （Rust ML框架）——默认在CPU上运行，CUDA可选
• 在索引时间： 每个块都作为BLOB嵌入并存储在SQLite中
• 搜索时： 查询被嵌入，并通过点积与所有存储的向量进行比较（暴力破解，典型会话大小\<1ms）
• 融合： 向量结果与BM25、三元组和模糊结果一起合并到现有的RRF（互易秩融合）管道中

这意味着 bpx_search(["authentication flow"]) 将找到有关“登录会话”、“JWT验证”和“令牌刷新”的块，即使这些词都没有出现在查询中。

重量可配置：

[search]
vector_weight = 1.0    # multiplier for semantic results
keyword_weight = 1.0   # multiplier for keyword results

上下文管理器

bpcontext跟踪它返回给代理的内容，并内联显示优化建议——不需要额外的工具调用。

它是如何工作的： 每次工具响应后，上下文分类账都会根据配置的预算检查利用率。当超过阈值时，响应中会附加一个警报：

每个阈值在每个会话中触发一次。预压缩钩子还包括保持/丢弃建议。

配置

[general]
max_stdout_bytes = 102400   # max bytes captured per command
head_ratio = 0.6            # fraction of preview from head vs tail

[search]
default_limit = 10
throttle_max = 8            # max searches per window
throttle_window_secs = 60
vector_weight = 1.0         # weight for semantic search in RRF fusion
keyword_weight = 1.0        # weight for keyword search in RRF fusion

[fetch]
cache_ttl_hours = 24        # cache fetched URLs

[embeddings]
model = "all-MiniLM-L6-v2"
model_dir = "~/.local/share/bpcontext/models"
batch_size = 32
enabled = true              # set to false to disable embeddings entirely

[context]
budget_tokens = 200000      # estimated context window budget
stale_threshold_minutes = 30

[integration]
taskvault_bin = "/path/to/taskvault"  # optional: for promote command
vault_path = "/path/to/obsidian_docs" # optional: Obsidian vault path

[cleanup]
stale_db_days = 14          # auto-cleanup old session databases

建筑

src/
  cli.rs          — CLI argument parsing (clap)
  config.rs       — TOML config loading
  db.rs           — SQLite connection and session DB management
  fetch.rs        — URL fetching and HTML-to-markdown conversion
  indexdir.rs     — Directory indexing for bpx_index_dir
  promote.rs      — Export results to Obsidian via TaskVault
  stats.rs        — Context savings tracking
  truncate.rs     — Head/tail preview generation
  context/        — Smart context manager (ledger, relevance scoring, alerts)
  embedder/       — Local embedding model (Candle + all-MiniLM-L6-v2)
  executor/       — Command execution and output capture
  hooks/          — Claude Code hook handlers (pre/post tool use, precompact)
  knowledge/      — Persistent knowledge store (RAG): source registry, incremental sync, enrichments, search
  mcp/            — MCP server (JSON-RPC over stdio)
  session/        — Session lifecycle and event tracking
  store/          — Chunking, FTS5 indexing, and multi-layer search (BM25 + trigram + fuzzy + vector)

数据存储

所有运行时数据都存储在XDG标准目录下：

• 内容数据库： ~/.local/share/bpcontext/content/{hash}.db --每个项目的FTS5索引+嵌入（会话范围）
• 会话数据库： ~/.local/share/bpcontext/sessions/{hash}.db --事件+上下文分类账
• 知识数据库： ~/.local/share/bpcontext/knowledge.db --持久知识存储（源注册表、文件哈希、块、嵌入）
• 模型： ~/.local/share/bpcontext/models/ --下载的嵌入权重
• 配置： ~/.config/bpcontext/config.toml

需求

• 锈蚀1.70+
• SQLite（通过rusqlite捆绑）
• 适用于CUDA：CUDA工具包12.0+和兼容的GPU

许可证

麻省理工学院