pgmi-builds/corti

🧠 Corti

面向 AI Agent 集群的认知基座

Markdown 作为事实来源 · 亚秒级级联同步 · Postgres 向量搜索 · 多 Agent 自适应

快速开始 · 安装与集成 · 存储栈 · 生命周期 · 设计哲学

Corti（corti）：面向 AI Agent 的持久化、自演化记忆层。将运行时状态与静态权重解耦。以可 diff 的 Markdown 存储状态。重建高性能的 Postgres/SQLite 向量/BM25 索引。完全自托管。

┌─────────────────────────────────────────────────────────────────────────┐
|                          AI AGENT COGNITIVE ARCHITECTURE                 |
|                                                                         |
| 1. LLM Backend (API)     --> Brainstem / Basal Ganglia (Stateless Core) |
| 2. Agent Framework       --> Sensorimotor Exoskeleton (Hands & Feet)   |
| 3. Memory ───────────────--> Agent Cortex (Persistent State Core)       |
└─────────────────────────────────────────────────────────────────────────┘

1. 人格 Agent 与 CLI Agent 之别：目标受众 = 人格 Agent（例如 Hermes Agent、OpenClaw Agent）≠ CLI 任务执行器。人格 Agent 需要持久的后台身份、偏好感知、上下文稳定性。
2. 状态-权重解耦：万亿参数的静态模型权重无法为本地项目而改变。运行时状态必须与静态权重解耦。
3. 记忆片段的随机预注入：将记忆片段随机预注入 ➔ 上下文。契合人类长期记忆：持续的背景上下文 + 定向的激活权重。拓宽激活面，防止召回遗漏。
4. 运行时认知边界：将向量空间直接映射到上下文。解决运行时瓶颈：LLM“不知道自己不知道什么”。常驻记忆 ≠ 按需查询（“文档查找”）。记忆需要常驻才能定义身份。

⚡ 核心特性

* 以简驭繁（为何不用知识图谱？）：
* 开放世界语义分歧：开放世界语义解析无法收敛。代码解析有严格的 AST 语法，但自然语言存在系统性歧义。在 AST/防护措施下的 LLM 解析会产生命名冲突（例如“ABC Project”有时被解析为“ABC”，有时被解析为“ABC Project”），使图构建陷入停滞。形式化本体工程（KBpedia、维基百科规模）成本高不可攀。
* 搜索效用递减：相比原始关键词/语义搜索，图遍历带来的边际收益极小。开放世界信息缺乏严格的依赖链；它依赖松散的因果/包含关系。LLM 拥有庞大的预训练联想空间；传入原始关键词 + 语义向量即可瞬间触发正确的联想触点，无需显式的图边。
* 记忆-知识同构性与局限性：记忆与知识在根源上是同构的 [1] [2]。局限性：Corti 目前尚未将记忆提炼为结构化的学术知识。解决方案：语义关键词/向量是激活 LLM 预训练潜在空间最具成本效益的触发机制。
* 理论基础：“记忆与知识共享同构的图基础 $G = (V, E)$。其区别是操作性的（元属性差异），而非结构性的（数据格式分歧）。” [1]
* 双摄入路径：
* 静默后台消化：自动、静默地在后台摄入来自活跃智能体会话的对话日志。
* 显式智能体 PUT：由智能体提交的直接、以编程方式触发的记忆写入。
* 检索与上下文注入：
* 启动片段预注入：在会话启动时预加载随机记忆片段 ➔ 常驻上下文。为关键词激活准备认知触发器。
* 定向提示增强：针对每条提示进行定向语义搜索。将检索到的记忆上下文直接追加到用户输入中。
* 灵活共享与隔离：
* 跨 5 个维度的多维命名空间隔离：app_id、user_id、agent_id、project_id、session_id。
* 命名空间映射：各维度设置值相同 ➔ 记忆共享；设置值不同 ➔ 绝对记忆隔离。
* Markdown 作为唯一事实来源 — 人类可读、可差异比较、经 Git 版本管理的 .md 文件（~/.corti/）。可从扁平文件 100% 重建。
* 亚秒级级联监视器 — 直接编辑（VS Code、Obsidian、Neovim）➔ 自动同步 SQLite 元数据与 Postgres 向量。
* 自进化离线记忆引擎（OME） — 后台反思循环将原始对话日志压缩为原子事实和动态画像。
* 混合 Postgres / PGLite 向量搜索 — 在单次查询执行中融合 pgvector 语义相似度、BM25 关键词匹配和标量 SQL 过滤。
* 无缝智能体集成 — 为 Hermes Agent、Claude Code、DeepSeek Harness（dsh）、FastAPI HTTP 端点和 CLI 提供插件。

💾 存储栈与路径布局

三件式嵌入式引擎。Markdown = 唯一事实来源。SQLite + Postgres = 派生数据，100% 可重建。

1. SQLite 状态管理器
* 角色：主状态引擎、审计日志记录器和原始对话缓冲区。
* 存储机制：收集原始对话流输入。将其存储为结构化 JSON blob / 块对象，表示未处理的消息数组。作为所有下游编译记忆产物的规范来源。

2. PostgreSQL（PG）记忆核心
* 角色：持久化、可查询记忆的高性能承载基底。
* 存储机制：评估原始 Markdown 文件，“咀嚼”（消化）语义结构，并将其编译为分层 Postgres 表模式：
* Episode：单个智能体会话 / 对话片段（对话流按主题边界进行逻辑分块）。
* 事实：从 Episode 中提取的精炼且蒸馏的语义输出。携带结构化属性、subject 索引，以及简洁的关键词触发 title 元数据。

| 层 | 技术 | 功能 / 资产 | 可重建性 |
|---|---|---|---|
| Truth | 纯 Markdown（.md） | 规范记忆内容，可人工编辑，可移植。 | — |
| State | SQLite（aiosqlite） | 原始事务缓冲区（JSON blob）、审计日志、OME 状态。 | ✅ 可从 .md 重建 |
| Index | Postgres + pgvector | Epised/Facts 向量 + BM25 分层搜索索引。 | ✅ 可从 .md 重建 |

路径命名空间映射：
~/.corti/                                ← 记忆根目录（CORTI_ROOT）
├── /                                  ← 应用隔离边界
│   └── /                          ← 项目隔离边界
│       ├── users/
│       │   └── /
│       │       ├── user.md                    ← 单文件重写（用户画像）
│       │       ├── episodes/                  ← 按日追加日志（原始对话）
│       │       └── .atomic_facts/             ← 按日追加日志（OME 提取的事实）
│       └── agents/
│           └── /
│               └── .foresights/               ← 按日追加日志（OME 提取的预见）
└── .index/                                    ← 被忽略的系统缓存（SQLite + Postgres）

🔄 记忆生命周期流水线

阶段 1：流式累积
* /add 端点按 (session, app, project) 在 SQLite 中缓冲原始消息。
* 实时边界检测器评估消息转换 ➔ 触发提取。

阶段 2：边界摄取（同步）
* /flush 端点触发手动/强制边界提取。
* 提取出的 MemCell 同步写入磁盘上的 episodes/episode-.md。
* HTTP 响应在 Markdown 提交后立即返回。

阶段 3：离线合成（异步 OME）
* 离线记忆引擎（OME）调度异步合成策略。
* 评估原始 episode ➔ 生成派生的 Markdown 资产：
* atomic_facts（单个事实）
* foresights（预测性上下文）
* user.md（用户画像）

阶段 4：级联同步（FS Watcher）
* 原生文件系统事件（Linux/macOS 上的 watchdog）拦截 Markdown 写入。
* 待处理变更排队到持久化 SQLite 表 md_change_state（防止崩溃丢失）。
* 多线程 worker 从队列中拉取 ➔ 计算增量 SHA256 差异 ➔ 仅重新嵌入发生变更的条目 ➔ upsert Postgres（Episodes / Facts schema）。

🚀 快速开始

1. 一键安装

curl -fsSL https://raw.githubusercontent.com/pgmi-builds/corti/main/install.sh | bash

此命令的作用：检查 Docker → 从 Docker Hub 拉取预构建镜像 → 使用默认配置初始化 ~/.corti/ → 如果检测到代理插件（Hermes、Claude Code、DeepSeek Harness），则自动安装。

仅接入单个代理（Corti 服务器已在其他地方运行）：

curl -fsSL https://raw.githubusercontent.com/pgmi-builds/corti/main/install.sh | bash -s -- --only-dsh      # DeepSeek Harness
curl -fsSL https://raw.githubusercontent.com/pgmi-builds/corti/main/install.sh | bash -s -- --only-hermes   # Hermes Agent
curl -fsSL https://raw.githubusercontent.com/pgmi-builds/corti/main/install.sh | bash -s -- --only-claude   # Claude Code

要求：Docker 24+。

精简版 — 如果你已经有带 pgvector 的 PostgreSQL 18+：
export DB_HOST=... DB_PORT=5432 DB_NAME=corti DB_USER=corti DB_PASSWORD=...
curl -fsSL https://raw.githubusercontent.com/pgmi-builds/corti/main/install.sh | bash -s slim

精简镜像：约 400 MB，而一体化镜像为 1.2 GB。固定版本：bash -s v0.2-slim。

2. 启动服务器

docker run -d --name corti \
-p 5473:5473 \
-v ~/.corti:/home/app/.corti \
m1research/corti:latest
精简版（外部 PG）：
docker run -d --name corti -p 5473:5473 -v ~/.corti:/home/app/.corti \
-e DB_HOST=... -e DB_NAME=corti -e DB_USER=corti -e DB_PASSWORD=... \
m1research/corti:slim
验证
curl http://localhost:5473/health
→ {"status":"ok"}

3. 存储与搜索（HTTP API）

存储偏好
curl -s -X POST http://localhost:5473/api/v1/memory/add \
-H 'Content-Type: application/json' \
-d '{"user_id":"default_user","messages":[{"role":"user","content":"Prefer strictly typed Python, dark mode UI","timestamp":'"$(date +%s)000"'}]}'

搜索记忆存储
curl -s -X POST http://localhost:5473/api/v1/memory/search \
-H 'Content-Type: application/json' \
-d '{"user_id":"default_user","query":"dev styling preference"}'

⚙️ 安装与插件集成

1. 一条命令完成 Docker 安装

安装脚本（install.sh）会自动处理所有事项：

1. 拉取 Docker 镜像 — 从 Docker Hub 获取预构建的 m1research/corti:latest（无需克隆，无需构建）
2. 数据初始化 — 从镜像中提取默认配置到 ~/.corti/corti.toml
3. Agent 插件安装 — 从镜像中提取插件源码到 agent 的本地插件目录：

| Agent | 目标位置 | 来源 |
|---|---|---|
| Hermes Agent | ~/.hermes/plugins/corti/ | src/integrations/hermes/ |
| Claude Code | ~/.claude/skills/corti/ | src/integrations/claude-code/ |
| DeepSeek Harness | 每个 ~/.dsh/profiles/（通过 dsh plugin add） | src/integrations/deepseek-harness/ |

插件是复制的（而非符号链接），因此它们能在仓库更新后继续存在并独立工作。dsh 插件则通过 dsh 自有的、由 pnpm 支持的 profile 管理器安装——直接从 GitHub 仓库安装，因此即使同一主机上没有 Docker 镜像也能正常工作。

2. 手动安装插件

如果安装脚本的自动检测没有识别到你的 agent，或者你在 Corti 之后安装了新的 agent——可以直接从 GitHub 仓库拉取插件（无需 Docker）：

Hermes Agent
curl -fsSL https://github.com/pgmi-builds/corti/archive/refs/heads/main.tar.gz | \
tar -xz --strip-components=3 -C ~/.hermes/plugins/ corti-main/src/integrations/hermes
mv ~/.hermes/plugins/hermes ~/.hermes/plugins/corti
hermes plugins enable corti

Claude Code — 放入 ~/.claude/skills/ 以便自动发现
（hooks/hooks.json + MCP 在下次会话时自动加载，零 CLI）
curl -fsSL https://github.com/pgmi-builds/corti/archive/refs/heads/main.tar.gz | \
tar -xz --strip-components=3 -C ~/.claude/skills/ corti-main/src/integrations/claude-code
mv ~/.claude/skills/claude-code ~/.claude/skills/corti

DeepSeek Harness (dsh) — 安装到每个现有的 dsh 配置文件中
dsh plugin --profile web add https://github.com/pgmi-builds/corti#src/integrations/deepseek-harness
然后将其指向你的 Corti 服务器（一次）：
echo "CORTI_BASE_URL=http://:5473" >> ~/.dsh/.env

通过将 main 替换为标签（例如 v0.2）来固定到特定版本。

🛠 设计哲学：功能移除

Corti 主动从执行循环中移除遗留的 Agent Case 和 Agent Skill 模块。

1. 移除 Agent Case（轨迹摘要）
原始功能：审查记忆历史，以总结单个 Agent 轨迹和任务场景，供未来回放使用。
* 移除原因：轨迹上下文已经被清晰地消化到基础分层模式（episode、facts、subject、title）中。高参数 LLM 包含大量原生预训练智能。当匹配到语义线索时，将原始事实和对话日志直接传入上下文在数学上已经足够。LLM 可以动态地泛化并解决本地任务。人工预摘要属于冗余。

2. 移除 Agent Skill（自定义能力存储）
* 原始功能：为已注册的 Agent 能力脚本提供执行环境。
* 移除原因：合法的 Agent 平台（Hermes、Claude Code、OpenClaw）拥有健壮、原生、开放的技能注册表和插件。在记忆基底内重复这些能力违反了极简主义。

3. 核心架构哲学
* Linux 单一工具哲学：坚持激进的极简主义。完全专注于将记忆状态层优化到绝对理论极限。绝不重复周围执行底盘所处理的服务。
* 缓解认知重叠：自主 Agent 的主要痛点是“不知道自己不知道什么”。记忆的存在是为了引导提示上下文到达模型预训练潜在空间中的正确坐标。在 2026 年 AI 驱动的开发时代，顶层架构蓝图和提示上下文选择远比本地代码生成脚本更有价值。为提示上下文选择并附加正确的事实/片段，对于高参数 LLM 推理来说已经完全足够。

🔬 理论基础与认知根基

1. 更新的互补学习系统（CLS）
* 引用：Kumaran, D., Hassabis, D., & McClelland, J. L. (2016). 智能体需要什么样的学习系统？互补学习系统理论更新。Trends in Cognitive Sciences, 20(7), 350-375. [1]
* 发现：新皮层学习率随新输入与现有图式拓扑结构的一致性而缩放。
* 相关性：验证了记忆巩固过程基于相互兼容性进行缩放；海马回放训练新皮层生成结构。为记忆-知识同构假说（MKIH）提供了实证锚点。

2. Tolman-Eichenbaum 机器（TEM）
* 引用：Whittington, J. C., Muller, T. H., Mark, S., Chen, G., Barry, C., Burgess, N., & Behrens, T. E. (2020). Tolman-Eichenbaum 机器：通过海马体形成中的泛化统一空间与关系记忆。Cell, 183(5), 1249-1263. [2]
* 发现：内侧内嗅皮层（MEC）形成抽象结构知识基础 ↔ 海马体绑定感觉情景记忆。
* 相关性：证明记忆与抽象图式共享相同的空间基础表征；区别在于拓扑连接，而非数据格式。

3. 克隆结构认知图（CSCG）
* 引用：George, D., Rikhye, R. V., Gothoskar, N., Guntupalli, J. S., Dedieu, A., & Lázaro-Gredilla, J. (2021). 克隆结构图表示支持认知地图的灵活学习与替代评估。Nature Communications, 12(1), 2392.
* 发现：空间导航、关系推理和情景地图在相同的统一图结构内巩固。
* 相关性：数学验证了多格式记忆-图式在统一图拓扑下的收敛。

4. 实证验证：LoCoMo 数据集
* 评估基线：LoCoMo 基准（Maharana et al., 2024），1,540 个多会话评估查询。
* 结果矩阵：
* 单跳事实检索：94.0%
* 多跳推理摄入：91.0%
* 对话锚定开放域：80.2%
* 时间序列推理：95.5%
* 加权平均：93.3%
* 理论解释：
* 简单语义向量检索 + 时间元数据过滤解决了 95.5% 的复杂时间顺序推理。
* 证实“关键词 + 语义相似度 + 时间元数据”在数学上足以触发上下文适当的回忆。
* 绕过了形式化知识图谱构建的高解析延迟、成本和解析分歧瓶颈。

⚖️ EverOS 来源与极简主义生产改造

Corti 最初从上游 EverOS 代码库（Apache-2.0）借用了代码结构和核心概念。然而，该系统经历了深度本地重新开发、自定义架构优化和设计理念转变。

极简工程与功能移除：
* 应用严格的 UNIX 风格极简主义来优化执行路径并减少认知膨胀。
* 完全移除了 agent_case（轨迹摘要）和 agent_skill（能力存储）。上游 EverOS 保留了这些组件；Corti 将其裁剪掉，因为高参数 LLM 潜在空间只需要原始语义触发器（episode 和 facts 模式），而不需要冗余的、预先摘要的本地结构和自定义执行注册表。

上游开源版本的局限性：
* LanceDB 瓶颈：上游 EverOS 依赖 LanceDB——一种为扁平、高读取研究数据设计的嵌入式列式存储。在持久守护进程工作负载中，LanceDB 会将完整表加载到内存中，并在变更时进行复制。这会导致严重的、不可恢复的内存泄漏和线程锁定，使其完全不适合多智能体自托管生产环境。
* SaaS 商业拆分：EverOS 开源核心充当其专有云 SaaS 的引流漏斗。因此，其“开箱即用”的本地自托管就绪度较低，缺乏多租户事务安全性、并发执行管道和稳健的本地持久化保证。

Corti 的自定义增强：
* 事务性 Postgres 全面改造：将整个检索底盘替换为稳健的、生产级的 PostgreSQL / pgvector 后端（为轻量级实例提供嵌入式 PGLite 支持），解决了存储泄漏问题并确保了事务安全性。
* 持久 API 守护进程：彻底改造了执行循环的 CLI 开销，将其替换为活跃的、并发的 FastAPI 守护进程，以安全地服务并发 Agent 集群。
* 轻量级记忆片段：放弃了导致提示膨胀的完整情节摄入，替换为基于标题的片段检索。注入 20 个简洁的元数据片段拓宽了召回触发面，同时保留了 token 上下文边界。
* 插件全面改造：完全重写了 Hermes 和 Claude Code 插件，使其能够与自托管本地守护进程无缝通信（将其与云 API 绑定解耦）。

📄 脚注与引用

[1] Kumaran, D., Hassabis, D., & McClelland, J. L. (2016). What learning systems do intelligent agents need? Complementary learning systems theory updated. Trends in Cognitive Sciences, 20(7), 350-375.

[2] Whittington, J. C., Muller, T. H., Mark, S., Chen, G., Barry, C., Burgess, N., & Behrens, T. E. (2020). The Tolman-Eichenbaum Machine: Unifying space and relational memory through generalization in the hippocampal formation. Cell, 183(5), 1249-1263.

📄 许可证

Apache-2.0 License。