Contextful

Contextful

⚠️ 当前处于早期 Alpha 阶段。API、功能和集成尚不稳定，可能会发生破坏性变更。非常欢迎反馈和贡献！

面向 Agentic AI 的本地上下文管理、搜索引擎与记忆。

Contextful 是一层运行时上下文层和本地搜索引擎，供 Agent 使用，让它们能够通过一种快速方式查找、压缩、引用和记忆项目上下文。

它以 CLI 优先工具的形式提供，配有 MCP 运行时桥接和生成的 Agent 指令，可无缝集成 Codex、Claude Code、Cursor、Windsurf、GitHub Copilot、VS Code、Cline、Roo Code、Continue 和 Zed。

Contextful 不会让 Agent 每次会话都读取 40 个文件，而是一次性为项目建立索引，并返回经过排序、带引用且符合令牌预算的上下文包。

为什么？

上下文一直是 Agentic AI 的瓶颈。大型上下文窗口模型（例如，100 万个令牌）：

1. 成本高昂，且需要显著更多的计算资源和处理时间。
2. 随着上下文窗口填满，更容易丢失关键信息。
3. 大多数项目有数百万行代码，但 Agent 每个上下文窗口能容纳的令牌有限。

当前的解决方案是让 Agent 猜测要读取哪些文件，然后每次会话都花费令牌来读取这些文件。这既缓慢、昂贵，又容易丢失信息。

除此之外，Agent 无法跨会话存储或共享经验。每次启动时，它们都会忘记一切，不得不再次读取相同的上下文。

我开始开发 Contextful，是为了通过高效的知识检索缩小上下文窗口。如果我们为项目建立索引，并返回经过排序、带引用且符合令牌预算的上下文包，就能实现：

• 令牌使用效率提升 100 倍： 不再为重复读取相同文件而消耗令牌。
• 减少工具调用： 一个上下文包即可替代数十次 grep、glob 和读取文件的调用。
• 会话之间不丢失上下文： Agent 可以将会话经验存储在有证据支持的记忆账本中。
• 可共享的项目知识： 经验和上下文包在上下文压缩及后续会话后仍然保留。

主要功能

1. 上下文管理

默认的本地存储使用 SQLite，并配备基于 FTS 的搜索和类型化图表。V1 提供：

• SQLite 作为默认的本地存储。
• FTS5 词法/BM25 搜索。
• 类型化图表：nodes、edges、node_props、edge_props。
• 用于常见图关系的热邻接缓存。
• 受 Code2Vec 风格二次重排序信号启发的确定性结构指纹。

后续存储升级将支持可选的语义向量（通过 sqlite-vec、LanceDB 或本地 HNSW），以及供更大型代码库使用的 Roaring 位图或 CSR 数组压缩邻接表。

2. 搜索引擎

Contextful 会分析查询、判断意图，并结合词法搜索、符号、文档、图关系和记忆命中，检索合适的证据。目标是为 Agent 提供 Google 级别的项目搜索：即使是“身份验证入门所需资源”这类模糊查询，也能找到合适的代码、文档和过往经验。

3. 记忆账本

Agent 可以存储经验、决策和有用的项目信息，但不会以松散的“记住这个”笔记形式保存。每条记忆都必须包含来自文件、符号、提交或先前上下文包的证据引用。当证据发生变化时，Contextful 会将该记忆标记为过期。

4. 上下文执行

Contextful 是一个 MCP 服务、本地索引器和轻量级命令行工具：

• **MCP 服务：**Agent 接口。
• **本地守护进程／监视器：**负责索引、重建、保持内容最新，以及未来的基准测试。
• **命令行工具（cxf）：**供人工进行设置、索引、搜索、写入记忆和本地冒烟测试。

MCP 是合适的接口，因为工具、资源和提示词正是 MCP 标准化的内容。Agent 请求上下文；Contextful 返回精简的证据。

安装

npx @inferensys/contextful init --workspace .
npx @inferensys/contextful search "where is user auth handled" --workspace . --budget 2000

作为 MCP 服务运行：

npx @inferensys/contextful server

命令行工具

主要二进制文件是 cxf；同时也提供更易读的别名 contextful。

cxf init --workspace <path>
cxf index --workspace <path> [--watch]
cxf daemon --workspace <path>
cxf search "<query>" --workspace <path> --budget 2000 --json
cxf memory add --workspace <path> --claim <text> --evidence <ref>
cxf server

核心 MCP 工具

保持 Agent 接口精简：

• context_pack(query, budget, scope) - 核心工具。返回经过排序、带引用且符合令牌预算的资料包，而不是迫使 Agent 随机读取 40 个文件。
• search_code(query, mode, filters) - 强大的代码、文档、符号和记忆搜索。
• trace_path(from, to, edge_types) - 遍历文件、符号、模块和配置之间的图关系。
• impact_analysis(symbol_or_file) - 查找反向依赖项和可能相关的测试。
• why_changed(symbol_or_file) - 提供当前证据和 Git 历史记录。
• recall_memory(query, scope) - 搜索会话中的经验和持久保存的项目经验。
• write_lesson(claim, evidence_refs, scope) - 保存有证据支持的记忆。

MCP 客户端设置

在任何支持 MCP 的编码工具中使用此标准输入输出（stdio）服务命令：

{
  "mcpServers": {
    "contextful": {
      "command": "npx",
      "args": ["-y", "@inferensys/contextful", "server"]
    }
  }
}

Codex：

codex mcp add contextful -- npx -y @inferensys/contextful server

以命令行工具为先的 Agent 工作流

每个工作区运行一次 cxf init。它会为项目建立索引，并写入 .contextful/AGENT_INSTRUCTIONS.md。这是一份精简的技能指南，告知 Agent 何时调用 context_pack、何时缩小搜索范围，以及何时允许写入记忆。

当人工想要测试 Agent 将收到的同一份证据资料包时，请使用 cxf search：

cxf search "how does auth load user profiles?" --workspace . --budget 2000

MCP 服务仍然是 Agent 接口。命令行工具用于设置、检查和可重复的本地测试。

隐私

V1 仅在本地运行。它不会调用外部嵌入 API、上传源代码、编辑源文件、自动修复代码，也不会在目标工作区内安装依赖项。

证据引用

写入记忆时，必须使用搜索或上下文资料包返回的证据引用：

• file:src/auth.ts:10-40
• symbol:src/auth.ts#AuthService:12
• pack:ctx_...

无效或过时的证据会被拒绝或标记为过时。