agentmemory Backend

OpenHuman uses sqlite as the default backend for the Memory trait. For users who already self-host agentmemory, OpenHuman provides an optional backend that proxies all trait calls via agentmemory's REST interface.

Selecting backend = "agentmemory" completely bypasses OpenHuman's SQLite + Embedder path. agentmemory handles storage, embedding, and retrieval; OpenHuman becomes a lightweight REST client.

Use Cases

When to use agentmemory backend:

• You're already running npx -y @agentmemory/agentmemory for Claude Code, Cursor, Codex, OpenCode, or OpenHuman and want to share the same persistent storage
• You want hybrid BM25 + vector + graph retrieval without configuring a separate Embedder on the OpenHuman side
• You prefer agentmemory's lifecycle (merging, retention scoring, automatic forgetting, graph extraction) over OpenHuman's unified storage

When to keep the default SQLite backend:

• You want fully self-contained single-process operation without relying on an external daemon
• You depend on OpenHuman-specific memory tree features (chunking, sealing, summary trees running on top of SQLite storage)

Quick Start

1. Install and start agentmemory (in one terminal):

npx -y @agentmemory/agentmemory

Runs on http://localhost:3111 (REST) and ws://localhost:49134 (engine) by default. First launch generates an HMAC key in ~/.agentmemory/.hmac and prints it once.

2. Configure OpenHuman in config.toml to point to it:

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

3. Restart OpenHuman. Factory skips SQLite path and logs [memory::factory] using agentmemory backend at <url>.

Configuration Fields

Field	Default	Purpose
agentmemory_url	http://localhost:3111	Base URL for agentmemory REST server
agentmemory_secret	none	Optional HMAC bearer token
agentmemory_timeout_ms	5000	Per-request reqwest timeout

When backend == "agentmemory", the following existing MemoryConfig fields are ignored — agentmemory manages its own embedding stack via ~/.agentmemory/.env:

• embedding_provider
• embedding_model
• embedding_dimensions
• sqlite_open_timeout_secs

Field Mapping

OpenHuman's MemoryEntry ↔ agentmemory row data:

OpenHuman Field	agentmemory Field	Description
namespace	project	Defaults to "default" when empty
key	title
content	content
id	id	agentmemory-generated (mem_<rand>)
category: Core	type: "fact"
category: Daily	type: "conversation"
category: Conversation	type: "conversation"
category: Custom(s)	type: "fact" + concepts: [s]	Custom tags merged into concepts array
session_id	sessionIds: [...]	OpenHuman exposes single id; agentmemory persists an array
timestamp	updatedAt (RFC3339)	Falls back to createdAt if updatedAt doesn't exist

RPC Method Mapping

Memory Method	agentmemory REST	Description
store	POST /agentmemory/remember
recall	POST /agentmemory/smart-search	Hybrid BM25 + vector + graph
get	POST /agentmemory/smart-search	+ client-side exact title filter
list	GET /agentmemory/memories?latest=true&project=<ns>
forget	get(ns, key) → POST /agentmemory/forget	Two steps: resolve id then forget
namespace_summaries	GET /agentmemory/projects
count	GET /agentmemory/health
health_check	GET /agentmemory/livez

Security

When agentmemory_secret is set, the client follows agentmemory's v0.9.12 plaintext bearer protection convention:

• Loopback hosts (localhost, 127.0.0.1, ::1) via http:// — allowed
• https:// to any host — allowed
• Plaintext HTTP to non-loopback hosts — one-time stderr warning at construction
• AGENTMEMORY_REQUIRE_HTTPS=1 — upgrades warning to hard rejection

Production deployments should set AGENTMEMORY_REQUIRE_HTTPS=1 so a misconfigured TLS terminator fails loudly rather than silently leaking.

Failure Modes

Failure	Backend Behavior
Daemon unreachable at startup	from_config succeeds (URL parsing), but health_check() returns false
Network timeout	Returns anyhow::Error per trait contract
4xx / 5xx response	anyhow::Error with status and body snippet
Plaintext bearer to non-loopback	One-time warning, request proceeds
Plaintext bearer + AGENTMEMORY_REQUIRE_HTTPS=1	Hard rejection at construction

No automatic fallback to SQLite. If the daemon is down at startup, the backend exposes transport errors loudly.

Next Steps

• Memory Tree - OpenHuman's default SQLite memory storage
• Memory Tools - General memory tools