GZOO Cortex

面向开发者的本地优先知识图谱。 监视您的项目文件，使用大模型提取实体和关系，并允许您使用自然语言查询所有项目的信息。

“我在各个项目中做过哪些架构决策？”

Cortex 可以从您的 README、TypeScript 文件、配置文件和对话导出中找到决策，然后结合来源引用为您合成答案。

为什么选择它

您同时处理多个项目。决策、模式和上下文分散在数百个文件中。您会忘记三个月前做出的决定。您会重复解决在另一个仓库中已经解决过的问题。

Cortex 会监视您的项目目录，自动提取知识，并在您需要时将其呈现给您。

Related MCP server: Graft

功能特性

• 监视您的项目文件（md, ts, js, json, yaml）的变更

• 提取实体：决策、模式、组件、依赖项、约束、待办事项

• 推断跨项目的实体关系

• 检测决策冲突时的矛盾点

• 查询支持自然语言，并提供来源引用

• 路由智能切换云端与本地大模型

• 尊重隐私 — 受限项目的数据绝不会离开您的机器

• Web 仪表盘提供知识图谱可视化、实时动态和查询浏览器

• MCP 服务器可与 Claude Code 直接集成

快速开始

1. 安装

npm install -g @gzoo/cortex

或从源码安装：

git clone https://github.com/gzoonet/cortex.git
cd cortex
npm install && npm run build && npm link

2. 设置

运行交互式向导：

cortex init

它将引导您完成：

• 大模型提供商 — Anthropic、Google Gemini、DeepSeek、Groq、OpenRouter 或 Ollama（本地）

• API 密钥 — 安全保存至 ~/.cortex/.env

• 路由模式 — 云端优先、混合模式、本地优先或仅限本地

• 监视目录 — Cortex 应监视哪些目录

• 预算限制 — 每月大模型支出上限

配置存储在 ~/.cortex/cortex.config.json 中。API 密钥存放在 ~/.cortex/.env 中。

3. 注册项目

cortex projects add my-app ~/projects/app
cortex projects add api ~/projects/api
cortex projects list                       # verify

4. 监视与查询

cortex watch                               # start watching for changes
cortex query "what caching strategies am I using?"
cortex query "what decisions have I made about authentication?"
cortex find "PostgreSQL" --expand 2
cortex contradictions

5. Web 仪表盘

cortex serve                               # open http://localhost:3710

排除文件与目录

Cortex 默认忽略 node_modules、dist、.git 和其他常见目录。若要添加更多：

cortex config exclude add docs             # exclude a directory
cortex config exclude add "*.log"          # exclude by pattern
cortex config exclude list                 # see all excludes
cortex config exclude remove docs          # remove an exclude

工作原理

Cortex 在每次文件变更时运行流水线：

1. 解析 — 文件内容由语言感知解析器（代码使用 tree-sitter，Markdown 使用 remark）进行分块

2. 提取 — 大模型识别实体（决策、组件、模式等）

3. 关联 — 大模型推断新旧实体之间的关系

4. 检测 — 自动标记矛盾和重复项

5. 存储 — 实体、关系和向量存入 SQLite + LanceDB

6. 查询 — 自然语言查询搜索图谱并合成答案

所有数据保留在本地 ~/.cortex/ 中。只有大模型 API 调用会离开您的机器（受限项目绝不会发送）。

大模型提供商

Cortex 是提供商无关的。它支持：

• Anthropic Claude (Sonnet, Haiku) — 通过原生 Anthropic API

• Google Gemini — 通过兼容 OpenAI 的 API

• DeepSeek (Reasoner, Chat) — 强大的推理能力，性价比极高

• Groq — 快速推理，提供免费层级

• 任何兼容 OpenAI 的 API — OpenRouter、本地代理等

• Ollama (Mistral, Llama 等) — 完全本地化，无需云端

路由模式

混合模式将高频任务（实体提取、排序）路由至 Ollama，将推理密集型任务（关系推断、查询）路由至您的云端提供商。

要求

• Node.js 20+

• 大模型 API 密钥（用于云端模式）— Anthropic、Google Gemini、DeepSeek、Groq 或任何兼容 OpenAI 的提供商

• Ollama（用于混合/本地模式）— 安装

配置

所有配置位于 ~/.cortex/cortex.config.json。API 密钥位于 ~/.cortex/.env。

cortex config list                       # see all non-default settings
cortex config set llm.mode hybrid        # switch routing mode
cortex config set llm.budget.monthlyLimitUsd 10  # set budget
cortex config exclude add vendor         # exclude a directory from watching
cortex privacy set ~/clients restricted  # mark directory as restricted

完整配置参考：docs/configuration.md

命令

完整 CLI 参考：docs/cli-reference.md

Web 仪表盘

运行 cortex serve 以在 http://localhost:3710 打开完整的 Web 仪表盘，包含：

• 仪表盘首页 — 图谱统计、近期活动、实体类型分布

• 知识图谱 — 交互式 D3-force 图谱，支持聚类，点击即可探索

• 实时动态 — 通过 WebSocket 实时查看文件变更和实体提取事件

• 查询浏览器 — 支持流式响应的自然语言查询

• 矛盾解决器 — 查看并解决冲突的决策

MCP 服务器 (Claude Code 集成)

Cortex 包含一个 MCP 服务器，以便 Claude Code 可以直接查询您的知识图谱：

claude mcp add cortex --scope user -- npx @gzoo/cortex mcp

这为 Claude Code 提供了 12 个工具：

架构

包含八个包的 Monorepo：

• @cortex/core — 类型、EventBus、配置加载器、错误类

• @cortex/ingest — 文件解析器（tree-sitter + remark）、分块器、监视器、流水线

• @cortex/graph — SQLite 存储、LanceDB 向量、查询引擎

• @cortex/llm — Anthropic/Gemini/OpenAI 兼容/Ollama 提供商、路由、提示词、缓存

• @cortex/cli — 包含 18 个命令的 Commander.js CLI

• @cortex/mcp — 模型上下文协议服务器 (stdio 传输，12 个工具)

• @cortex/server — Express REST API + WebSocket 中继

• @cortex/web — React + Vite + D3 Web 仪表盘

架构文档：docs/

隐私与安全

• 被归类为 restricted（受限）的文件绝不会发送给云端大模型

• 敏感文件 (.env, .pem, .key) 会被自动检测并拦截

• API 密钥在发送至云端前会被扫描并脱敏

• 所有数据存储在本地 ~/.cortex/ — 不会向外部发送任何数据

完整安全架构：docs/security.md

构建技术栈

• SQLite (通过 better-sqlite3) — 实体和关系存储

• LanceDB — 用于语义搜索的向量嵌入

• Anthropic Claude — 云端大模型提供商

• Google Gemini — 云端大模型提供商 (通过兼容 OpenAI 的 API)

• DeepSeek — 云端大模型提供商 (推理 + 对话)

• Groq — 快速云端推理

• Ollama — 本地大模型推理

• tree-sitter — 语言感知文件解析

• Chokidar — 跨平台文件监视

• Commander.js — CLI 框架

• React + Vite — Web 仪表盘

• D3 — 知识图谱可视化

贡献

请参阅 CONTRIBUTING.md 获取指南。

许可证

MIT — 请参阅 LICENSE

关于

由 GZOO 构建 — 一个 AI 驱动的业务自动化平台。

Cortex 最初是一个用于在多个客户项目间维护上下文的内部工具。我们将其开源，因为每个处理多个项目的开发者都会面临上下文丢失的问题，我们认为这种方法——自动文件监视 + 知识图谱 + 自然语言查询——是解决该问题的正确途径。