# 🧠 Cortex 实战教程：给 AI 装上本地记忆

> 如果你用 AI 写代码、做分析，你一定遇到过这些问题。这篇教程不讲空洞的概念，直接用真实场景告诉你：Cortex 是怎么解决这些问题的。

---

## 📖 这篇教程是写给谁的

| 如果你遇到这些问题 | 那这篇就是写给你的 |
|:-----------------|:-----------------|
| 在 Trae 里问项目内部问题，AI 总说"我无法访问你的本地文件" | ✅ |
| 每次都要把代码文件复制粘贴给 AI，才能让它理解上下文 | ✅ |
| 昨天和 AI 讨论好的方案，今天打开新对话它全忘了 | ✅ |
| 项目文档散落在不同地方，AI 找不到，自己也难找 | ✅ |
| 在飞机/地铁/野外没网的地方，AI 完全不能用 | ✅ |
| 同一个问题，反复问 AI 好几遍，因为它记不住 | ✅ |
| 团队协作时，成员 A 踩过的坑成员 B 又踩一遍 | ✅ |

**一句话概括：Cortex 让你的 AI 拥有永久记忆，能随时搜索你的全部本地项目。**

---

## 目录

- [场景一：AI 不知道你的代码库](#场景一ai-不知道你的代码库)
- [场景二：离线也能用的 AI 知识库](#场景二离线也能用的-ai-知识库)
- [场景三：AI 总是忘记之前的讨论](#场景三ai-总是忘记之前的讨论)
- [场景四：项目文档散落一地，AI 找不到](#场景四项目文档散落一地ai-找不到)
- [场景五：重复劳动——同样的问题反复问](#场景五重复劳动同样的问题反复问)
- [场景六：团队协作——知识不共享](#场景六团队协作知识不共享)
- [场景七：生产环境——把知识库变成服务](#场景七生产环境把知识库变成服务)
- [附录：命令速查](#附录命令速查)

---

## 场景一：AI 不知道你的代码库

### 痛点

你在 Trae 里问：

> "我们这个项目的商品管理模块，C5 商品的补货流程是怎么实现的？"

AI 的回答：

> "我无法访问你的本地项目文件，请把相关代码贴给我..."

然后你不得不去翻代码，找到好几个文件，一个个复制粘贴给 AI。一天下来，这种事情可能要重复十几遍。

### 解决方案

用 Cortex 把你的项目索引成 AI 可搜索的知识库。

**第一步：安装 Cortex**

```bash
# 已经装好了
cortex --help
```

**第二步：索引你的项目**

```bash
# 索引整个项目目录
cortex index e:\程序\魔盒系统\INFOSYS

# 或者索引你所有项目
cortex index e:\程序
```

**第三步：配置 Trae MCP**

在 Trae 设置 → MCP 服务器 → 添加：

| 字段 | 值 |
|:----|:----|
| 名称 | `Cortex` |
| 命令 | `E:\程序\Cortex\bin\cortex.exe` |
| 参数 | `mcp` |
| 类型 | `stdio` |

**第四步：回到 Trae，再问一次**

> "C5 商品的补货流程是怎么实现的？"

这次 AI 会自动调用 `cortex_search` 搜索你的代码库，然后基于搜索结果回答你。

### 效果

```
之前：翻文件 → 复制代码 → 粘贴给 AI → 等回答
之后：直接问 → AI 自动搜 → 秒回
每天省下：30 分钟到 2 小时的"文件搬运"时间
```

### 进阶技巧

```bash
# 开发时让 cortex 自动监听文件变更
cortex watch e:\程序\魔盒系统\INFOSYS

# 现在改了代码，AI 立即就能搜到新内容
# 不需要手动重建索引
```

---

## 场景二：离线也能用的 AI 知识库

### 痛点

你在飞机上想查一下项目的部署文档，打开笔记本却发现：

> 网络不通 → AI 工具连不上 → 知识库在云端 → 什么都搜不了

或者你在：

- **地铁通勤** — 信号断断续续，AI 回答到一半断网
- **出差路上** — 高铁隧道里没信号，想查的东西查不了
- **客户现场** — 客户内网没有互联网，你带的 AI 工具全变摆设
- **野外/偏远地区** — 根本没有网络覆盖

这时候你才发现：**所有依赖云端的 AI 工具，断网=废了**。而你的项目文档、代码、笔记都在本地，就是没有工具能搜。

### 解决方案

Cortex 是**100% 本地运行**的知识库引擎。

```
你的文件 → 本地索引（不联网） → 本地搜索（不联网） → 本地服务（不联网）
                               ↓
                        全程零外部依赖
```

**第一步：在联网时先把文档索引好**

```bash
# 在家/办公室有网时，把需要的项目都索引
cortex index e:\程序
cortex index e:\资料

# 索引完后，知识库已经完全存在本地磁盘上
cortex status
# Documents: 27142  ← 全在本地，不依赖任何云服务
```

**第二步：断网后照常使用**

```bash
# 所有命令完全离线工作
cortex search "部署 环境变量"         # 搜索知识库 ✅
cortex context "架构设计" --tokens 2000  # RAG 上下文 ✅
cortex status                           # 查看状态 ✅
cortex mcp                              # MCP 服务器 ✅（给本地 AI 用）
cortex serve                            # REST API 服务 ✅
```

**第三步：搭配本地 AI 使用**

如果 Trae 用的云端模型（如 Claude），离线时确实用不了。但你可以：

```bash
# 方案 A：先用 cortex 搜出需要的上下文，存成文件
cortex context "商品模块接口文档" --tokens 4000 > context.txt

# 然后把 context.txt 带到有网的地方贴给 AI

# 方案 B：搭配本地运行的 AI（如 Ollama + 本地模型）
# 在本地起一个 AI 服务，让它调用 cortex 的 MCP
cortex mcp   # cortex 作为知识库后端
ollama run qwen2.5   # 本地模型作为 AI 前端
```

**查看 Cortex 占用了多少空间：**

```bash
cortex usage
# Storage: 156 MB / 1 GB (15.2%)  ← 整个知识库才 156MB
# Tier:    free
```

### 效果

```
之前：断网 = AI 失能，文档查不了，代码搜不了
之后：断网 = 照常使用，全部本地搜索，零延迟
156MB 的知识库 ≈ 27,000 个文档，塞进手机都绰绰有余
```

### 技术原理

为什么 Cortex 能离线工作？

```
单二进制文件 34MB        → 不需要安装运行时
内置 SQLite FTS5        → 不需要外部数据库
零外部依赖              → 不需要 pip/npm/go
中文单字分词本地完成     → 不需要联网 API
配置热加载               → 改配置不需要重启
全量索引 18k 文件 40秒   → 一次索引，永久离线可用
```

### 进阶技巧

```bash
# 出差前批量索引需要的项目
cortex index --force e:\程序 --workers 32   # 快速重建
cortex index --force e:\资料 --workers 16

# 然后把资料文档的 U 盘也索引一遍，双重保险
cortex index D:\项目资料
```

---

## 场景三：AI 总是忘记之前的讨论

### 痛点

昨天你和 AI 讨论了半天的架构设计：

```
你：我们决定把商品模块拆成三个子模块：库存管理、定价引擎、补货策略
AI：好的，这是一个很好的架构拆分...
```

今天打开新对话：

```
你：帮我在商品模块里加一个功能
AI：好的，请描述一下你们的商品模块是什么样的？
你：（又开始从头解释...）
```

AI 会话是**无状态的**——每次新对话都是"失忆"状态。之前讨论过的技术决策，下次它全不记得。

### 解决方案

用 Cortex 的记忆系统，把重要的讨论结论持久化。

**方式一：在 Trae 中，让 AI 自动记忆**

配置好 MCP 后，AI 会自动调用 `cortex_memory_write` 和 `cortex_memory_search`。你只需要正常聊天就行，AI 会在合适的时机自动记笔记。

**方式二：手动写入重要信息**

```bash
# 把技术决策写进记忆
curl -X POST http://localhost:8080/v1/memory \
  -H "Content-Type: application/json" \
  -d '{
    "content": "2026-05-13 技术决策：商品模块拆分为库存管理、定价引擎、补货策略三个子模块，各自独立部署",
    "tags": ["architecture", "product-module", "decision"]
  }'

# 下次需要时，搜索记忆
curl -X GET "http://localhost:8080/v1/memory/search?q=商品模块 拆分&top_k=5"
```

**方式三：把项目文档转为记忆**

```bash
# 直接索引整个文档目录，所有文档变成可搜索的知识
cortex index e:\程序\魔盒系统\INFOSYS\docs

# 以后 AI 搜到相关内容会自动引用
```

### 效果

```
之前：AI 每次新对话都是失忆状态
之后：AI 可以"回忆"之前讨论过的所有内容
之前做过的技术决策、架构设计、API 约定 → AI 全记得
```

---

## 场景三：项目文档散落一地，AI 找不到

### 痛点

你的项目文档分布在不同地方：

```
e:\程序\魔盒系统\INFOSYS\README.md       — 项目介绍
e:\程序\魔盒系统\INFOSYS\docs\架构.md      — 架构设计
e:\程序\魔盒系统\账单\README.md             — 账单模块说明
e:\资料\学习\文档\API设计.md                 — API 规范
e:\资料\项目文档\部署指南.md                 — 部署流程
```

每次要找某个信息，你得想：

> "这个写在哪了来着？README 里还是单独的文档里？"

而且 AI 也找不到——它根本不知道这些文件存在。

### 解决方案

把所有项目文档一股脑索引给 Cortex，让 AI 替你找。

```bash
# 把整个工作目录和资料库都索引
cortex index e:\程序
cortex index e:\资料

# 查看索引了多少文档
cortex status
# Documents: 27142
```

然后问 AI：

> "我们的部署流程是什么？需要哪些环境变量？"

AI 会自动在所有索引文档中搜索，找到 `部署指南.md` 里的相关内容，直接回答你。

### 效果

```
之前：翻文件夹 → 猜文件名 → 打开看是不是 → 不是再找
之后：直接问 → AI 自动在所有文档里找到答案
```

### 搜索技巧

```bash
# 限制搜索范围，更精确
cortex search "部署 环境变量" --top-k 5

# 查看原始的 RAG 上下文（AI 会用它来自动回答）
cortex context "部署流程" --tokens 2000
```

---

## 场景四：重复劳动——同样的问题反复问

### 痛点

你经常需要查这些信息：

- "C5 冷藏柜的容积是多少？"
- "供应商 1688 的数据格式是什么？"
- "补货阈值怎么配置的？"

每次你要么去翻代码/文档，要么问 AI 但前提是你得把相关上下文发给它。同一个信息，一周可能要查好几次。

### 解决方案

把这些信息预先索引，让 AI 随时能搜到。

**第一步：确保文档已经索引**

```bash
cortex index e:\程序\魔盒系统
```

**第二步：在 Trae 中正常使用**

配置好 MCP 后，AI 会自动搜索。你只需要正常问就行：

> "C5 冷藏柜容积多少？"

AI 会自动：`cortex_search("C5 冷藏柜 容积")` → 找到技术规格页 → 回答"180L"。

**第三步：把常问的信息写成文档**

对于没有现成文档的知识，可以新建一个 `常见问题.md`：

```markdown
# 常见问题

## C5 冷藏柜
- 容积：180L
- 补货阈值：库存低于 10 台时触发补货
- 供应商：美的

## 账单系统
- ...
```

然后索引它：

```bash
cortex index e:\程序\魔盒系统\INFOSYS\docs\常见问题.md
```

### 效果

```
之前：同一个信息一周查 3 次，每次花 5 分钟
之后：直接问 AI，3 秒钟得到答案
一周省下：25 分钟，而且准确率 100%
```

---

## 场景五：团队协作——知识不共享

### 痛点

你是团队里对某个模块最熟悉的人。有人来问你：

> "这个接口的返回格式是什么？"
> "那个配置项是什么意思？"

你每次都要回答，或者让他们去翻文档。团队里每个人都在重复"认知成本"。

更糟糕的是——有人踩过的坑，另一个人还会再踩一遍。

### 解决方案

把团队知识库搭在共享位置，所有人都能搜。

**方式一：共享知识库目录**

把文档放在共享目录，团队每个人都在本地索引：

```bash
# 每个人在自己机器上执行
cortex index \\共享服务器\项目文档
```

**方式二：搭建中心化知识库服务**

```bash
# 在服务器上启动
cortex serve

# 然后团队所有成员通过 API 搜索
curl -X POST http://team-server:8080/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query":"商品接口返回格式","top_k":5}'
```

**方式三：把踩过的坑记入记忆**

```bash
# 遇到问题并解决后，记录到记忆系统
curl -X POST http://localhost:8080/v1/memory \
  -H "Content-Type: application/json" \
  -d '{
    "content": "坑：账单导入时 CSV 编码必须是 UTF-8，否则中文乱码。解决：在导入脚本开头加 BOM 检测",
    "tags": ["坑", "账单系统", "CSV"]
  }'

# 以后别人遇到类似问题，AI 会搜到这条记忆
```

### 效果

```
之前：同一个坑 N 个人踩，每次都要重新排查
之后：有人踩过坑 → 记录 → AI 自动提醒 → 别人不再踩
```

---

## 场景六：生产环境——把知识库变成服务

### 痛点

你已经把项目索引好了，在本地用得很爽。但你想：

- 在其他电脑上也能搜自己的知识库
- 让自动化脚本也能调用知识库
- 查看知识库的使用统计

### 解决方案

把 Cortex 当服务跑起来。

**启动 REST API 服务：**

```bash
cortex serve

# 输出：
# [INFO] starting REST API server  :8080
# [INFO] metrics server started     :9090
```

现在你可以从任何地方调用：

```bash
# 从其他应用搜索
curl -X POST http://localhost:8080/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query":"补货流程","top_k":3}'

# 写入自动化脚本
python -c "
import requests
r = requests.post('http://localhost:8080/v1/search',
    json={'query': '今日待处理订单', 'top_k': 10})
for result in r.json()['results']:
    print(result['chunk']['content'])
"
```

**开启自动备份：**

```yaml
# config.yaml
backup:
  auto_backup: true       # 每天自动备份
  max_backups: 30          # 保留 30 份
```

这样知识库每天自动备份，数据安全。

**配置监控：**

```bash
# Prometheus 指标
curl http://localhost:9090/metrics | grep cortex
# cortex_search_total 1234     — 搜索总次数
# cortex_index_total 5678      — 索引文件总数
```

### 效果

```
之前：知识库只能在自己机器上用
之后：知识库变成服务，任何设备/脚本都能调用
```

---

## 日常使用流程总结

把以上场景整合到日常工作流中：

### 🟢 第一天：初始化

```bash
# 索引所有项目
cortex index e:\程序
cortex index e:\资料

# 配置 Trae MCP（一次性的）
# 设置 → MCP 服务器 → 添加 cortex

# 完成，开始用
```

### 🟡 每天

```bash
# 开发时后台监听
cortex watch e:\程序

# 正常在 Trae 里写代码、问问题
# AI 自动搜索知识库，自动记忆重要信息
```

### 🔴 每周

```bash
# 去重，保持知识库精炼
cortex dedup

# 查看知识库状态
cortex status
```

### 🔵 遇到坑时

```bash
# 记录到记忆系统（AI 会替你做，也可以手动）
curl -X POST http://localhost:8080/v1/memory \
  -H "Content-Type: application/json" \
  -d '{"content":"解决方案...","tags":["坑","模块名"]}'
```

---

## 附录：命令速查

### 索引

| 命令 | 作用 |
|:----|:----|
| `cortex index <目录>` | 索引一个目录 |
| `cortex index --force <目录>` | 强制重新索引 |
| `cortex watch <目录>` | 监听目录，文件变更自动索引 |
| `cortex index --workers 32` | 加速索引（默认 16） |

### 搜索

| 命令 | 作用 |
|:----|:----|
| `cortex search <关键词>` | 搜索知识库 |
| `cortex search <关键词> --top-k 20` | 指定返回条数 |
| `cortex search <关键词> --json` | JSON 格式输出 |
| `cortex context <关键词>` | 获取 RAG 上下文 |

### 服务

| 命令 | 作用 |
|:----|:----|
| `cortex mcp` | 启动 MCP 服务器（给 AI 用） |
| `cortex serve` | 启动 REST API（给程序用） |
| `cortex serve` | 自动启用配置热加载 |

### 维护

| 命令 | 作用 |
|:----|:----|
| `cortex status` | 查看知识库状态 |
| `cortex usage` | 查看存储用量 |
| `cortex dedup` | 去重 |
| `cortex setup` | 配置向导 |
| `cortex version` | 版本信息 |

---

> 本教程基于 Cortex v3.3
> GitHub: [https://github.com/lh123aa/cortex](https://github.com/lh123aa/cortex)