Open Agent Memory: persistent agent memory with sources you can inspect

Rocke Dong — Sun, 08 Nov 2026 14:28:53 +0000

An agent can answer well during a conversation and still lose a useful preference or project decision when the next session starts. Keeping the whole history in every prompt makes that history expensive to carry and difficult to inspect.

Open Agent Memory (OAM) is an Apache-2.0, self-hosted memory engine for AI agents. It retains eligible conversations, derives source-backed facts and Insights, and returns relevant evidence with citations. Your agent remains responsible for the final answer.

The v0.0.1 source and release are public, with a PostgreSQL/pgvector deployment, a bundled Memory Inspector, HTTP/OpenAPI integration, and OpenClaw and DeepSeek Harness plugins.

1. Start with a small memory problem

Consider a synthetic user who says:

I prefer vegetarian meals and travelling by train. Please keep my travel plans concise.

Later, a fresh session needs to propose a trip. The useful result is not simply that a database contains the sentence. The relevant preference needs to reach the agent's actual input, and a developer needs to be able to check where it came from.

OAM's first-use path is:

retain an eligible conversation
    -> receive an operation receipt
    -> wait for indexing readiness
    -> recall relevant evidence in a new session
    -> give that evidence to the agent
    -> inspect the original source

A successful retain response means the source and receipt were accepted. It does not mean indexing has finished. That distinction matters when wiring memory into a real application.

2. Conversations, documents and Profiles have different roles

OAM separates three input paths:

Eligible interactions produce learned memory, including facts and source-backed Insights.
Document Resources preserve text, HTML, PDF or image evidence that can be searched alongside learned memory. Uploading a document does not automatically turn its contents into personal facts or Profile content.
Explicit Profile Data supply structured user information through their own input path. A stored User Profile is generated or updated on an explicit refresh request.

For example, a travel brochure can provide a train schedule while a conversation provides a food preference. Both can support an answer, but the brochure should not redefine the user's preferences.

The Memory Inspector lets an authorized user browse memory and follow its source support. It also exposes the separate Resources and Profile workflows. These are tools for checking a result, not a guarantee that model extraction or an agent's final answer is always correct.

3. Try the HTTP path

Start with the public source and versioned image:

git clone https://github.com/rocke2020/open-agent-memory.git
cd open-agent-memory
docker pull ghcr.io/rocke2020/open-agent-memory:0.0.1

The Compose guide explains the remaining setup: configure generation and embedding models, initialize PostgreSQL and runtime roles, run preflight, and start the API and worker. OAM supplies no default model credentials. A model endpoint on the host must also be reachable from its containers.

Create an OAM user and use that user's key for personal memory operations. In API-key mode the root credential administers identities; it cannot substitute for a user key on personal-content routes.

Then run the copyable retain → readiness → recall example. It uses the synthetic travel preferences above, polls the accepted operation, and retrieves cited evidence. It also explains what to inspect if the bounded polling deadline expires.

For a custom agent, put recall before the host's answer-generation call and include the returned evidence within the host's prompt budget. Retain completed, eligible conversation content through the corresponding user scope. Keep authoritative identity in application configuration rather than letting a model choose another user's collection. The HTTP API reference documents these routes and response semantics.

Ordinary recall performs no text-generation call. Query embedding and optional configured reranking may still use model services. Profile reads are separate from recall; fetch the stored Profile explicitly if the host needs it.

4. Use an existing agent plugin

If you already run one of the supported hosts, use its integration guide:

OpenClaw: the plugin provides authorized conversation capture, fast automatic recall, explicit search and exact-ID memory removal.
DeepSeek Harness: the personal-profile plugin captures completed human turns and supplies cited recall for later turns.

Both plugins require a running OAM service and a configured user-scoped credential. Installing a plugin is not proof that its host has captured a completed turn or recalled it successfully. Test a fresh session and inspect the supporting source.

5. Know what you are choosing

OAM is useful to evaluate when you want control over persistent memory, model bindings and source inspection in an existing agent. It is a memory engine rather than a hosted assistant or a replacement for the host's planning and answer logic.

Self-hosted storage does not mean all inference stays local: that depends on the endpoints you configure. Indexing and explicit Profile refresh can incur provider charges. The deployment has operational prerequisites, and the published local application-replica checks do not establish database high availability or physical multi-host resilience.

The repository links release evidence and evaluation reports with their settings and limitations. This introduction does not claim a new benchmark run or a universal accuracy advantage.

If you try OAM in an existing agent, which step is hardest: setup, deciding what may be learned, getting useful context into the answer, or checking a recalled claim? A small reproducible example in the issue tracker is useful feedback; keep credentials and private conversation data out of it.