Ctx Sys

🚀 ctx-sys

专为AI编码助手打造的本地混合检索增强生成（RAG）解决方案。对代码库进行索引，通过语义、关键词和图检索进行搜索，让AI助手深入理解项目 — 一切都在本地借助Ollama运行。

🚀 快速开始

1. 安装

# 安装ctx-sys
npm install -g ctx-sys

# 安装并启动Ollama（用于嵌入）
# macOS: brew install ollama
# Linux: curl -fsSL https://ollama.com/install.sh | sh
ollama serve &
ollama pull mxbai-embed-large:latest

2. 为项目建立索引

cd your-project
ctx-sys init
ctx-sys index

此命令会使用tree-sitter解析代码，借助Ollama生成嵌入向量，并对所有Markdown文档建立索引。

3. 搜索

# 语义 + 关键词混合搜索
ctx-sys search "how does authentication work"

# 带源扩展的上下文组装
ctx-sys context "error handling in the API layer"

# 使用HyDE进行更好的概念搜索
ctx-sys search "database connection pooling" --hyde

4. 连接到AI助手

将ctx-sys作为MCP服务器添加。对于 Claude Desktop，添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "ctx-sys": {
      "command": "ctx-sys",
      "args": ["serve"]
    }
  }
}

对于 Claude Code，添加到MCP设置中：

{
  "mcpServers": {
    "ctx-sys": {
      "command": "ctx-sys",
      "args": ["serve"]
    }
  }
}

现在，你的AI助手可以使用12种基于操作的工具来搜索代码库、查询关系图、管理对话记忆等。

✨ 主要特性

• 混合RAG — 结合向量搜索、关键词/FTS5和图遍历，并采用互逆排名融合。
• 本地优先 — 代码不会离开本地机器。Ollama负责嵌入和摘要生成。
• 代码感知 — 通过tree-sitter抽象语法树（AST）解析提取函数、类、导入和关系。
• 与任何MCP客户端兼容 — 可与Claude Desktop、Claude Code、Cursor或任何支持MCP的工具配合使用。

📦 安装指南

npm install -g ctx-sys

💻 使用示例

基础用法

# 安装ctx-sys
npm install -g ctx-sys

# 安装并启动Ollama（用于嵌入）
# macOS: brew install ollama
# Linux: curl -fsSL https://ollama.com/install.sh | sh
ollama serve &
ollama pull mxbai-embed-large:latest

高级用法

# 为项目建立索引
cd your-project
ctx-sys init
ctx-sys index

# 语义 + 关键词混合搜索
ctx-sys search "how does authentication work"

# 带源扩展的上下文组装
ctx-sys context "error handling in the API layer"

# 使用HyDE进行更好的概念搜索
ctx-sys search "database connection pooling" --hyde

📚 详细文档

CLI参考

核心命令

ctx-sys init [directory]          # 初始化项目配置
ctx-sys index [directory]         # 为代码、文档和嵌入向量建立索引
ctx-sys search <query>            # 混合搜索（语义 + 关键词）
ctx-sys context <query>           # 带扩展的上下文组装
ctx-sys status [directory]        # 项目信息和健康检查
ctx-sys serve                     # 启动MCP服务器
ctx-sys watch [directory]         # 监控文件并自动重新索引

关键标志

# 索引
ctx-sys index --no-doc            # 跳过文档索引
ctx-sys index --no-embed          # 跳过嵌入向量生成
ctx-sys index --force             # 从头开始重新索引所有内容

# 搜索
ctx-sys search "query" --hyde     # 对概念查询使用HyDE
ctx-sys search "query" --limit 20 # 控制结果数量
ctx-sys search "query" --no-semantic  # 仅进行关键词搜索

# 上下文
ctx-sys context "query" --max-tokens 8000  # 令牌预算
ctx-sys context "query" --no-expand        # 跳过上下文扩展
ctx-sys context "query" --hyde             # 使用HyDE增强检索

# 状态
ctx-sys status --check            # 全面健康诊断

子命令

# 实体管理
ctx-sys entity list               # 列出已索引的实体
ctx-sys entity stats              # 类型细分
ctx-sys entity get <id>           # 实体详情

# 关系图
ctx-sys graph query <entity>      # 遍历关系
ctx-sys graph stats               # 图统计信息

# 嵌入向量
ctx-sys embed run                 # 生成/更新嵌入向量
ctx-sys embed status              # 覆盖率报告

# 摘要生成
ctx-sys summarize run             # 生成大语言模型摘要
ctx-sys summarize status          # 覆盖率报告

# 会话与记忆
ctx-sys session list              # 对话会话
ctx-sys session messages [id]     # 查看会话消息

# 知识库
ctx-sys kb create <name>          # 打包为可共享的.ctx-kb文件
ctx-sys kb install <file>         # 安装知识库

# 调试
ctx-sys debug health              # 系统健康检查
ctx-sys debug inspect             # 数据库表
ctx-sys debug export <file>       # 导出项目数据

MCP工具

当作为MCP服务器连接时，ctx-sys提供12种基于操作的工具：

配置

项目配置 (.ctx-sys/config.yaml)

project:
  name: my-project

indexing:
  ignore:
    - node_modules
    - dist
    - .git

embeddings:
  provider: ollama
  model: mxbai-embed-large:latest

summarization:
  provider: ollama
  model: qwen3:0.6b

hyde:
  model: gemma3:12b

全局配置 (~/.ctx-sys/config.yaml)

database:
  path: ~/.ctx-sys/ctx-sys.db

providers:
  ollama:
    base_url: http://localhost:11434
  openai:
    api_key: ${OPENAI_API_KEY}  # 可选的云备用方案

支持的语言

文档（Markdown、HTML、YAML、JSON、TOML、PDF、CSV、XML、纯文本）也会进行语义分块索引。

要求

• Node.js 18+
• Ollama（用于本地嵌入和摘要生成）
  • mxbai-embed-large:latest — 嵌入模型（1024维，自动检测）
  • qwen3:0.6b — 摘要生成（可选）
  • gemma3:12b — HyDE查询扩展（可选）

架构

ctx-sys将所有数据存储在一个SQLite数据库中，包含：

• 实体 — 代码符号、文档章节、对话消息
• 关系 — CONTAINS、IMPORTS、CALLS、EXTENDS、IMPLEMENTS（从AST自动提取）
• 向量 — 通过sqlite-vec实现的嵌入向量，用于快速K近邻搜索
• FTS5 — 基于BM25排名的全文搜索
• 会话 — 带决策跟踪的对话历史

搜索结合了四种检索策略（向量、FTS、图、启发式重排序），采用互逆排名融合。高级功能包括HyDE查询扩展、查询分解、检索门控和智能上下文扩展。

从源代码构建

git clone https://github.com/davidfranz/ctx-sys.git
cd ctx-sys
npm install
npm run build
npm link    # 使ctx-sys全局可用

贡献

欢迎贡献代码。有关架构细节，请参阅白皮书，完整文档请访问网站。

📄 许可证

MIT