Memory that actively forms around what matters.
Formative Memory is an OpenClaw plugin that gives your agent a self-optimizing memory. It strengthens relevant context through use, weakens unused details, and automatically builds associations between related concepts. In each session, it helps by injecting relevant memories into context before every response. It also evaluates memory quality — each retrieval affects the strength of the memory, so useful ones rise and unused ones fade. Every night, your agent sleeps: a consolidation process prunes and combines memories to keep the quality of recalled context high.
Over time, this combination process builds beyond raw facts into interpretations, nuanced awareness, and deeper understanding.
Before every response, the plugin searches for memories relevant to the current conversation using hybrid search (embedding similarity + BM25 full-text), ranked by memory strength. Matching memories are injected into the agent's context automatically. Each retrieval strengthens the memories that were surfaced.
User: "Do you remember that restaurant? The one by the beach
last summer. I'm trying to book for our anniversary."
Injected memories:
[a3f2|fact|strength=0.82] "Dinner at Maininki, Hanko, July 2024"
[b7d1|event|2026-07-04] "Wedding anniversary — 12 years"
[c9f3|preference|str=0.74] "Sanna loves peonies"
[d2e6|fact|2026-07-02] "Sanna: private doctor's appointment"
Agent: "Of course! It was Maininki, in Hanko. Shall I book a table?
Your 12th anniversary is coming up on July 4th."
The agent sees recalled memories as context, not instructions — this reduces prompt injection risk from stored content.
Memories are collected in two ways. The agent can store a memory
explicitly with memory_store, and auto-capture extracts durable
facts from conversations automatically after each turn.
After the turn above, auto-capture extracts:
→ store("Booking anniversary dinner at Maininki", type: event,
temporal_anchor: 2026-07-04, temporal_state: future)
A later turn — user asks for Sanna's favorite foods:
Agent explicitly stores:
→ memory_store("Sanna's favorites: salmon soup (her mother's recipe,
no cream), pistachio ice cream, meat pies from Market Hall
on Saturdays", type: preference)
→ id: e8b2a1f4, strength: 1.0
Each memory is content-addressed (SHA-256) — same content always produces the same ID, so duplicates are prevented by design.
Every night, the agent sleeps. A consolidation process runs through the accumulated memories:
| Step | What happens |
|---|---|
| Reinforce | Memories that influenced responses gain strength |
| Decay | All strengths decrease — recent memories fade faster than established ones |
| Associate | Memories retrieved together form links; connections grow stronger with co-occurrence |
| Temporal shift | Future memories transition to present or past based on anchor dates |
| Prune | Weak memories and associations are removed |
| Merge | Similar memories are combined into coherent summaries |
Before consolidation:
[a3f2|strength=0.82] "Dinner at Maininki, Hanko, July 2024"
[f1c4|strength=0.65] "Maininki — beachfront restaurant, good wine list"
[a9b3|strength=0.41] "Tried booking Maininki in June, fully booked"
After consolidation:
[g7e2|strength=1.00] "Maininki, Hanko: beachfront restaurant with good
wine list. Visited July 2024. Book early — fills up in summer."
Associations formed:
"Maininki" ←0.7→ "Wedding anniversary"
"Maininki" ←0.4→ "Sanna loves peonies"
All mutation happens during consolidation — live chat stays fast and predictable. Over time, simple facts combine into richer structures: merged summaries, connected associations, and deeper understanding.
Install the plugin:
openclaw plugins install formative-memoryThis installs from npm, enables the plugin, and assigns it the memory slot automatically. Restart the gateway to load the plugin.
That's it. The plugin works out of the box:
- Auto-capture records conversations for consolidation
- Auto-recall surfaces relevant memories before every response
- Consolidation runs automatically to maintain memory quality
No configuration needed — sensible defaults are built in.
The plugin registers five tools the agent can use during conversation:
| Tool | What it does |
|---|---|
memory_store |
Store a new memory with type and optional temporal anchor |
memory_search |
Search by meaning and keywords, ranked by relevance x strength |
memory_get |
Retrieve a specific memory by ID |
memory_feedback |
Rate a memory's usefulness (1-5) — feeds into reinforcement |
memory_browse |
Browse all memories sorted by importance, with type diversity |
Memory types: fact, preference, decision, plan, observation.
All settings are optional — defaults are designed to work out of the box.
Configuration goes in openclaw.json under the plugin entry:
{
"plugins": {
"entries": {
"formative-memory": {
"enabled": true,
"config": {
"autoRecall": true,
"autoCapture": true,
"requireEmbedding": true,
"embedding": {
"provider": "auto"
}
}
}
}
}
}| Key | Default | Description |
|---|---|---|
autoRecall |
true |
Inject relevant memories into context before every response |
autoCapture |
true |
Automatically capture conversations for consolidation |
requireEmbedding |
true |
Require a working embedding provider. Set false to allow BM25-only fallback |
embedding.provider |
"auto" |
Embedding provider: auto, openai, gemini. Additional providers (voyage, mistral, ollama, local) are also accepted when memory-core embedding adapters are installed as a fallback registry |
embedding.model |
— | Override the provider's default embedding model. Only takes effect with an explicit embedding.provider — ignored in "auto" mode to avoid passing a provider-specific model name to the wrong provider |
dbPath |
~/.openclaw/memory/associative |
SQLite database location |
verbose |
false |
Enable debug logging |
logQueries |
false |
Include raw query text in debug logs (disabled by default for privacy) |
The "auto" provider selects the best available embedding provider from
your configured API keys. When requireEmbedding is true (the
default), the plugin will not start without a working embedding provider.
Set it to false to allow graceful degradation to keyword-only search.
API keys are read from OpenClaw's auth-profiles.json. Environment
variables are not used. Configure a profile under the standard
OpenClaw setup:
{
"version": 1,
"profiles": {
"openai:default": { "type": "api_key", "key": "sk-..." },
"google:default": { "type": "api_key", "key": "AIza..." }
}
}The openai:default and google:default profile names are picked up
automatically. If you have multiple profiles for the same provider
(e.g. openai:work and openai:personal), the plugin warns and picks
the first one — add a :default profile to select explicitly.
The plugin pins the selected provider and model to the database on
first successful resolution. On subsequent runs, the same provider and
model are used regardless of embedding.provider in config — this
prevents silent drift that would corrupt the vector store when a
different provider (producing different-dimension vectors) takes over.
If you intentionally want to switch providers or models for an existing database, you must re-embed all memories via migration. Attempting to change the configured provider mid-life produces a clear error at startup rather than silent corruption.
OpenClaw Runtime
|
|-- Context Engine --- assemble() -> auto-recall into context
| (budget-aware) afterTurn() -> log exposures + attributions
|
|-- Memory Tools ----- memory_store - create memory
| (agent-initiated) memory_search - hybrid search
| memory_get - lookup by ID
| memory_feedback - rate usefulness
| memory_browse - browse by importance
|
+-- Consolidation ---- reinforce -> decay -> associate -> transition
(automatic) -> prune -> merge (LLM) -> cleanup
Storage: SQLite with FTS5 for full-text search. Single file, no external services.
Embedding: Standalone fetch-based clients for OpenAI and Gemini
read keys from auth-profiles.json. Additional providers (Voyage,
Mistral, Ollama, local) resolve through memory-core's embedding
adapter registry when installed. Circuit breaker with graceful fallback
to keyword-only search when requireEmbedding is false.
Consolidation LLM: Uses Anthropic (Claude) or OpenAI for memory merging. Runs only during consolidation, not during normal chat.
Automatically recalled memories are framed as reference data, not instructions. This reduces prompt injection risk from stored memory content, but memory remains untrusted input — the framing is probabilistic, not a hard security boundary.
Do not store secrets (API keys, passwords) in memories. They will be surfaced to the model during recall.
A standalone diagnostic CLI operates directly on the SQLite database — no OpenClaw runtime needed:
memory stats <memory-dir> # Database overview
memory list <memory-dir> # List memories (filterable)
memory inspect <memory-dir> <id> # Detailed view of a single memory
memory search <memory-dir> <q> # Search by content
memory export <memory-dir> # Export to JSON
memory history <memory-dir> # Retrieval history
memory graph <memory-dir> # Association graphCentralized logging with configurable verbosity. By default only significant events are logged (info level).
Enable debug logging:
{ "verbose": true }| Level | What |
|---|---|
| info | Memory stored, memories injected into context, circuit breaker state changes |
| debug | Search results, embedding fallback reasons, cache hit/miss, consolidation timing |
| warn | Circuit breaker opening (degraded to keyword-only), recall failures |
All log lines are prefixed with [formative-memory] [level] for easy
filtering. Query text is never included in logs by default — set
logQueries: true to opt in.
- How Associative Memory Works — conceptual guide
- Architecture — storage, retrieval, provenance, consolidation
- Comparison with OpenClaw built-in memory — technical comparison
- Glossary — terminology
pnpm install # Install dependencies
pnpm build # Build (tsdown)
pnpm test # Run tests (vitest)
pnpm lint # Lint (oxlint)
pnpm check # Full check (format + typecheck + lint)Requires Node.js >= 22.12.0, pnpm 10.x.
Contributions welcome. Areas where help is especially useful:
- Consolidation algorithm tuning and evaluation
- Embedding model benchmarks
- Adapters for other AI coding agents
- Documentation and examples