Ctx Sys

ctx系统

用于AI编码助手的本地混合RAG。 索引您的代码库，使用语义+关键字+图形检索进行搜索，并让您的AI助手深入了解项目——所有这些都在Ollama本地运行。

npm install -g ctx-sys

为什么选择ctx-sys？

AI编码助手受到上下文窗口的限制。他们看不到你的整个代码库，他们忘记了你昨天讨论的内容，他们错过了文件之间的连接。ctx-sys通过充当 *聪明的图书管理员* --它为你的代码建立索引，理解符号之间的关系，并在你的人工智能需要时准确检索正确的上下文。

• 混合动力RAG --将向量搜索、关键字/FTS5和图遍历与倒排融合相结合
• 本地优先 --你的代码永远不会离开你的机器。Ollama处理嵌入和摘要
• 代码感知 --树型AST解析提取函数、类、导入和关系
• 适用于任何MCP客户端 --Claude Desktop、Claude Code、Cursor或任何与MCP兼容的工具

快速入门（5分钟）

1.安装

# Install ctx-sys
npm install -g ctx-sys

# Install and start Ollama (for embeddings)
# 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

这将使用树形图解析您的代码，使用Ollama生成嵌入，并对任何markdown文档进行索引——所有这些都在一个命令中完成。

3.搜索

# Semantic + keyword hybrid search
ctx-sys search "how does authentication work"

# Assembled context with source expansion
ctx-sys context "error handling in the API layer"

# Use HyDE for better conceptual search
ctx-sys search "database connection pooling" --hyde

4.连接到您的AI助手

添加ctx-sys作为MCP服务器。对于 克劳德桌面，添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

对于 克劳德代码，添加到MCP设置中：

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

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

运作原理

Your Code                  ctx-sys                         AI Assistant
─────────                  ───────                         ────────────
  .ts .py .rs    ──→   AST Parse (tree-sitter)
  .md .html      ──→   Document Chunking
                        ↓
                   Entity Extraction
                   (functions, classes, imports)
                        ↓
                   Embed with Ollama              ←──  "How does auth work?"
                   (mxbai-embed-large)                        ↓
                        ↓                              context_query
                   ┌─────────────┐                          ↓
                   │  SQLite DB  │               ┌─────────────────────┐
                   │  + FTS5     │──────────────→│  Hybrid Search      │
                   │  + vec0     │               │  • Vector similarity│
                   │  + Graph    │               │  • FTS5 keyword     │
                   └─────────────┘               │  • Graph traversal  │
                                                 └─────────┬───────────┘
                                                           ↓
                                                    Rank & Assemble
                                                           ↓
                                                  Relevant context with
                                                  source attribution

CLI参考

核心命令

ctx-sys init [directory]          # Initialize project config
ctx-sys index [directory]         # Index code + docs + embeddings
ctx-sys search             # Hybrid search (semantic + keyword)
ctx-sys context            # Assembled context with expansion
ctx-sys status [directory]        # Project info and health checks
ctx-sys serve                     # Start MCP server
ctx-sys watch [directory]         # Watch files and auto-reindex

关键标志

# Index
ctx-sys index --no-doc            # Skip document indexing
ctx-sys index --no-embed          # Skip embedding generation
ctx-sys index --force             # Re-index everything from scratch

# Search
ctx-sys search "query" --hyde     # Use HyDE for conceptual queries
ctx-sys search "query" --limit 20 # Control result count
ctx-sys search "query" --no-semantic  # Keyword-only search

# Context
ctx-sys context "query" --max-tokens 8000  # Token budget
ctx-sys context "query" --no-expand        # Skip context expansion
ctx-sys context "query" --hyde             # HyDE-enhanced retrieval

# Status
ctx-sys status --check            # Full health diagnostics

子指令

# Entity management
ctx-sys entity list               # List indexed entities
ctx-sys entity stats              # Type breakdown
ctx-sys entity get            # Entity details

# Relationship graph
ctx-sys graph query       # Traverse relationships
ctx-sys graph stats               # Graph statistics

# Embeddings
ctx-sys embed run                 # Generate/update embeddings
ctx-sys embed status              # Coverage report

# Summarization
ctx-sys summarize run             # Generate LLM summaries
ctx-sys summarize status          # Coverage report

# Sessions & memory
ctx-sys session list              # Conversation sessions
ctx-sys session messages [id]     # View session messages

# Knowledge bases
ctx-sys kb create           # Package as shareable .ctx-kb
ctx-sys kb install          # Install a knowledge base

# Debug
ctx-sys debug health              # System health check
ctx-sys debug inspect             # Database tables
ctx-sys debug export        # Export project data

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}  # Optional cloud fallback

支持的语言

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

需求

• Node.js 18+
• 奥拉玛 （用于局部嵌入和汇总）

- mxbai-embed-large:latest --嵌入模型（1024维，自动检测） - qwen3:0.6b --摘要（可选） - gemma3:12b --HyDE查询扩展（可选）

建筑

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

• 实体 --代码符号、文档部分、对话消息
• 关系 --包含、导入、调用、扩展、实现（从AST自动提取）
• 矢量 --通过sqlite-vec嵌入实现快速KNN搜索
• FTS5 --BM25排名的全文搜索
• 会话 --具有决策跟踪功能的对话历史记录

搜索使用倒排融合将所有四种检索策略（向量、FTS、图、启发式重新排序）结合起来。高级功能包括HyDE查询扩展、查询分解、检索门控和智能上下文扩展。

从源头构建

git clone https://github.com/davidfranz/ctx-sys.git
cd ctx-sys
npm install
npm run build
npm link    # Makes ctx-sys available globally

贡献

欢迎捐款。看 白皮书 有关架构细节和 网站 获取完整文档。

许可证

麻省理工学院