内容
<p align="right"><b>English</b> · <a href="README.es.md">Español</a></p>
<p align="center">
<img src="https://raw.githubusercontent.com/n1x-technologies/n1x-cortex/main/docs/assets/hero.png" alt="N1X Cortex, the cited knowledge graph, for you and your agents" width="100%">
</p>
<p align="center">
<a href="https://www.npmjs.com/package/@n1x-technologies/cortex"><img alt="npm" src="https://img.shields.io/npm/v/@n1x-technologies/cortex?color=292929&label=npm"></a>
<img alt="node" src="https://img.shields.io/badge/node-%E2%89%A518-292929">
<img alt="MCP" src="https://img.shields.io/badge/MCP-ready-292929">
<a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-292929"></a>
<img alt="local-first" src="https://img.shields.io/badge/local--first-%E2%9C%93-292929">
</p>
<p align="center">
<b>将任何markdown文件夹或未记录的代码库转换为引用的、可查询的知识图。<br>
为<b>你</b>和你的<b>智能代理</b>，从任何CLI。</b>
</p>
```bash
npm i -g @n1x-technologies/cortex
```
---
## 什么是Cortex
大多数知识都存在于分散的markdown文件中（笔记、文档、维基），或者根本没有文档，只有一个代码库。人类可以阅读它；**人工智能代理无法信任它**（没有结构，没有出处）。Cortex解决了这个问题：它读取任何markdown库或整个未记录的代码库，创建一个**引用的笔记图**，这样人员和代理都知道**每个答案的来源**。
- 🧩 **原子化和连接**: 笔记变成一个由链接、类型笔记组成的图（wikilinks，frontmatter）。
- 📌 **设计引用**: 每个答案都指向其源笔记，这样你总是知道答案来自哪里。
- 🔒 **本地优先和私有**: 在你的机器上运行，在你的文件上。除非你说，否则什么都不会离开。
- 🤖 **智能代理原生（MCP）**: 配备MCP服务器，因此任何代理都可以查询并写回你的库作为工具。
<p align="center"><img src="https://raw.githubusercontent.com/n1x-technologies/n1x-cortex/main/docs/assets/flow.png" alt="Cortex在三个步骤中完成的操作：您的笔记或整个代码库→Cortex构建引用的图→您和您的代理询问并获得引用的答案" width="100%"></p>
## 为什么更便宜，为什么不猜测
想象你的知识库有**300页**。要回答一个问题，大多数设置都会将所有300页交给AI并希望得到答案。Cortex交给它**实际回答该问题的引用段落**。
<p align="center"><img src="https://raw.githubusercontent.com/n1x-technologies/n1x-cortex/main/docs/assets/metrics.png" alt="Cortex发送约1,340个引用上下文令牌，而不是213,409个（小159倍），并且基于引用的笔记模型制造的内容要少得多，100%引用，本地，可逆转" width="100%"></p>
- **每次问题阅读量减少约159倍**。在实际的213,000令牌知识库中，“阅读所有内容”花费约213,000令牌每个问题；而Cortex的引用答案花费**约1,340令牌**：这意味着**99.4%减少**。更快，更便宜。
- **它停止编造内容**。对于一个模型，询问它不知道的事实时，它给出了自信但错误的答案，频率为**25-63%**。给定Cortex的引用笔记，这个比例降至**0-13%**：它正确回答，或说“我不知道”，而不是猜测。
- **你可以随时检查**。每个答案都指向它引用的确切笔记。**100%引用**，逐字引用。
所有这些都在CLI上使用真实数据进行了实际测量，您可以在[`bench/`](bench/)中自己复制这些数字。
## 为什么有效
**任何代理，任何CLI，或不使用代理**。通过MCP从Claude Code、Copilot（代理模式）、Cursor、Cline等读取/查询和写回，或者使用您自己的密钥，不使用任何代理：
```bash
cortex atomize source.md --model anthropic:claude-3-5-sonnet --write
```
一种蒸馏方法驱动每条路径，因此无论谁在编写笔记，笔记内容都保持一致。
**指向未记录的代码库，它会自我记录**。
```bash
cortex bootstrap . --model anthropic:claude-3-5-sonnet --write
```
读取每个文件，包括代码，并将项目概念蒸馏成连接的笔记。 Dry-run（无 `--write`）预览文件计划 **免费，它不会调用模型**；整个运行可逆转，使用 `cortex undo`。
**引用，本地优先，可逆转**。每个答案都引用其源笔记；没有任何内容离开您的机器；每个写入都备份并可使用 `cortex undo`撤销。
## 用例
- **[加入旧版或未记录的代码库](docs/use-cases/onboard-a-repo.md)**: 指向Cortex并询问 *"身份验证是如何工作的？"* 而不是grep。每个答案都引用确切的文件。
- **[为您的智能代理提供真正的内存](docs/use-cases/agent-memory.md)**: 一个本地的、引用的、可逆转的长期大脑，任何MCP代理（Claude Code、Copilot、Cursor...）都可以读取和写入。
- **[团队的单一事实来源](docs/use-cases/team-knowledge-base.md)**: 一个可验证的知识库，许多人和代理共享，而不是分散的文档。
- **[自我记录的代码库](docs/use-cases/self-documenting-codebase.md)**: 随着代码的移动，实时文档会再生，因此它们永远不会过时。
- **[始终在线的Ambient Agent → Symbiont](docs/use-cases/symbiont.md)**: Cortex安装到代码库中，扫描代码，并保持引用的大脑与您的工作同步。
每个链接都指向一个简短的演练，查看所有[用例](docs/use-cases/)。
## 快速入门（30秒）
```bash
npm i -g @n1x-technologies/cortex # 或运行而无需安装：npx @n1x-technologies/cortex
cd my-vault # 任意的.md笔记文件夹
cortex init # 检测frontmatter，写入.cortex.json（+ gitignore缓存）
cortex status # 按类型/状态显示笔记 + 孤立的链接
cortex query "如何工作？" # 来自您自己的笔记的引用答案
cortex viz # 🌐 本地网页查看器，您的知识图
```
就是这样，不需要账号，不需要服务器，不需要云。
### 更新
在任何地方重新运行安装即可跳转到最新版本：
```bash
npm i -g @n1x-technologies/cortex@latest
```
## 从任意代理（MCP）使用
Cortex使用 **[模型上下文协议](https://modelcontextprotocol.io)**，因此任何支持MCP的代理，不仅是Claude Code，都可以将您的库用作 **引用知识源**，并可选地写回。
```bash
# 只读（默认），代理可以查询和读取您的库：
cortex mcp
# ⭐ 推荐，也让代理捕获知识写回为草稿（可逆转）：
cortex mcp --write
# 完整的策展人，草稿 + 推广 + 合并（结构性，仍然可逆转）：
cortex mcp --write=curate
```
写入是**启动时可选的**：代理不能自行启用或升级其自身范围。
| 模式 | 标志 | 代理可以执行的操作 |
|------|------|------------------------|
| **只读** | *(无)* | 查询和读取笔记。 |
| **草稿** ⭐ | `--write` | 读取 **+** 捕获：将来源蒸馏成 `_inbox/` 中的 `draft`，设置状态，撤销。 |
| **策展** | `--write=curate` | 草稿 **+** 将草稿从 `_inbox/` 推广并合并重复项。 |
每次写入都备份并可逆转（`cortex_undo`），`Markdown/`下的源代码永远不会被触碰，审计轨迹记录在 `.cortex/mcp-writes.log` 中。
> **进一步了解：** [**Symbiont**](docs/use-cases/symbiont.md)，环境代理模式，Cortex安装到代码库中，扫描代码，并保持引用的大脑与您的工作同步。
## 蒸馏或引导无需代理（自带密钥）
任何人都可以使用自己的模型进行原子化，不需要Claude Code，不需要MCP客户端：
```bash
export ANTHROPIC_API_KEY=... # 或OPENAI_API_KEY
cortex atomize Markdown/spec.md --model anthropic:claude-3-5-sonnet --write
```
与任何OpenAI兼容的端点一起工作，包括本地模型：
```bash
cortex atomize Markdown/spec.md --model openai-compat:llama3 --base-url http://localhost:11434/v1 --write
```
相同的蒸馏方法驱动每条路径，Claude的`/atomize`技能，任何MCP代理和此CLI，因此笔记内容一致，无论谁在蒸馏。 默认干燥运行；添加 `--write` 以提交。每次写入都可逆转，使用 `cortex undo`。
指向一个没有文档的代码库，它读取每个文件，包括代码，并将项目概念蒸馏成连接的原子笔记：
```bash
export ANTHROPIC_API_KEY=... # 或OPENAI_API_KEY
cortex bootstrap . --model anthropic:claude-3-5-sonnet --write
```
它尊重 `.gitignore`，跳过二进制文件和供应商文件夹，按文件流式传输进度，并将 `status: draft` 笔记写入 `_inbox/`。 默认干燥运行，运行而不 `--write` 列出它 *将* 蒸馏的文件，不调用任何模型：免费预览，然后再花费单个令牌。 `cortex undo` 删除运行创建的每个草稿，恢复那些更新现有笔记的运行，然后打开图谱，运行 `cortex viz`。 与任何OpenAI兼容的端点一起工作（ `--model openai-compat:llama3 --base-url http://localhost:11434/v1` ）。
## 命令
| 命令 | 它执行的操作 |
|---------|--------------|
| `cortex init` | 检测frontmatter字段，写入 `.cortex.json`，忽略 `.cortex/` 缓存。 |
| `cortex new <type> <id>` | 从 `_templates/<type>.md` （ `init` 播种一个启动器 `note` 模板）搭建一个笔记到类型的目录中，第一个笔记需要 `--dir`，然后它被学习（ `--title`/`--module`）。 |
| `cortex status` / `orphans` | 按类型/状态显示笔记；孤立的链接排名为“ atomize-next ”。 |
| `cortex query "..."` | 来自您笔记的引用答案（混合检索）。 `--json` （或 `/query` 技能）用于机器可读输出。 |
| `cortex viz` | 本地网页查看器，采用N1X品牌身份：交互式图谱，搜索，按颜色分类，动画焦点，邻居高亮显示，双向（进/出）链接面板，三态组过滤器，图谱/树视图切换，实时力控制（d3-force）和Mermaid架构导出。单击节点的 **打开笔记** 以在新标签页中阅读其渲染的markdown（ `/note/<id>`）。 |
| `cortex mcp install` | **一键安装** 到Claude Code（卸载以删除； `--write[=curate]` 注册写入者）。 |
| `cortex mcp` | **运行MCP服务器** 用于代理（stdio）。默认只读； `--write[=draft\|curate]` 暴露可逆的捕获/策展工具。 |
| `cortex embed` | 构建本地嵌入存储（启用语义搜索）。 |
| `cortex atomize <src>` | 将源蒸馏成草稿笔记（干燥运行； `--write`）。 `--model <provider:model>` 在没有代理的情况下运行蒸馏，自带密钥（ [见上](#蒸馏或引导无需代理-自带密钥)）。 |
| `cortex bootstrap [path]` | 蒸馏一个 **整个未记录的代码库**：每个合格的文件，包括代码，变成连接的草稿笔记，自带密钥（ [见上](#蒸馏或引导无需代理-自带密钥)）。 |
| `cortex gaps` / `dupes` / `verify` | 策展诊断。 `dupes` 默认按类型比较（ `--cross-type` 加宽）； `verify --all` 扫描整个库以查找不完整的笔记。 |
| `cortex merge <keep> <drop> --content-file <merged.md>` | 将近似重复对折叠成一个笔记，重定向传入链接（通过 `/dupes-merge` 技能）。 干燥运行； `--write`，可逆转。 |
| `cortex moc` / `doc` | 生成Map-of-Content笔记 / 品牌Typst PDF（ `doc --pdf`）。 |
| `cortex set-status <note> <status>` | 将笔记推进其生命周期（门控 `promote` 读取）。 干燥运行； `--write`。 |
| `cortex promote` | 将状态先进的草稿从 `_inbox/` 提升到精选目录中。 干燥运行； `--write`，可逆转。 |
| `cortex hook` · `pause` · `resume` | Claude Code自主钩子。 使用 `autonomy: auto-draft`/`full`，Stop钩子在后台将更改的源代码蒸馏到图谱中（可逆转）； `pause` 是终止开关。 |
| `cortex undo` | 反转最后写入。所有操作都可逆转。 |
## 它是如何工作的
Cortex建立在四个支柱上， **Atomize · Connect · Curate · AI Layer**：在一个引擎上，该引擎提供三个界面（CLI，本地查看器和MCP服务器）：
```mermaid
flowchart TB
V[("📁 Markdown vault<br/>notes · wikilinks · frontmatter")] --> ENG["⚙️ Cortex engine<br/>scan · graph · index · embed"]
ENG --> G["🕸️ note graph"]
ENG --> I["🔎 lexical index (TF-IDF)"]
ENG --> EM["🧠 embeddings<br/>(optional, local)"]
G --> S{{surfaces}}
I --> S
EM --> S
S --> CLI["⌨️ CLI"]
S --> VIZ["🌐 local viewer"]
S --> MCP["🤖 MCP server"]
CLI --> U["👤 you + 🤖 agents"]
VIZ --> U
MCP --> U
```
- **Atomize**：将源代码（markdown或代码）蒸馏成小型、单一思想的笔记，AI辅助，默认干燥运行，每次写入可逆转。
- **Connect**：wikilinks + frontmatter变成一个typed graph；孤立的链接和空白自动显示。原始源代码（ `Markdown/`）和笔记模板（ `_templates/`）被排除，因此它们永远不会作为节点出现。
- **Curate**：诊断（ `gaps`， `dupes`， `verify`）保持大脑健康； `merge` 将重复项折叠成一个笔记，可逆转。
- **AI Layer**：引用查询（混合词典 + 语义），MCP服务器和品牌文档生成器。
## 语义搜索（可选）
词典搜索开箱即用。对于基于含义的搜索（同义词，释义，跨语言ES↔EN），嵌入模型是一个 **可选对等方**，因此基础安装保持轻量：
```bash
npm i -g @xenova/transformers # 本地设备模型，不会离开您的机器
cortex embed # 构建存储（之后增量）
```
然后 `cortex query` 和 `cortex dupes` 变成混合（词典 + 语义），MCP服务器保持模型温暖。
## Roadmap
Cortex今天是 **开源本地引擎**：免费，您自己的，在您的机器上。这是更大的想法中的开放核心：
- **自主软件的可靠大脑**。随着团队将更多工作交给代理，这些代理需要一个 **单一事实来源**，他们可以信任和引用。Cortex是这一层，即 **大脑中的代理 / 自主软件工厂**，许多代理从（很快）写入同一个共享的可验证知识库。
- **始终本地**。Cortex保持开放，在您的机器上的引擎， vault 内容永远不会离开您的机器。下面的路线图都是Cortex；它通过加深本地引擎及其代理循环来增长，而不是锁定任何服务。
路径是增量的，因此不会有任何内容被丢弃。
## 路线图
- ✅ **引擎 + CLI**：图谱，状态，孤立的链接，引用查询，本地查看器。
- ✅ **AI原子化**：AI蒸馏笔记，可逆转的写入，状态门控推广。
- ✅ **策展 & 输出**：gaps/dupes/verify，MOC笔记，品牌PDF。
- ✅ **语义层**：本地嵌入，混合查询/重复项。
- ✅ **MCP服务器（读取）**： `cortex_query` + `cortex_get_note` 用于代理。
- ✅ **自主捕获（钩子）**: Stop钩子在后台将更改的源代码蒸馏到图谱中（可逆转）; 加上可逆转的重复 `merge`.
- ✅ **MCP写入/策展**： `cortex mcp --write[=draft|curate]` 暴露捕获&策展作为MCP工具，因此 *任何* 代理写回，默认只读，每次写入可逆转。
## 从源代码（贡献者）
```bash
git clone https://github.com/n1x-technologies/n1x-cortex.git
cd n1x-cortex/toolkit && npm install && npm run build
npm test`
```
