> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/architecture/memory.md).

# 记忆

crates/openhuman-core/src/memory/ 中的记忆宿主层：TinyMemory 的代理生命周期绑定到 OpenHuman 的轮次、RPC 和 UI。

`crates/openhuman-core/src/memory/` 是 TinyMemory 之上的宿主层。它在每一轮周围运行代理记忆生命周期。前导阶段会立即取用已完成的缓存上下文，并排队执行用户日志记录和刷新；已提交的回复会在后台记录。压缩会使用已完成的上下文，并排队自己的刷新，而不会延迟权威摘要器。信念构建也在后台运行。

其行为定义在 [`docs/specs/memory-v2.md`](https://github.com/tinyhumansai/openhuman/blob/main/docs/specs/memory-v2.md)中。面向用户的功能是 [记忆](/openhuman/zh/gong-neng/memory.md).

## TinyMemory crates（`vendor/tinymemory/crates/`)

| Crate                     | 拥有                                                                                                                                                                                                                                        |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tinymemory-api`          | 引擎契约： `MemoryEngine` （recall、fetch、store、forget、list、consolidate、beliefs）， `StoreItem`, `MemoryMeta`, `MetaFilter`, `Namespace`/`Reach`, `EngineDescriptor`, `Error`。不涉及 I/O。其 `符合性` 特性会加入所有引擎都通过的测试套件，以及内存中的 `ReferenceEngine` 单元测试所使用的。 |
| `tinymemory-tools`        | 任何引擎之上的代理接口： `AgentMemory` (`start_session`, `pre_turn`, `post_turn`, `recall_for_compaction`, `recall`), `MemoryLayout`, `大脑`，整体回忆（`ContextPack`), `BackgroundJob`/`BackgroundRunner`.                                                   |
| `tinymemory-integrations` | 所有与外部世界交互的部分：双链路上的 CortexDB 引擎（`cortexdb` 直接， `tinyhumans` 位于后端之后）、注册表、文档转换和 brain filer、源读取器（受 SSRF 保护）、密钥/PII 清理、v1 导入器。                                                                                                                |

## 宿主模块

| 模块                                 | 角色                                                                                                            |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `引擎`                               | 绑定 `[memory] 引擎`: `tinyhumans` 使用宿主的后端凭据（按请求解析）与传输层的归因标头，或者 `cortexdb` 使用存储为 `memory-cortexdb`的密钥。当两者都不可用时关闭。 |
| `守卫`                               | `ScrubbingEngine`：无论通过哪条路径，每次写入都会按宿主策略进行清理。                                                                   |
| `范围`                               | 将 OpenHuman 配置投射到 TinyMemory `IdentityPins`；调用方使用上游的 `Identity` / `ResolvedIdentity` 用于每一轮。                   |
| `lifecycle::prefetch`              | 用于自动轮次和压缩回忆的有作用域、有上限的内存缓存和后台工作线程。                                                                             |
| `lifecycle::hooks`                 | 生命周期原语；显式/手动 `pre_turn` 和 `压缩` 保留配置的截止时间。                                                                     |
| `lifecycle::jobs`                  | 持久化的后台队列以及 `memory_background` cron 定时任务。                                                                     |
| `lifecycle::views`                 | 用于这些 RPC 的策略、pack 预览、代理列表和任务视图。                                                                               |
| `brain`                            | 已同步项目的大脑源映射以及 `memory_brain_*` 操作。                                                                            |
| `源`                                | 该 `[[memory.sources]]` 注册表并同步到大脑中。                                                                            |
| `通道`                               | 每个已记录线程到达的通道，用于遗忘某个通道。                                                                                        |
| `回填`                               | 在生命周期形态下经同意门控地存储过往聊天。                                                                                         |
| `导入`                               | 经同意门控、可恢复的 v1 导入。                                                                                             |
| `工具`, `tool_budget`, `tool_writes` | 作用域内的代理工具：受限的显式读取，以及对以下内容的持久本地接纳： `学习`/`遗忘`，随后在后台投递。                                                          |
| `操作`, `探索`                         | 引擎选择、回忆、获取、学习、遗忘、列出，以及探索器。                                                                                    |
| `总线`                               | cron 订阅者（`memory_sources_sync`, `memory_background`).                                                         |
| `模式`                               | 该 `openhuman.memory_*` 控制器。                                                                                   |
| `状态`, `错误`, `类型`                   | 子系统状态、错误代码、共享类型。                                                                                              |

## 代理循环调用记忆的地方

| 钩子                       | 文件                                                                                                                      |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| 轮前（取用缓存的 pack，排队日志记录和刷新） | `memory/lifecycle/session_hooks.rs`，来自 `before_turn` 于 `runtime_session.rs`                                             |
| pack 注入，临时的，轮次中的每个模型请求   | `agent/tinyagents/middleware/memory_pack.rs`                                                                            |
| 轮后（记录回复，排队构建），在持久提交之后    | `session_hooks.rs`，来自 `finalize_after_durable_commit`                                                                   |
| 来自已完成缓存的压缩增强，并带有后台刷新     | `agent/tinyagents/memory_summarizer.rs`，在摘要器外层包裹于 `context_wiring.rs` （阶梯顺序和大小定义在 `tinyagents-harness` `ContextLadder`) |

自动 pack 以 CoreContext、workspace、配置指纹、已解析的 memory identity 和线程为键。它们在 60 秒后过期。每个 context 的缓存最多保留 64 个条目，每个 pack 64 KiB；全局 8 个 worker 处理有上限的队列，每个条目最多 16 个待处理操作，每个操作的截止时间为 120 秒。达到饱和时，会跳过尽力而为的自动工作，而不是等待。pack 将自己标识为先前查找的结果，而不是当前问题的权威答案。

成功的内容变更会清除缓存 pack 并推进修订，同时保留排队中的会话日志，并拒绝较早的在途结果。引擎或凭据失效会清空缓存和待处理刷新。作用域内的后台任务会保留 CoreContext；memory identity 是运行上下文上的显式值，而不是任务局部状态。

该代理工具每次调用允许 15 秒，保留的总预留时间为 30 秒，每个保留的运行记录可尝试 8 次。在高 churn 下的空闲驱逐可以重置该运行的预算，而未完成的预留不能被驱逐。 `学习`/`遗忘` 确认的是持久化的本地接纳，而不是远程完成。其已清理的 outbox 条目包含受信任的作用域而不是凭据，并在后台/认证 tick 时由匹配的所有者重试。直接 RPC、UI 和导入/删除工作流保持其显式行为。

该轮的 `MemoryTurn` （config、identity、thread、pack）搭载于 `OpenHumanRunContext::memory_turn`；子运行有自己的。

聊天线程持久化不是记忆。它是 `tinyagents_session::threads`，由 `crates/openhuman-core/src/threads/store`.

MCP 服务器提供 `memory.recall`, `memory.fetch`, `memory.list`, `memory.learn` 和 `memory.forget` (`mcp/server/tools/specs.rs`).

## 测试

* 每个模块旁边的单元测试（`*_tests.rs`），对应 `ReferenceEngine`.
* `tests/memory_v2_e2e.rs`：每个 `memory_*` 针对模拟后端的 RPC，以及一个 Web 聊天轮次，其推理请求携带该 pack，其轮次会记录为 `x-sdk-name`，且其转录中不包含 pack。
* `crates/openhuman-embed/tests/runtime_agents.rs`: `AgentSpec::memory`.
* `app/test/playwright/specs/memory-v2.spec.ts` （UI）。

在真实的 CortexDB 服务器上， `scripts/test-memory-cortexdb-live.sh` 在 Docker 中启动锁定版本的 harness（`vendor/tinymemory/integration/cortexdb/`）并运行 `tests/memory_cortexdb_live.rs`：学习、同步文件夹源、网页聊天轮次日志记录、回忆、pack 预览、注入到轮次的推理请求中的 pack，以及信念构建。除非 `OPENHUMAN_LIVE_CORTEXDB_URL` 已设置，否则会跳过。