智能体记忆库 pgmi-builds/corti

🧠 Corti

面向 AI 智能体集群的认知基底

Markdown 作为唯一事实来源 · 亚秒级级联同步 · Postgres 向量搜索 · 多智能体自适应

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

Corti（corti）：给 AI 智能体用的持久化、自演化记忆层。把运行时状态与静态权重解耦。状态存成可 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. 人格智能体 vs. 命令行智能体：目标用户 = 人格智能体（比如 Hermes Agent、OpenClaw Agent）≠ 命令行任务执行器。人格智能体需要持久的后台身份、偏好感知、上下文稳定。
2. 状态与权重解耦：万亿参数的静态模型权重没法为本地项目改动。运行时状态必须与静态权重解耦。
3. 记忆片段随机预注入：把记忆片段随机预注入 ➔ 上下文。这贴合人类的长期记忆：恒定的背景上下文 + 定向激活权重。扩大激活面，避免漏召回。
4. 运行时的认知边界：把向量空间直接映射到上下文。解决运行时瓶颈：LLM「不知道自己不知道什么」。常驻记忆 ≠ 按需查询（「查文档」）。记忆必须常驻，才能定义身份。

⚡ 核心特性

* 简单优先于复杂（为什么不用知识图谱？）：
* 开放世界的语义分歧：开放世界的语义解析无法收敛。代码解析有严格的 AST 语法，自然语言却有系统性歧义。在 AST/防护措施下做 LLM 解析，会产生命名冲突（比如「ABC Project」有时解析成「ABC」，有时解析成「ABC Project」），让图谱构建卡住。形式化本体工程（KBpedia、维基百科那种规模）成本高到无法承受。
* 搜索收益递减：相比原始的关键词/语义搜索，图遍历带来的边际收益极小。开放世界的信息没有严格的依赖链，靠的是松散的因果/包含关系。LLM 自带海量预训练关联空间；直接喂原始关键词 + 语义向量，瞬间就能触发正确的关联触点，不需要显式的图边。
* 记忆与知识同构 & 局限：记忆和知识在根上同构 [1] [2]。局限：Corti 目前不会把记忆蒸馏成结构化的学术知识。解决：语义关键词/向量是激活 LLM 预训练潜空间最划算的触发机制。
* 理论依据：「记忆与知识共享同构的图基 $G = (V, E)$。二者的区别是操作层面的（元属性差异），不是结构层面的（数据格式分歧）。」[1]
* 双摄入路径：
* 静默后台消化：自动、静默地在后台摄入活跃智能体会话的对话日志。
* 显式 Agent PUT：由智能体直接以编程方式触发并提交的记忆写入。
* 检索与上下文注入：
* 启动片段预注入：会话启动时预加载随机记忆片段 ➔ 常驻上下文。为关键词激活准备认知触发器。
* 定向提示词增强：每条提示词都做定向语义搜索。把检索到的记忆上下文直接追加到用户输入后面。
* 灵活的共享与隔离：
* 沿 5 个维度做多维命名空间隔离：app_id、user_id、agent_id、project_id、session_id。
* 命名空间映射：各维度取值相同 ➔ 记忆共享；取值不同 ➔ 记忆绝对隔离。
* Markdown 作为唯一事实来源 —— 人类可读、可 diff、由 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 端点、命令行插件。

💾 存储栈与路径布局

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

1. SQLite 状态管理器

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

2. PostgreSQL（PG）记忆核心

* 职责：持久化、可查询记忆的高性能承载底座。
* 存储机制：解析原始 Markdown 文件，「咀嚼」（消化）语义结构，编译成分层的 Postgres 表结构：
* Episode：单个智能体会话 / 对话片段（对话流按主题边界做逻辑分块）。
* Facts：从 Episodes 提炼出的精炼语义输出。带结构化属性、subject 索引，以及由关键词触发的简洁 title 元数据。

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

路径命名空间映射：

~/.corti/ ← Memory Root (CORTI_ROOT)
├── <app_id>/ ← App isolation boundary
│ └── <project_id>/ ← Project isolation boundary
│ ├── users/
│ │ └── <user_id>/
│ │ ├── user.md ← Single-file rewrite (User Profile)
│ │ ├── episodes/ ← Daily-log append (Raw conversations)
│ │ └── .atomic_facts/ ← Daily-log append (OME extracted facts)
│ └── agents/
│ └── <agent_id>/
│ └── .foresights/ ← Daily-log append (OME extracted foresight)
└── .index/ ← Ignored system cache (SQLite + Postgres)

🔄 记忆生命周期流水线

阶段 1：流式累积

* /add 端点按 (session, app, project) 把原始消息缓冲进 SQLite。
* 实时边界检测器评估消息转换 ➔ 触发提取。

阶段 2：边界摄入（同步）

* /flush 端点触发手动/强制边界提取。
* 提取出的 MemCell 同步写入磁盘上的 episodes/episode-<date>.md。
* Markdown 提交完成后，HTTP 响应立即返回。

阶段 3：离线合成（异步 OME）

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

阶段 4：级联同步（文件系统监听器）

* 原生文件系统事件（Linux/macOS 上的 watchdog）拦截 Markdown 写入。
* 待处理变更排入持久化 SQLite 表 md_change_state（防止崩溃丢数据）。
* 多线程 worker 从队列拉取 ➔ 计算增量 SHA256 diff ➔ 只重新嵌入变更条目 ➔ 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 服务已在别处运行）：

bash
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+。

精简版 —— 如果你已经有 PostgreSQL 18+ 并装了 pgvector： bash
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.3.4-slim。

2. 启动服务 bash
docker run -d --name corti \
-p 5473:5473 \
-v ~/.corti:/home/app/.corti \
m1research/corti:latest

Slim variant (external 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

Verify

curl http://localhost:5473/health

→ {"status":"ok"}

3. 存储与搜索（HTTP API） bash

Store preference

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"'}]}'

Search memory store

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（不用 clone，不用构建）
2. 写入数据 —— 从镜像里提取默认配置，写入 ~/.corti/corti.toml
3. 安装智能体插件 —— 从镜像里提取插件源码，放进智能体本地的插件目录：

| 智能体 | 目标路径 | 来源 |
| 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 配置档管理器安装 —— 直接从 GitHub 仓库装，所以同一台机器上即使没有 Docker 镜像也能用。

2. 手动安装插件

如果安装脚本的自动检测没认出你的智能体，或者你在装完 Corti 之后才装了新智能体 —— 直接从 GitHub 仓库拉取插件（不需要 Docker）： bash

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 — dropped into ~/.claude/skills/ for auto-discovery (hooks/hooks.json + MCP auto-loaded on next session, zero 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) — installs into every existing dsh profile
dsh plugin --profile web add https://github.com/pgmi-builds/corti#src/integrations/deepseek-harness
then point it at your Corti server (once):
echo "CORTI_BASE_URL=http://<corti-host>:5473" >> ~/.dsh/.env

把 main 换成某个 tag（比如 v0.3.4），就能固定到指定版本。

🛠 设计理念：砍掉的功能

Corti 主动把遗留的 Agent Case 和 Agent Skill 模块从执行链路里移除。

1. 移除 Agent Case（轨迹摘要）

原有功能：回顾记忆历史，为单个 Agent 轨迹和任务场景生成摘要，供日后回放。
* 移除原因：轨迹上下文已经干净地消化进基础分层 schema（episode、facts、subject、title）。高参数 LLM 自带海量预训练智能。语义线索一旦匹配上，把原始事实和对话日志直接塞进上下文，数学上就够了。LLM 能自己泛化，动态解决局部任务。人为预摘要纯属多余。

2. 移除 Agent Skill（自定义能力仓库）

* 原有功能：为注册的 Agent 能力脚本提供执行环境。
* 移除原因：正经的 Agent 平台（Hermes、Claude Code、OpenClaw）都有健壮、原生、开放的技能注册表和插件。在记忆底座里重复这些能力，违背极简主义。

3. 核心架构理念

* Linux 单工具哲学：坚持激进极简。全部精力用来把记忆状态层优化到理论极限。周边执行底盘已经处理的服务，绝不重复造。
* 消除认知重叠：自主智能体最大的痛点是「不知道自己不知道什么」。记忆存在的意义，是引导提示词上下文落到模型预训练潜空间里的正确坐标。在 2026 年 AI 驱动的开发时代，顶层架构蓝图和提示词上下文选择，远比局部代码生成脚本值钱。把正确的事实/片段挑出来挂到提示词上下文上，高参数 LLM 推理完全够用。

🔬 理论基础与认知根基

1. 更新版互补学习系统（CLS）

* 引用：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. [1]
* 发现：新皮质学习率随新输入与已有图式拓扑的一致性而缩放。
* 相关性：验证记忆巩固过程随相互兼容性而缩放；海马回放训练新皮质生成结构。为 Memory-Knowledge Isomorphism Hypothesis (MKIH) 提供实证锚点。

2. Tolman-Eichenbaum Machine (TEM)

* 引用：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. [2]
* 发现：内侧内嗅皮层（MEC）形成抽象结构知识基础 ↔ 海马绑定感官情景记忆。
* 相关性：证明记忆与抽象图式共享同一套空间基础表征；区别在于拓扑连接，而非数据格式。

3. Clone-Structured Cognitive Graph (CSCG)

* 引用：George, D., Rikhye, R. V., Gothoskar, N., Guntupalli, J. S., Dedieu, A., & Lázaro-Gredilla, J. (2021). Clone-structured graph representations enable flexible learning and vicarious evaluation of cognitive maps. 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 schema），不需要冗余的预摘要本地结构和自定义执行注册表。

上游开源版本的局限：

* LanceDB 瓶颈：上游 EverOS 依赖 LanceDB——一种嵌入式列式存储，为扁平、高读取量的研究数据而设计。在常驻守护进程负载下，LanceDB 会把整张表加载进内存，并在变更时复制。这导致严重且无法恢复的内存泄漏和线程锁定，使其完全不适合多智能体自托管生产环境。
* SaaS 商业拆分：EverOS 开源核心充当其专有云 SaaS 的漏斗。因此，它的本地自托管「开箱即用」成熟度很低，缺少多租户事务安全、并发执行流水线和可靠的本地持久化保证。

Corti 的自定义增强：

* 事务型 Postgres 重构：把整个检索底座替换为健壮的生产级 PostgreSQL / pgvector 后端（为轻量实例提供嵌入式 PGLite 支持），解决存储泄漏并确保事务安全。
* 常驻 API 守护进程：重构执行循环的命令行开销，替换为主动、并发的 FastAPI 守护进程，安全服务并发的智能体集群。
* 轻量记忆片段：抛弃让提示词膨胀的完整 episode 注入，替换为基于标题的片段检索。注入 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。