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