Infimium

Infimium

为你的代码库打造的私有上下文层与超级大脑。 为 AI Agent 赋予持久记忆、深度依赖图和即时代码上下文 —— 100% 本地运行，零 token 冗余。

演示

为什么需要它

大型仓库会让 Agent 读取过多代码，或错过正确的符号。Infimium 会在 Agent 开始编辑之前检索精简且相关的上下文。

200,000 lines of code
Agent reads everything -> context blown + expensive
grep "price calculation" -> misses calcPropertyValue()

tool: semantic_code_search
query: "price calculation logic"

-> services/property/calc.ts:142 · calcPropertyValue()
-> callers: getListingPrice(), estimatePropertyTax()

快速开始

需要 Node.js 22.5+。在你的项目文件夹中运行：

cd /path/to/your/project
npx infimium@latest setup

请从你要索引的仓库中运行 setup，而不是从你的主目录（~）运行。 Infimium 会自动阻止过于宽泛的根目录，因此它不会扫描无关文件。

该命令会创建全局配置，在已安装 Ollama 的情况下启动 Ollama，拉取 nomic-embed-text，索引当前项目或工作区，运行 doctor，并打开 Playground。

已发布的 CLI 保留其可执行入口点，因此 MCP 客户端可以通过下面的配置直接启动它。

如果尚未安装 Ollama：

npx infimium@latest setup --install-deps

infimium setup 会在 ~/.infimium/.env 创建一个全局配置。你不需要在每个项目中都放置 .env。代码、文档、记忆、图和向量都存储在本地 ~/.infimium/ 下。

联网搜索是可选的。仅在需要时添加 Tinyfish 密钥：

SEARCH_PROVIDER=tinyfish
SEARCH_API_KEY=your_key

完整的 infimium plan 生成还需要一个本地文本模型：

ollama pull llama3.1

infimium plan --dry-run "your task" 无需该模型即可运行，并会先展示检索到的代码上下文。

连接你的 Agent

Cursor、Windsurf、Claude Desktop 以及其他 MCP 客户端：

{
  "mcpServers": {
    "infimium": {
      "command": "npx",
      "args": ["-y", "infimium", "serve"]
    }
  }
}

重启客户端，然后使用：

Use Infimium hello_infimium.
Use Infimium get_context before starting.
Use Infimium semantic_code_search to explain this repository.

Infimium 通常使用 MCP 进程的工作目录。如果你的客户端从其他位置启动它，请传入一次 project_path；Infimium 会记住当前活动项目并自动为其建立索引。

工具

工具	功能
hello_infimium	确认 MCP 服务运行正常。
get_context	读取已保存的 YAML 仓库上下文、当前记忆和交接信息；显式刷新会更新 Git/索引状态。
infimium_update	刷新情景记忆和交接图；控制自动记忆检查点。
semantic_code_search	按语义查找代码，并优先返回符号签名。
expand_symbol	仅在需要时加载某个完整实现。
query_local_docs	搜索本地 Markdown、文本、HTML 和 PDF 文件。
dep_graph	显示某个符号的导入、调用方、被调用方和 HTTP 路由。
project_memory	跨 Agent 保存活动的暂存区事件、精简里程碑和持久项目规则。
plan	基于代码和图上下文构建有依据的实现计划。
web_search	通过可选的 Tinyfish 配置进行联网搜索。
fetch_url	从 URL 中提取可读的 Markdown 或文本。
shell	运行允许列表中的命令，并设置超时和输出限制。

命令行

命令	描述
infimium doctor	对依赖项和配置运行健康检查。
infimium status	显示索引和记忆的当前状态。
infimium --help	显示所有相关的命令行命令。
infimium playground	启动本地 Web UI，以浏览索引、图和记忆。
infimium index	扫描并索引当前项目目录（代码、文档、依赖项）。
infimium watch	以监视模式运行索引器，持续索引更改。
infimium get-context	以 YAML 格式输出完整的扁平化上下文（layer.md）。
infimium code-search <query>	语义搜索代码并返回符号签名。
infimium expand-symbol <symbol>	获取特定符号的完整实现代码。
infimium docs-search <query>	语义搜索本地 markdown/text 文档。
infimium dep-graph <symbol>	显示依赖项、调用方、被调用方和路由图。
infimium plan --dry-run "<task>"	根据给定提示词草拟实现计划。
infimium remember "<note>"	向项目记忆添加里程碑、进度或决策。
infimium resume	显示活动任务和最近的暂存记忆事件。
infimium memory complete	将活动暂存区压缩为归档里程碑。
infimium memory search "<query>"	语义搜索过去的项目规则和记忆账本。

如果你没有全局安装该包，请使用 npx infimium ...。

项目记忆

自行刷新记忆，或为当前项目启用定期检查点：

infimium update --note "Implemented login validation" --task "Finish login" --handoff "Run the auth tests next"
infimium update start --interval 300
infimium update status
infimium update stop

将示例笔记替换为你自己的内容。添加 --project /path/to/repo 以选择项目，添加 --file src/auth.ts 以附加相关文件。infimium_update 和 infimium-update 是命令行别名。MCP Agent 使用 infimium_update 工具，并传入 action: refresh|start|stop|status、project_path，以及可选的 note、task、handoff、files 或 interval_seconds。

自动更新为可选启用，并在前台命令行监视器或 MCP 服务打开时运行。其按项目设置会在重启后保留；stop 会禁用未来的检查点（正在进行的刷新可能会完成）。检查点会在本地 SQLite 中关联事件片段、任务、文件引用和交接笔记。未更改的观察结果会被去重。自动检查点记录可观察状态，而非猜测的意图，且绝不会将任务标记为完成。

get-context / get_context 现在会读取已保存的上下文和当前记忆，而无需重新扫描仓库。它包含一个有界记忆图，以及仅在收到请求时才回答仓库概览问题的指引，并优先使用 Infimium 记忆。缺失的上下文会被明确报告。运行 infimium update 或 get-context --refresh 以刷新文件系统上下文。这些是 Agent 指引，而非针对其他客户端的强制机制。

Infimium 在长时间会话中保持记忆有界：

• 暂存区： 活动任务的最近事件。
• 归档： 已完成任务的压缩摘要。
• 账本： 持久决策、规则、特殊行为和未解决的阻塞。

在工作期间记录有意义的进度：

infimium remember "Added rate-limit middleware" --type progress --task "Rate limiting"
infimium remember "Use Redis-backed counters in production" --type decision

当任务完成时：

infimium memory complete

Infimium 在可用时使用本地 llama3.1 模型，在不可用时回退到确定性压缩。原始压缩事件会在本地保留七天后被修剪。get_context 绝不会调用大模型或网络服务。

从源代码检出中，构建一次并使用以下命令运行本地 playground：

npm run build
npm run playground

本地架构

• Ollama 在你的机器上创建嵌入。
• 嵌入式 SQLite 存储向量、索引元数据、项目记忆和图边。无需 ChromaDB 或 Docker 服务。
• 文档使用递归的边界感知分块，而非盲目的固定切片。
• 内置 JavaScript、TypeScript、Python 和 Dart 解析器。
• Go、Rust 和 Java 的 Tree-sitter WASM 语法在首次使用时下载，并缓存到 ~/.infimium/grammars/。
• .gitignore、.infimiumignore 和框架默认值会在索引前排除依赖、构建输出、Flutter 产物、缓存和二进制文件。
• semantic_code_search 返回签名；expand_symbol 按需提供完整代码。
• 项目记忆使用会话级草稿本、紧凑的里程碑归档和版本化的语义账本。
• get_context 将静态锚点、动态仓库状态和活跃执行作为独立的 YAML 区域输出。

多个项目

在包含相关项目的文件夹中运行常规索引命令：

infimium index

Infimium 会从 pubspec.yaml、package.json、Cargo.toml 和 go.mod 等文件中检测直接项目根。它会显示检测到的角色和依赖关系，询问一次，然后创建 infimium.workspace.json，索引每个项目，并打开 Playground。

对于无人值守的设置：

infimium index --yes --no-playground

使用 --no-workspace 仅索引当前项目。工作区项目保持独立的记忆和 Git 状态，同时 get_context 会包含来自相关项目的均衡摘要和图关系。

Infimium - Playground

Infimium 将初始负载成本从约 1,460 个 token 降至每个符号 8 个 token。语义搜索首先返回 AST 签名；Agent 仅在需要时通过 expand_symbol 请求完整实现。

Full implementation   ~1,460 tokens
AST skeleton               ~8 tokens
Initial payload reduction  ~99.5%

这些是 Playground 参考值，并非宣称每个函数都具有相同大小。检查你自己已索引的仓库，并在本地比较 AST 优先检索与全文检索：

infimium playground

打开 Token Economics 查看你实际已索引符号的预估 token 差异。

隐私

代码、文档、嵌入、记忆、图数据、提示词、查询、文件路径和仓库名称均保留在本地。

Infimium 发送隐私安全的匿名生命周期遥测，以便我们了解设置成功率：

• init_started, init_completed
• doctor_run, doctor_passed
• index_started, index_completed, setup_completed
• serve_started, first_tool_call, playground_opened

遥测包含匿名安装 ID、Infimium 版本、操作系统、Node 主版本、时间戳和事件名称。它绝不包含代码、文件路径、仓库名称、提示词、搜索查询、记忆笔记、API 密钥或用户身份。

随时禁用它：

infimium telemetry off

或设置：

INFIMIUM_TELEMETRY=false

故障排除

常见问题与常见困惑

layer.md 在哪里？ 当你运行 infimium get-context 时，它会将保存的上下文直接打印到你的终端（stdout）。刷新会将项目范围的 YAML 存储在 Infimium 的本地数据目录下。要将保存的上下文导出到文件，请使用终端重定向：

infimium get-context > layer.md

为什么 Playground UI 显示 "Awaiting first agent interaction..."？ CURRENT TASK 跟踪器反映存储的项目上下文。运行 infimium update --task "Your task" 来刷新它；get-context 读取保存的快照。

如何格式化 infimium remember？ infimium remember 命令需要一条消息和一个 --type 标志（有效类型：note、progress、decision、blocker、index、plan）。如果你还希望它更新 Playground 中的活跃任务，请包含 --task 标志：

infimium remember "Added rate limiting" --type progress --task "Security Features"

数据库已被锁定

如果你看到 Failed to start Infimium: Database is locked，说明另一个 Infimium 实例正持有 SQLite 记忆数据库的锁。这种情况通常发生在 infimium playground 或 infimium watch 仍在另一个终端中运行时，你却在某个终端中手动执行 infimium index。只需在执行手动命令前先停止正在运行的进程（Ctrl+C）。

常规设置问题

运行：

infimium doctor

每个未通过的检查都会打印一条可直接复制粘贴的修复方案。如果设置仍然失败，请将以下提示词交给你的编码 Agent：

Set up Infimium in this repository. Install/start Ollama, pull nomic-embed-text,
run npx infimium init, run npx infimium index, and make all six
npx infimium doctor checks pass. Do not commit secrets.

贡献

请参阅 CONTRIBUTING.md。添加一门语言首先要从解析器测试夹具和提取测试开始。

在 MIT 许可证下，自托管永久免费。