AI代理认知记忆系统

敞开的宫殿——你代理人的心灵宫殿

ECS为AI代理构建了认知记忆系统。

意识，而不是记忆。

中文文档

Open Palace是一个类似ECS（实体组件系统）的人工智能代理认知系统，作为本地MCP服务器交付。

它从一个前提开始： 代理是不可靠的指令追随者。告诉代理“始终在更改后提交”。它会忘记、跳过或格式错误。因此，必须发生的一切都是代码级管道（PostHook引擎），而不是系统提示符中的一行。

这不是内存插件。Open Palace管理着整个认知堆栈：

• 谁是代理人 是 （实体注册表，具有双向SOUL同步和个性进化跟踪功能）
• 什么代理人 知道 （具有三级索引和L2混合搜索的组件存储）
• 什么代理人 决定及其原因 （双层变更日志，包括基本原理和被拒绝的替代方案）
• 谁是代理人 与...互动 （带有交互标签和信任跟踪的关系记忆）
• 发生了什么 自动地 （带库管理员、内存衰减、健康检查和可扩展管道的系统存储）

全部存储在本地 ~/.open-palace/，您拥有的一个自包含的git仓库。

问题

当前的代理框架通过上下文指令和markdown文件来管理认知。这以可预测的方式打破：

• 子代理以空白板条的形式生成。 一个衍生的“CMO”子代理对上一个“CMO“做了什么一无所知。具有相同角色的独立代理人？完全独立的实体，零共享状态。
• 跨会话内存不存在。 每一次新的会议都从头开始。如果没有结构化的日志、摘要或版本控制的存储，就没有传递决策和上下文的机制。上周决定了什么？代理人没有办法知道。
• 长上下文会降低准确性。 在会话中，随着上下文的增长，指令遵循的准确性会下降。压缩和修剪是按块丢弃的，而不是有选择地丢弃的，通常会在此过程中丢失决策上下文。
• 跨代理的冗余上下文。 在多智能体对话中，每个参与者都携带完整的上下文，而每个参与者只需要一小部分。选择性加载没有结构索引机制。
• 内存文件缺乏保护。 没有版本控制或结构约束，代理可以用相互矛盾的信息覆盖现有内存，无法回滚。
• 记忆只会积累，永远不会忘记。 如果没有主动遗忘，检索噪声会随着每个文件的增加而增加。经过几个月的使用，找到正确的信息变得更加困难，而不是更容易。
• 及时的指示是不可靠的。 上下文说明是建议性的。代理可能会忘记、跳过或错误格式化它们。关键操作需要代码级保证。

Open Palace通过确定性工程解决了这些问题：存储计算分离、代码级PostHooks、三级索引、基于温度的内存衰减、写验证和git支持的版本控制。

突出显示的功能

基于温度的记忆衰退。 记忆不是永恒的。Open Palace根据年龄、访问频率和参考人数对每个条目进行温度评分。冷数据会自动存档。固定条目受到保护。图书管理员的安全水印可确保在消化之前不会存档任何内容。结果：即使经过数月的累积数据，检索也保持精确。

压缩弹性上下文快照。 当主机驱逐上下文时，代理会立即恢复。 mp_snapshot_save 写入一个实时的仅覆盖状态文件——当前焦点、活动任务、阻止程序、最近的决策。压实后， mp_snapshot_read 在一次通话中恢复工作状态。不是会话日志。一个保存点。

写完整性保护。 在内存进入系统之前，可以根据现有数据对其进行验证。验证层检测四种风险类型：重复、矛盾、幻觉事实和过时的覆盖。决策类型条目会自动验证。原则是：永远不要盲目相信代理人的写作。

三层可插拔搜索。 L2搜索使用任何可用的后端：安装QMD（BM25+向量+LLM重新排序）时，Orama BM25作为嵌入式回退，或简单的关键字扫描作为最后手段。无需建设RAG管道。检索+摘要系统将L0/L1/L2结果与LLM合成相结合，以获得结构化答案。

关系记忆与信任跟踪。 标记的交互模式会随着时间的推移而积累。信任评分会根据明确的事件而变化。代理为每个用户或合作者构建一个结构化的配置文件——沟通风格、专业知识、偏好——为未来的交互提供信息。

集中式配置参考。 所有子系统中的每个可调参数（28个参数，涵盖库管理员计划、衰减阈值、验证规则、搜索后端等）都记录在一个可查询的引用中，其中包含默认值、类型、受影响的系统和代码位置。 mp_config_reference 返回可按关键字筛选的完整表。

太长，读不下去了

人工智能代理的ECS架构认知系统。身份+知识+决策+关系，有工程保证。

1. ECS架构。 实体注册表（身份/个性）+组件存储（知识模块）+系统存储（自动化管道）。按需装卸。
2. 三级指数。 L0主指数（<500个代币，始终处于上下文中），用于全球认知。L1按需总结。通过目标搜索获取L2原始数据。代理人不带背景；他们知道存在什么，并加载他们需要的东西。
3. 工作记忆草稿。 零摩擦 mp_scratch_write 在工作中捕捉洞察力——没有范围，没有类型，只有内容。在压实过程中幸存下来。本土的 memory/*.md 文件在启动时自动摄取。准备就绪后，草稿条目将升级为结构化组件。
4. 压缩弹性快照。 仅覆盖代理在上下文驱逐后立即读取的状态文件，以在一次调用中恢复焦点、任务和决策。
5. 版本化人格。 主机工作区和Open Palace之间的双向SOUL同步。进化史上的每一个变化。Git回滚。个性不会默默地漂泊；它以书面记录的方式演变。
6. 可追溯的决策。 双层变更日志：自动生成的操作日志+代理记录的决策日志，其中包含基本原理和被拒绝的替代方案。预写验证可以捕获重复、矛盾和幻觉记忆。
7. 基于温度的记忆衰退。 基于年龄、访问模式和引用计数的主动遗忘。冷数据被存档，而不是删除。图书管理员安全水印可防止数据丢失。随着数据的增长，检索保持精确。
8. 三层可插拔搜索。 QMD混合搜索可用时，Orama BM25作为嵌入式回退，简单扫描作为最后手段。检索+摘要系统将L0/L1/L2的答案与LLM进行综合。
9. 关系记忆。 交互标签、信任评分、用户资料。随着时间的推移，代理学习如何与每个用户交互。
10. 代码级保证。 PostHook引擎在每次写入操作时都会触发git提交、索引更新、更改日志写入和搜索重新索引。代码管道，而不是提示指令。
11. 完全本地化，完全便携。 ~/.open-palace/ 是一个自包含的git repo。YAML+Markdown+Git。无云依赖。 cp -r 任何机器。

什么是ECS？

ECS（实体组件系统）是游戏行业的一种架构模式，用于《守望先锋》、《矮人要塞》和无数MMO背后的引擎。与OOP继承层次结构不同，其中行为被烘焙到类树中，ECS将身份（实体）、数据（组件）和行为（系统）解耦。

在开放宫：

需要一个新的知识领域吗？创建组件。需要新的自动化工作流程吗？注册一个系统。代理身份、知识和维护例程完全解耦。

代理商如何使用Open Palace

会话启动。 代理人打电话来 mp_index_get, mp_snapshot_read，以及 mp_scratch_read。现在它有L0主索引（<500个令牌，全局感知），从上次快照恢复的工作状态，以及最近的草稿。在三次通话中实现完整的上下文恢复。

在工作中捕捉洞察力。 在调试、探索或讨论期间，代理调用 mp_scratch_write 一旦它发现了重要的事情。找到根本原因了吗？刮掉它。方法失败了吗？挠为什么。用户是否更正了一个假设？不用担心。零摩擦——只有内容和可选标签。这些条目在压缩后仍然存在，因为它们是文件，而不是上下文。

按需加载上下文。 用户询问项目。代理将其与L0进行匹配，调用 mp_component_load("projects/my-app")，获取L1摘要和最近的决定。只有需要的东西才能进入上下文。

记录决策。 代理人打电话来 mp_changelog_record 决定、理由和被拒绝的替代方案。PostHook自动处理git提交、L0更新和全局更改日志。根据现有数据验证决策条目，以捕捉重复和矛盾。

搜索所有数据。 mp_raw_search 使用最佳可用后端查询更改日志、摘要和草稿条目。对于更深入的查询， retrieval_digest 将L0/L1/L2结果与LLM合成相结合。

压缩前保存状态。 代理人打电话来 mp_snapshot_save 有当前焦点、活动任务和障碍。压实后， mp_snapshot_read 立即恢复一切。

被动记忆摄取。 即使代理人写信给本地人 memory/*.md 文件而不是Open Palace，这些文件在每次MCP服务器启动时都会通过SHA256 diffing自动摄入到草稿层。

生成子代理。 主代理电话 mp_entity_get_soul("cmo") 对于子代理的个性，加载相关的组件摘要，并将两者注入到生成提示符中。子代理开始通知，而不是空白。

后台维护。 图书管理员每天将变更日志摘要为更新的L1摘要，每周进行跨组件分析，每月重建L0。Memory Decay根据温度评分存档冷数据。健康检查验证数据完整性并标记过时的知识。所有代码级别，无代理参与。

五大设计原则

1. 存储计算分离。 确定性工程（索引、变更日志、git）处理持久性。LLM处理推理。每个人都做自己擅长的事。
2. 意识>背景。 代理人不会携带所有东西。它携带一个压缩的全局索引（<500个令牌），并对存在的内容具有结构意识。信息按需加载。
3. 代理人不可知。 新会话、不同模型、上下文驱逐：代理从Open Palace的结构化数据中完全重建意识。
4. 工程管线>提示说明。 必须发生的事情（git提交、索引更新、更改日志写入）是代码级的PostHooks，而不是可能被遗忘的LLM指令。
5. 便携性>召回。 所有状态都是可序列化的、可转移的、版本控制的。复制 ~/.open-palace/ 任何机器。

建筑

┌──────────────────────────────────────────────────────────────────┐
│                        MCP Server (stdio)                        │
│                                                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │  Entity Registry  │  │  Component Store  │  │ System Store  │  │
│  │  Identity + SOUL  │  │  Projects/Skills  │  │  Librarian    │  │
│  │  Evolution Log    │  │  Knowledge/Rels   │  │  Health Check │  │
│  │  Bidirectional    │  │  Load/Unload      │  │  Memory Decay │  │
│  │  Workspace Sync   │  │  Per-component    │  │  Retrieval+   │  │
│  │                   │  │  Changelog        │  │  Digest       │  │
│  └──────────────────┘  └──────────────────┘  └──────────────┘  │
│                                                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │  3-Level Index    │  │  Dual-Layer      │  │  PostHook     │  │
│  │  L0: Global Map   │  │  Changelog       │  │  Engine       │  │
│  │  L1: Summaries    │  │  + Write         │  │  Auto git     │  │
│  │  L2: Search/RAG   │  │  Validation      │  │  Auto index   │  │
│  └──────────────────┘  └──────────────────┘  └──────────────┘  │
│                                                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │  Context Snapshot │  │  Workspace Sync   │  │  3-Tier      │  │
│  │  Compaction       │  │  SHA256 diffing   │  │  Search      │  │
│  │  Recovery         │  │  SOUL writeback   │  │  QMD/Orama/  │  │
│  │                   │  │                   │  │  builtin     │  │
│  └──────────────────┘  └──────────────────┘  └──────────────┘  │
│                                                                  │
│                     Persistence Layer                             │
│          ~/.open-palace/ (YAML + Markdown + Git)                 │
└──────────────────────────────────────────────────────────────────┘

快速开始

先决条件

• Node.js>=18（推荐：v22）
• npm

游标（推荐--单行安装）

bash <(curl -fsSL https://raw.githubusercontent.com/KasparChen/open-palace/main/scripts/install-cursor.sh)

此操作在中克隆、构建和注册MCP服务器 ~/.cursor/mcp.json，并安装光标规则+技能文件。代理将在每个会话中自动使用Open Palace，无需手动配置。

如果您更喜欢手动设置：

git clone https://github.com/kasparchen/open-palace.git ~/open-palace
cd ~/open-palace && npm install && npm run build
bash scripts/install-cursor.sh

克劳德桌面版

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "open-palace": {
      "command": "node",
      "args": ["/absolute/path/to/open-palace/dist/index.js"]
    }
  }
}

开爪

添加 ~/.openclaw/workspace/config/mcporter.json:

{
  "servers": {
    "open-palace": {
      "command": "node",
      "args": ["/absolute/path/to/open-palace/dist/index.js"]
    }
  }
}

然后运行 mp_onboarding_init 自动设置SKILL、TOOLS.md和AGENTS.md。

验证

让代理运行：

mp_index_get          → Should return the L0 Master Index
mp_system_list        → Should show 6 registered systems
mp_onboarding_status  → Should report setup status

更新中

cd ~/open-palace && git pull && npm install && npm run build

# For Cursor: re-run the install script to update rule/skill files
bash scripts/install-cursor.sh

# For OpenClaw: run mp_onboarding_init — it detects version changes and updates automatically

或者让代理人来处理： mp_onboarding_status 报告何时有更新可用，以及 mp_onboarding_init 应用它。

MCP工具（42个工具）

划痕：工作记忆

快照：压缩恢复

指数：全球意识

实体：代理身份

组成部分：知识模块

变更日志：决策跟踪

搜索：L2检索

关系：互动记忆

记忆衰退：主动遗忘

系统：自动化管道

配置

入职

关键系统

图书管理员

在多个级别将变更日志和草稿条目处理成摘要：

图书管理员默认情况下通过MCP采样使用主机的LLM（不需要API键）。如果采样不可用，则返回到直接人类API。

记忆衰退

基于温度的主动遗忘，随着数据的增长保持检索的准确性：

• 每个条目都有一个温度分数： age_base + access_bonus + reference_bonus + pin_bonus
• 低于存档阈值的条目将被移动到 archive/ （未删除）
• 图书管理员的安全水印可防止存档未处理的数据
• 固定入口受到永久保护（温度999）
• 可配置： decay.archive_threshold, decay.max_age_days, decay.pinned_entries

检索+摘要

使用LLM合成进行L0到L1到L2的渐进检索：

• 三层搜索后端：QMD（BM25+矢量+重新排序的混合搜索）可用时，Orama（嵌入式BM25）作为后备，简单的关键字扫描作为最后手段
• mp_raw_search 返回具有相关性得分的原始匹配片段
• retrieval_digest 该系统通过将摘要和搜索结果与LLM相结合来合成结构化答案

健康检查

验证整个内存系统：

• 索引一致性（L0条目与实际组件目录）
• 孤立检测（没有索引条目的组件，反之亦然）
• 稳定性评分（60天以上未验证的组件标记为陈旧）
• Git状态（未提交的更改）
• 实体同步状态

内存摄取

即使代理人写信给本地人 memory/*.md 文件，Open Palace在每次MCP服务器启动时通过SHA256 diffing自动捕获内容。被动安全网——代理不需要改变行为，内容就可以流入Open Palace。

PostHook发动机

每次写入操作都会触发自动的副作用——git提交、索引更新、更改日志写入、搜索重新索引。代码级管道。代理不需要“记住”提交或更新索引。

发展

npm run typecheck    # Type check without emitting
npm run build        # Compile TypeScript
npx tsx src/test-e2e.ts   # Run E2E tests (138 assertions)

路线图

• 第一阶段 --MCP服务器+实体+索引+组件+变更日志+PostHook
• 第2阶段 --L0/L1/组件/变更日志核心逻辑
• 第三期 --图书管理员+系统存储+健康检查
• 第3.5阶段 --入职+双向工作空间同步
• v0.2 --工作记忆层（划痕+记忆摄入+图书馆员划痕分类）
• v0.3 --光标集成（规则+技能自动安装，多环境入职）
• v0.4 --上下文快照、库管理员安全门、内存衰减、写验证、关系内存、三层搜索（QMD/Orama/内置）、检索+摘要、状态评分、集中配置参考

致谢

最初的设计研究涉及研究六个游戏系统中的记忆和人格机制——矮人要塞、迪斯科极乐世界、复仇者系统（魔多之影/战争）、巴尔杜尔之门3、十字军之王3和Planescape：折磨。主要的收获是概念性的：分层记忆结构，即记忆应该是可见和可查询的，而不是隐含的，并且关系可以被捕获为标记的交互。我们没有直接移植任何游戏机制——LLM代理不需要状态机或个性评分系统——但这些游戏塑造了我们对问题空间的看法。

以下项目和著作对建筑产生了直接影响：

• 生成式智能体 （斯坦福）——证明“结构化外部记忆+LLM反射”确实有效的论文。Open Palace的整个前提——代理应该向持久结构化存储写入和读取，而不是依赖于上下文窗口——都可以追溯到这项工作。
• MemGPT/Letta --引入了具有加载/卸载操作的显式内存层，将LLM上下文视为托管资源。我们的组件挂载/卸载和“感知>上下文”原则来自相同的见解。
• HippoRAG --海马激发了层次检索。这直接塑造了我们从L0到L1到L2的渐进式拆包流程。
• OpenViking --具有抽象/概述/详细级别的分层上下文加载。我们三级指标设计的最直接灵感。
• A-MEM --Zettelkasten风格的自组织笔记的代理记忆。强化了记忆条目应该相互关联的观点。
• Mem0 --内存作为独立的基础架构层。验证了存储计算分离原理。
• 泽普 / 图形 --时间感知知识图。影响了我们的变更日志基于时间的查询和决策可追溯性设计。
• 王的OpenClaw内存管理指南 --一份医生报告，记录了5个具有结构化记忆的代理30天的运行情况。基于温度的衰变模型、“先消化后遗忘”的安全原则、NOW.md压缩恢复模式和CRUD写入验证方法直接受到了本文见解的启发。Open Palace使用代码级保证而不是基于提示的指令来实现这些模式。
• 主控程序 （Anthropic）——使Open Palace主机不可知的协议层。
• 开爪 --我们集成的第一个主机环境。OpenClaw的工作空间文件约定直接塑造了双向同步和入职设计。
• QMD --本地混合搜索引擎（BM25+向量+LLM重新排序）。Open Palace的三层搜索后端使用QMD作为可用的最高质量选项。

进一步阅读： 作者@lijiuer92 --对代理内存架构进行了很好的分析。

许可证

麻省理工学院