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:latest2.为你的项目建立索引
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" --hyde4.连接到您的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 attributionCLI参考
核心命令
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 dataMCP工具
当作为MCP服务器连接时，ctx-sys公开了12个基于动作的工具：
| 工具 | 动作 | 它的作用 |
|---|---|---|
| 上下文查询 | *（独立）* | 具有源属性的混合RAG检索 |
| 实体 | 添加、获取、搜索、删除 | 管理代码和文档实体 |
| 索引 | 代码库、文档、同步、状态 | 解析和索引代码和文档 |
| 图 | 链接、查询、统计 | 导航实体关系 |
| 会话 | 创建、列出、存档、总结 | 会话生命周期 |
| 消息 | 存储、历史记录 | 会话间的对话消息 |
| 决定 | 搜索、创建 | 架构决策跟踪 |
| 检查点 | 保存、加载、列出、删除 | 代理状态持久化 |
| 记忆 | 溢出、召回、状态 | 热/冷内存层管理 |
| 反思 | 存储、查询 | 跨会话学习和课程 |
| 项目 | 创建、列出、设置活动、删除 | 多项目管理 |
| 钩子 | install，impact report | Git钩子集成 |
配置
项目配置(.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支持的语言
| 语言 | 解析 | 提取实体 |
|---|---|---|
| types/JavaScript | 树形图 | 函数、类、方法、接口、类型、导入 |
| Python | 树形图 | 函数、类、方法、导入 |
| Rust | 树保姆 | 函数、结构、impls、特征、导入 |
| Go | 树保姆 | 函数、结构、方法、接口、导入 |
| Java | 树形图 | 类、方法、接口、导入 |
| C/C++ | 树形图 | 函数、类、结构、枚举、命名空间、#includes |
| C# | 树形图 | 类、接口、结构、记录、枚举、方法、用法 |
文档（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贡献
许可证
麻省理工学院