agentmemory 后端

OpenHuman 默认使用 sqlite 作为 Memory trait 的后端。对于已经自托管 agentmemory 的用户，OpenHuman 提供了一个可选后端，通过 agentmemory 的 REST 接口代理所有 trait 调用。

选择 backend = "agentmemory" 会完全绕过 OpenHuman 的 SQLite + Embedder 路径。agentmemory 拥有存储、嵌入和检索层，OpenHuman 变成一个轻量级 REST 客户端。

使用场景

使用 agentmemory 后端的情况：

您已经在为 Claude Code、Cursor、Codex、OpenCode 或 OpenHuman 运行 npx -y @agentmemory/agentmemory，希望共享同一个持久化存储
您想要混合 BM25 + 向量 + 图检索，而不想在 OpenHuman 端配置独立的 Embedder
您更偏好 agentmemory 的生命周期（合并、保留评分、自动遗忘、图谱提取）而非 OpenHuman 的统一存储

保持默认 SQLite 后端的情况：

您想要完全自包含的单进程操作，不依赖外部守护进程
您依赖 OpenHuman 特定的记忆树功能（在 SQLite 存储之上运行的 chunking、sealing、summary trees）

快速开始

安装并启动 agentmemory（在一个终端中）：

npx -y @agentmemory/agentmemory

默认运行在 http://localhost:3111（REST）和 ws://localhost:49134（引擎）。首次启动会在 ~/.agentmemory/.hmac 生成 HMAC 密钥并打印一次。

在 config.toml 中配置 OpenHuman 指向它：

[memory]
backend = "agentmemory"
# 下面的默认值 - 只有需要覆盖时才设置
# agentmemory_url        = "http://localhost:3111"
# agentmemory_secret     = ""           # HMAC bearer token，可选
# agentmemory_timeout_ms = 5000

重启 OpenHuman。工厂会跳过 SQLite 路径并记录 [memory::factory] using agentmemory backend at <url>。

配置字段

字段	默认值	用途
`agentmemory_url`	`http://localhost:3111`	agentmemory REST 服务器的基础 URL
`agentmemory_secret`	无	可选的 HMAC bearer token
`agentmemory_timeout_ms`	`5000`	每个请求的 reqwest 超时时间

当 backend == "agentmemory" 时，以下现有 MemoryConfig 字段被忽略——agentmemory 通过 ~/.agentmemory/.env 管理自己的嵌入栈：

embedding_provider
embedding_model
embedding_dimensions
sqlite_open_timeout_secs

字段映射

OpenHuman 的 MemoryEntry ↔ agentmemory 行数据：

OpenHuman 字段	agentmemory 字段	说明
`namespace`	`project`	空时默认为 `"default"`
`key`	`title`
`content`	`content`
`id`	`id`	agentmemory 生成的 (`mem_<rand>`)
`category: Core`	`type: "fact"`
`category: Daily`	`type: "conversation"`
`category: Conversation`	`type: "conversation"`
`category: Custom(s)`	`type: "fact"` + `concepts: [s]`	自定义标签合并到 concepts 数组
`session_id`	`sessionIds: [...]`	OpenHuman 暴露单个 id；agentmemory 持久化一个数组
`timestamp`	`updatedAt` (RFC3339)	如果 `updatedAt` 不存在则回退到 `createdAt`

RPC 方法映射

`Memory` 方法	agentmemory REST	说明
`store`	`POST /agentmemory/remember`
`recall`	`POST /agentmemory/smart-search`	混合 BM25 + 向量 + 图
`get`	`POST /agentmemory/smart-search`	+ 客户端精确 title 过滤
`list`	`GET /agentmemory/memories?latest=true&project=<ns>`
`forget`	`get(ns, key)` → `POST /agentmemory/forget`	两步：解析 id 然后遗忘
`namespace_summaries`	`GET /agentmemory/projects`
`count`	`GET /agentmemory/health`
`health_check`	`GET /agentmemory/livez`

安全

当设置了 agentmemory_secret 时，客户端遵循 agentmemory 的 v0.9.12 明文 bearer 保护约定：

环回主机 (localhost, 127.0.0.1, ::1) 通过 http:// —— 允许
https:// 到任何主机 —— 允许
到非环回主机的明文 HTTP —— 在构造时发出一次性 stderr 警告
AGENTMEMORY_REQUIRE_HTTPS=1 —— 将警告升级为硬性拒绝

生产部署应设置 AGENTMEMORY_REQUIRE_HTTPS=1，以便配置错误的 TLS 终结器会大声失败而不是静默泄露。

故障模式

故障	后端行为
守护进程在启动时不可达	`from_config` 成功（URL 解析），但 `health_check()` 返回 false
网络超时	按 trait 合约返回 `anyhow::Error`
4xx / 5xx 响应	带状态和 body 片段的 `anyhow::Error`
明文 bearer 到非环回主机	一次性警告，请求继续
明文 bearer + `AGENTMEMORY_REQUIRE_HTTPS=1`	在构造时硬性拒绝

没有自动回退到 SQLite。 如果守护进程在启动时宕机，后端会大声暴露传输错误。

下一步

记忆树 - OpenHuman 默认的 SQLite 记忆存储
记忆工具 - 通用记忆工具

使用场景​

快速开始​

配置字段​

字段映射​

RPC 方法映射​

安全​

故障模式​

下一步​