内容
# 皮层
用于 AI 编程代理的持久、分层内存。作者在类似 Obsidian 的知识库中记录笔记；皮层将它们提炼成代理可消费的文件，并在运行时通过 MCP 服务器将它们提供给您的代理 — 因此，您的代理在每次对话中都会出现，已经了解您的偏好、模式和项目。
```
构建 （知识库 → 代理）： 笔记 → 提炼.py → 核心上下文.md + 内存.json
捕获 （代理 → 知识库）： 代理 → 内存写入 → 笔记写入 → 提炼.py（自动）
```
## 一条命令即可开始
需要 **Python 3.10+** 和 **Node 18+**。
```bash
git clone https://github.com/JaySmith/Cortex-AI.git cortex-ai
cd cortex-ai
./setup.sh
```
`setup.sh` 是交互式的：它会提示您输入 **知识库路径** 和 **开放代码技能目录**（按 Enter 键接受显示的默认值 — 捆绑的示例知识库和 `~/.config/opencode/skills`）。然后，它将 Python 依赖项安装到 `.venv` 中，构建 MCP 服务器，生成 `<vault>/_sync/cortex.yaml`，运行第一个提炼，安装 `cortex-ai` 技能，并打印要粘贴到代理的确切 MCP 配置。您将立即在 `<vault>/_sync/distilled/` 中获得可用的提炼输出。
要跳过提示（脚本/CI），请将知识库作为参数传递和/或设置环境变量：
```bash
./setup.sh /path/to/your/vault
# 或完全非交互式：
VAULT_ROOT=/path/to/vault OPENCODE_SKILLS_DIR=~/.config/opencode/skills ./setup.sh
```
## 将其连接到您的代理
`setup.sh` 在最后打印了两个代理的即用代码段。总之：
**开放代码** (`opencode.jsonc`)：
```jsonc
"mcp": {
"cortex": {
"type": "local",
"command": ["node", "<repo>/mcp/cortex/build/index.js"],
"enabled": true,
"environment": {
"MEMORY_JSON": "<vault>/_sync/distilled/memory.json",
"VAULT_ROOT": "<vault>",
"DISTILL_SCRIPT": "<repo>/distill.py",
"DISTILL_PYTHON": "<repo>/.venv/bin/python"
}
}
}
```
还将 `<vault>/_sync/distilled/opencode/core-context.md` 添加到开放代码的 `"instructions"` 数组中（提炼器可以自动连接此项 — 请参见 [docs/QUICKSTART.md](docs/QUICKSTART.md)）。
**Claude Desktop** (`claude_desktop_config.json`)：在 `mcpServers.cortex` 下使用相同的环境变量 — `setup.sh` 会打印完整的代码段。
## 笔记如何路由
每个笔记的 `tier` 前置元信息决定了它的去向：
| 层级 | 行为 | 用途 |
|------|----------|---------|
| `core` | 急切 — 连接到 `core-context.md`，始终加载 | 首选项、角色、固定规则 |
| `skill:<name>` | 延迟 — 嵌入 `skills/<name>/reference.md` | 重知识，仅在该技能运行时加载 |
| `project` | 延迟 — 每个项目一个文件 | 项目目标、状态、路线图 |
| `vault-only` | 从不提炼 | 会话笔记、草稿、日志 |
最少的前置元信息：
```yaml
---
id: my-note
type: knowledge # knowledge | entity | feedback | decision | session | log
tier: core # core | skill:<name> | project | vault-only
aliases: ["Human Readable Title"]
---
```
完整规范：[docs/VAULT_SCHEMA.md](docs/VAULT_SCHEMA.md)。
## MCP 工具
`mcp/cortex/` 中的服务器向您的代理公开了这些工具：
| 工具 | 类型 | 功能 |
|------|------|------|
| `memory_search` | 读取 | 跨提炼笔记的关键字搜索 |
| `memory_get` | 读取 | 按 ID 获取一个笔记 |
| `memory_related` | 读取 | 按共享标签 + 类别关联的笔记 |
| `memory_write` | 写入 | 创建/更新一个笔记，然后自动提炼 |
| `memory_reload` | 管理 | 强制重新加载索引 |
## 日常使用
您的配置位于 `<vault>/_sync/cortex.yaml`。如果它不在 `distill.py` 旁边，请将 `--config <vault>/_sync/cortex.yaml` 传递到以下命令：
```bash
.venv/bin/python distill.py # 编辑笔记后重新提炼
.venv/bin/python distill.py --dry-run # 预览而不写入
.venv/bin/python distill.py --list # 列出所有笔记及其层级
.venv/bin/python distill.py --show-config # 打印解析路径（JSON）
```
## 导入现有代理（备份 + 入职）
已经设置了代理？`cortex-import.py` 备份其配置并将知识库中已知的部分种子化 — 这样您就不必从空白知识库开始。
```bash
# 预览（不写入任何内容）— 自动检测常见位置
.venv/bin/python cortex-import.py --dry-run
# 导入到示例知识库（或传递 --vault /path/to/your/vault）
.venv/bin/python cortex-import.py
```
**它读取的内容**（每个内容作为 `type: feedback, tier: core` 笔记，标记为 `review`）：
- `AGENTS.md` / `CLAUDE.md`
- 来自 `opencode.jsonc` 的 `instructions[]` 文件
- `~/.claude/memory/*.md`
**备份：** 在读取任何内容之前，包括 `opencode.jsonc` 在内的所有源文件都会被复制到 `<vault>/_sync/backups/<timestamp>/`。因此，任何内容都不会丢失。
所有内容都带有 `review` 标签，因为导入的内容不会自动分类，因此请浏览 `<vault>/feedback/`，在必要时调整 `type`/`tier`，然后重新提炼。使用 `--agents-md`、`--claude-md`、`--opencode` 或 `--claude-memory` 覆盖自动检测的路径。
## 版本控制和升级
皮层跟踪 **两个编号**：
- **发布版本** — 存储库根目录中的 **`VERSION`** 文件中的 SemVer。在 `distill.py --version`、`MCP serverInfo.version`、`package.json` 和 `_meta.cortex_version` 中可见于每个 `memory.json`。升级时增加此版本号。
- **架构版本** — **`SCHEMA_VERSION`** 中的整数，描述磁盘数据契约。写入 `memory.json._meta.schema_version`。这是升级安全比较的内容 — 而不是 SemVer。
每次运行 `distill.py` 都会协调代码架构与知识库架构：它会迁移到新版本（首先自动备份 `_sync/`），如果知识库比代码新，则拒绝运行。随时检查：
```bash
python3 distill.py --config <vault>/_sync/cortex.yaml --check
```
### 升级实时安装
`setup.sh` 启动了一个全新的安装； **`deploy.sh`** 升级一个现有的安装，其组件位于不同的位置（提炼器位于 `<vault>/_sync/` 下，MCP 位于 `~/.config/opencode/mcp/cortex/` 下，技能位于 `~/.config/opencode/skills/` 下）。它是幂等的，首先备份每个目标，重新提炼实时知识库，并验证结果。默认情况下为干运行：
```bash
git pull # 获取新版本
(cd mcp/cortex && npm run build)
./deploy.sh # 预览
./deploy.sh --apply # 部署，然后重启您的代理
```
使用环境变量 `VAULT_ROOT`、`MCP_HOME`、`SKILLS_DIR` 覆盖位置。
完整的增量规则（何时增加主版本号/次版本号/修订版本号和架构版本号）位于 **[CHANGELOG.md](CHANGELOG.md)** 中。
### 你改变主意了？
`setup.sh` 和 `cortex-import.py` 在 `<vault>/_sync/backups/` 下记录安装清单。要恢复皮层到机器的预安装状态（保留您的笔记）：
```bash
python3 cortex-uninstall.py --vault <vault> --latest # 预览
python3 cortex-uninstall.py --vault <vault> --latest --apply # 恢复
```
## 仓库布局
```
VERSION 发布版本（SemVer）— 唯一真实来源
SCHEMA_VERSION 磁盘数据契约版本（整数）
CHANGELOG.md 版本历史 + 版本控制/升级规则
ROADMAP.md 未来版本的计划方向
distill.py 构建管道（知识库 → 代理文件）+ 架构检查/迁移
cortex-import.py 备份 + 将现有代理配置导入知识库
cortex-uninstall.py 基于清单的恢复到预皮层状态（保留笔记）
gen-portfolio.py 可选：来自层级：项目笔记的项目投资组合
setup.sh 新安装的一键启动（交互式）
deploy.sh 升级现有实时安装（先备份，幂等）
cortex.yaml.example 配置模板（setup.sh 在 <vault>/_sync/cortex.yaml 处生成一个真实的）
mcp/cortex/ MCP 服务器（运行时读取 + 捕获）
skills/cortex-ai/ 开放代码技能（setup.sh 安装它，填充真实路径）
example-vault/ 启动知识库 — 每个层级一个笔记，开箱即用
docs/ 概述，QUICKSTART，DEVELOPMENT，VAULT_SCHEMA，EXTENDING，架构
```
技能中的 `version` 命令报告发布版本 (`VERSION`)、架构版本 (`SCHEMA_VERSION`) 和 MCP 服务器版本 (`mcp/cortex/package.json`) — 说“皮层版本”。 `status` 命令报告知识库健康状况、架构偏移和同步陈旧性 — 说“皮层状态”。说“皮层卸载”以恢复皮层（保留笔记）。
## 文档
- [docs/overview.md](docs/overview.md) — 皮层是什么以及为什么使用它
- [docs/QUICKSTART.md](docs/QUICKSTART.md) — 手动设置 + 故障排除
- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — 贡献：开发设置、开发循环、发布
- [docs/VAULT_SCHEMA.md](docs/VAULT_SCHEMA.md) — 前置元信息参考
- [docs/EXTENDING.md](docs/EXTENDING.md) — 添加自定义输出目标
- [docs/DISTILLATION_SUMMARY.md](docs/DISTILLATION_SUMMARY.md) — 架构
- [mcp/cortex/README.md](mcp/cortex/README.md) — MCP 服务器详细信息
- [ROADMAP.md](ROADMAP.md) — 未来版本的计划方向
## 相关
- **[Cortex-Hub](https://github.com/JaySmith/Cortex-Hub)** — 多代理协调层。AI 代理的注册表、共享内存和消息传递。 可选地通过 Cortex-Hub 的共享内存存储同步知识库笔记。
## 许可证
MIT.
