index1

面向编程智能体（coding agents）的 AI 记忆系统，采用 BM25 + 向量混合搜索。提供 6 个 MCP 工具，支持智能化的代码/文档检索与认知事实记录。

功能概述

• 双模记忆：语料库（代码索引）+ 认知记忆（情景化事实）
• 混合搜索：BM25 全文检索 + 向量语义搜索，采用 RRF（Reciprocal Rank Fusion）融合策略
• 结构感知分块：支持 Markdown、Python、Rust、JavaScript 和纯文本格式
• MCP Server：提供 6 个工具（recall、learn、read、status、reindex、config）
• 针对 CJK 优化：自动检测中文/日文/韩文查询，并动态调整权重
• 内置 ONNX 嵌入模型：开箱即用向量搜索能力，无需依赖 Ollama
• 优雅降级：即使无任何嵌入服务，仍可退化为纯 BM25 模式运行

安装

# 推荐方式
pipx install index1

# 或使用 pip 安装
pip install index1

# 或通过 npm 安装（自动安装对应 Python 包）
npx index1@latest

一键插件配置：

index1 setup                 # 自动配置 hooks + MCP（适配 Claude Code）

验证安装：

index1 --version
index1 doctor        # 检查运行环境

配置 MCP

在项目根目录下创建 .mcp.json 文件：

{
  "mcpServers": {
    "index1": {
      "type": "stdio",
      "command": "index1",
      "args": ["serve"]
    }
  }
}

若 index1 不在 PATH 中，请使用 which index1 输出的完整路径。

添加搜索规则

将以下内容添加至项目中的 .claude/CLAUDE.md：

## 搜索策略

本项目已配置 index1 MCP Server（含 recall 及其余 5 个工具）。进行代码搜索时：

1. 已知标识符（函数/类/文件名）→ 直接使用 Grep/Glob（耗时约 4ms）
2. 探索性问题（如“XX 是如何工作的？”）→ 优先调用 recall，再用 Grep 补充细节
3. 使用中/日/韩文查询英文代码 → 必须使用 recall（Grep 无法跨语言匹配）
4. 高频关键词（预期匹配结果 ≥ 50 条）→ 优先使用 recall（节省 90% 以上上下文开销）

效果对比：

未启用规则：Grep "search" → 返回 881 行 → 占用 35,895 tokens  
启用规则：recall        → 返回 5 条摘要 → 占用 460 tokens（节省率达 97%）

索引项目

index1 index ./src ./docs    # 索引源码与文档目录
index1 status                # 查看索引统计信息
index1 search "your query"   # 测试搜索功能

可选：多语言能力增强

index1 v2 内置 ONNX 嵌入模型（bge-small-en-v1.5）。如需更优的多语言支持，请执行：

curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text           # 标准模型，270MB
# 或
ollama pull bge-m3                     # CJK 场景最优，1.2GB

index1 config embed_backend ollama
index1 doctor                          # 验证配置是否生效

不安装 Ollama 时，内置 ONNX 嵌入模型仍可直接提供向量搜索能力。

Web UI

index1 web                   # 在端口 6888 启动 Web UI
index1 web --port 8080       # 指定自定义端口

MCP 工具参考

故障排查