cortex

Cortex——用于知识库的 RAG MCP

English | Français

Cortex 是一个 MCP（Model Context Protocol）服务，可对本地知识库进行语义搜索。它让 Claude、Codex 和 Gemini 能够在文档中找到合适的段落，而不浪费上下文窗口。搜索基于语义（按含义而非关键词），支持法语和英语。Cortex 在本地处理并索引知识库，不会发送其内容；MCP 客户端仍可能根据自身策略将请求的内容块传递给模型。 可选的 Confluence 写入器只会下载明确列入允许列表的空间；生成的 Markdown、向量索引和词法索引均保留在本地。

从 2026.0906.01 起，Companion 提供引导式主页、操作历史记录，以及通过单个页面或空间链接进行 Confluence 设置的功能。连接和范围测量确认仍保留在流程中；成功采集后会进行索引。请使用组合安装程序，以确保 Cortex 和 Companion 兼容。

自 2026.0909.02 起，如果子树枚举失败，Confluence 更新会保留已提供服务的版本，并在重试时应用已更改的目标／分类设置。搜索默认使用多语言向量检索；CLI 和 MCP 调用方可明确选择混合搜索或重排序搜索。升级后首次成功采集时会重新生成较早的发布修订版本，后续同步则会移除过时的索引条目。

引导式文档更新（2026.0909.00）

Companion 在 我的来源 中整合本地文档和 Confluence，只需一个 更新我的文档 操作。搜索预览窗口可调整大小，大型页面树会渲染可见行，取消准备审核时会保留草稿。准备状态现在会依据已保存的文档文件夹和配置，包括重启后。升级后请运行一次文档更新，为旧索引建立此项依据。请参阅发行说明。

无需枚举空间即可测量范围（2026.0907.00）

添加 Confluence 来源时，只需读取一次索引计数，即可测量页面、子树和整个空间的范围，无需逐页读取空间。对于一个有 5916 页的空间，这项测量耗时 3 min 19 s，超过了所有图形界面调用方的超时时间，因此 Companion 完全没有显示任何内容。现在它约一秒即可响应，输出的契约保持不变。

因此，两个整个空间的数字会相差一：解析出的页面不再计入空间总数，而没有可见页面的空间报告为零，而不是一。如果某个部署的搜索端点不返回总数，就无法测量范围；此时会报告为永久性故障，而非可重试故障。请参阅契约。

配套的 Companion 2026.0907.00 恢复了范围窗口的对比度（其选项此前使用系统文字颜色绘制），并停止将超时报告为连接故障，也不再建议通过增加延迟来解决问题后又悄悄还原。

Companion 中的来源管理（2026.0906.02）

工作流包括搜索、远程页面树、影响审核、基于依据的准备状态、保存并更新、撤销最近一次移除，以及恢复操作。请参阅契约。

配套版本 2026.0906.02 提供可见的 我的来源 卡片、预填的选择编辑器、确认后移除页面／空间，以及指向原始内容的浏览器链接。 移除操作只会更改 Cortex 的跟踪状态；成功采集和索引后，搜索结果才会反映这一更改。

移除最后一个来源时，会明确在 schema v2 或 v3 配置中写入 spaces = []。这个有意设置的空允许列表可用于创建空发布，并保留先前文档的墓碑记录。缺少 spaces 键仍属于配置不完整，采集会被拒绝。连接和凭据验证以及发布保护措施仍然适用。必须更新两个组件；已安装的 2026.0906.01 版本不支持此功能。

安装

Windows，无需 Python（推荐）

最简单的方式：使用一个安装程序安装 Cortex、Cortex Companion、无窗口的 Confluence 转换器和离线模型。无需单独安装 Python 或 .NET 运行时。

1. 从最新版本下载 Cortex-Setup.exe 和 SHA256SUMS。
2. 运行未签名的安装程序前，在 PowerShell 中使用 Get-FileHash .\Cortex-Setup.exe -Algorithm SHA256 计算其摘要，并确认它与 SHA256SUMS 中 Cortex-Setup.exe 对应的行完全匹配。
3. 确认后再双击运行。如果 SmartScreen 仍发出警告，请选择 More info，然后选择 Run anyway。
4. 选择存放文档的文件夹，保留 Index everything in this folder 选项，然后完成安装。安装完成后，Cortex Companion 会打开。只有在 Companion 中请求同步时才会开始索引。
5. 在 Companion 中打开 Settings，确认知识库文件夹。Companion 会自动检测随其安装的 Cortex 可执行文件。
6. 将文档放入该文件夹，打开 Local database，然后选择 Synchronize local documents。
7. 重启 AI 应用：Cortex 会作为 MCP 服务出现在其中。

之后，Companion 可以让你同步、安排任务、诊断和配置 Cortex，而无需使用终端。详情、静默模式和重新安装说明： Windows 安装。

独立压缩包（Windows x64、macOS Apple Silicon、Linux x64）

每个版本还会为每个平台提供一个 ZIP 压缩包。解压后会得到一个 cortex/ 文件夹，其中包含 cortex 或 cortex.exe 可执行文件（MCP 服务 + CLI，无需 Python）、运行时，以及所有内嵌依赖的许可证；请保留整个文件夹。请参阅独立分发。

从 PyPI 安装（Python，进阶）

py -m pip install --upgrade cortex-local-rag
cortex setup

此方式会安装 CLI 和 MCP 服务，但不包含 Cortex Companion。如果模型缓存为空，首次使用时会下载模型。

从源代码安装（开发）

:: From the folder where you cloned Cortex
install.bat

install.bat 和 sync.bat 是从源代码检出进行开发的方式，不是受支持的终端用户安装方式：install.bat 会安装 requirements.txt 中未锁定版本的依赖项，sync.bat 会按分区逐一索引文件夹，但不包括 Confluence 文档。要使用 Cortex，请改为安装 Cortex-Setup.exe 或独立压缩包。详情： 安装。

工作原理

Documents folder (.md, .pdf)       Optional Confluence writer (REST)
      |                                      |
      |                              current Markdown generation
      +------------------+-------------------+
                         |
                         v
  cortex sync           <- Split, hash, vectorize, update FTS5
                         |
                         v
  %LOCALAPPDATA%\Cortex\  <- ChromaDB + lexical.db
      |
      v
  cortex serve          <- MCP server (FastMCP)
      |
      v
  MCP clients           <- Claude / Codex / Gemini / Antigravity / LM Studio / Cursor / Windsurf / VS Code

嵌入模型是多语言 ONNX 模型 paraphrase-multilingual-MiniLM-L12-v2。Windows 安装程序会将其打包；如果本地缓存为空，从源代码安装或使用独立二进制文件时会下载该模型。

两种索引模式

• 整个文件夹（默认）：放入所选文件夹中的任何内容，无论是在根目录还是任何子文件夹中，都可搜索。无需配置。
• 分区（进阶）：将索引限制在指定名称的子文件夹中，你可以分别搜索这些文件夹（默认为 knowledge、projects、notes）。

这些模式适用于用户选择的文档文件夹。生成的摄取文档会与当前已发布的内容分开索引，使用 source_kind=doc 和 sources 分区。

详情：配置。

cortex 命令

安装的包提供一个命令：

子命令	用途
cortex setup	一次完成配置、索引和客户端注册（--kb-path、--yes、--no-index、--reset）。
cortex serve	运行 MCP 服务（供客户端使用）。
cortex sync	增量索引同步。
cortex search	在控制台中搜索索引（用于调试）。
cortex ingestion	显示来源状态以及是否需要补齐同步。
cortex confluence	交互式存储 PAT，或运行允许列表中的写入器。
cortex config	通过原子 JSON 契约读取或更改配置，尤其适用于 Companion。
cortex daemon	运行、检查或停止 [server] mode = "shared" 时使用的共享用户级服务（选择启用）。
cortex bundle	描述或验证加密的可移植归档。
cortex doctor	安装诊断（只读）。
cortex register / cortex unregister	在 MCP 客户端中添加或移除 Cortex。
cortex init	创建唯一的用户级配置。
cortex check	验证安装。

cortex --help 会说明所有子命令，cortex <command> --help 会说明其选项。无需提示的安装脚本如下：

cortex setup --yes --kb-path "D:\Documents\Knowledge"

暴露的 MCP 工具

工具	描述
cortex_search	默认进行多语言向量搜索；可选 retrieval_mode（vector、hybrid、rerank）。参数：query、section、top_k（1-10）、来源/作者筛选条件，以及发生/更新时间范围。
cortex_sync	触发对所选文件夹的增量同步；执行完整同步时，还会同步当前已发布的文档版本。
cortex_list_sections	列出包含的分区和“超出策略范围”的文件夹。
cortex_freshness	只读的知识库和摄取新鲜度摘要。参数：section（可选）、include_entries（默认为 false）。

文档

• 目录
• Windows 安装：统一的 Cortex + Companion + Confluence 转换器 + 模型安装程序、语料库选择、静默模式、 重新安装。
• 独立发行版：各平台归档和可复现构建。
• 从源代码安装：先决条件、MCP 客户端。
• 用户指南：同步、搜索、工具、doctor、日志。
• 常见问题：安装、本地数据、同步和诊断。
• 发行说明：各版本面向用户的变更以及 已发布历史记录说明。
• 技术变更日志：各版本的完整变更。
• 配置：config.toml、索引模式、 分区、数据目录、迁移。
• 摄取调度：来源状态、 补齐同步、重试和任务计划程序。
• 元数据 v2 迁移：结构化搜索 元数据、备份、迁移和还原。
• Confluence 写入器：允许列表中的 REST 摄取、 Windows 凭据管理器、转换和原子版本。
• 可复现安装：requirements.lock、 --require-hashes、重新生成锁定文件。
• 公开规范：MCP 接口、索引契约、数据、 分发和限制。
• 架构：端到端和技术选择。
• 安全：本地运行时、关闭遥测、 单写入者。

先决条件

路径	要求
Windows 安装程序	无需单独安装 Python 或 .NET 运行时。至少约 500 MB 可用空间（应用、模型和索引）。
独立归档	无需 Python。约 500 MB 可用空间（模型和索引）。
从源代码安装	Python 3.11 至 3.13。约 500 MB 可用空间。
客户端	Claude Desktop/Code、Codex、Gemini、Antigravity、LM Studio、Cursor、Windsurf 或 VS Code（支持 MCP）。

许可证

Apache 2.0。请参阅 LICENSE。

检索验证

请参阅验证指南，了解桌面 JSON 搜索约定、隔离的 FR/EN 相关性语料库、性能测量以及精确的配对提交检查。