Memory is Infrastructure,
Not Just Files.
Persistent, shared, and governed memory for OpenClaw agent systems.
Shared Across Agents
Hybrid Retrieval
Multi-Tenant
mem9.ai · Built on TiDB
1
Why Agent Memory Breaks
From single-agent prototype to production fleet — the architectural gap that file-based memory cannot cross.
2
Every Agent System Hits a Structural Ceiling
File-based memory cannot cross the prototype-to-fleet boundary.
Prototype
One agent · local file · works
✓ Works
Growth
Multi-session · files diverge · context lost
Production Fleet
Multi-tenant · no sharing · architecture collapses
3
Memory Silos Block Organizational Intelligence
Without shared infrastructure, context stays local — agents repeatedly rebuild what others already learned.
Personal
Local notes · no reliable transfer · isolated per agent
Team
No shared context across agents
Company
No queryable knowledge base
↑ Facts should flow upward — but never do
↓ Org knowledge should flow down — but is inaccessible
4
The OpenClaw Native Baseline — and Its Limits
Fast to set up for a single agent. Not production memory.
Native Memory ✓
- Markdown files · SQLite index
- Verbatim snippet retrieval
- Zero dependencies · works offline
Native Memory ✗
- No cross-agent sharing
- No typed schema or provenance
- No multi-tenant isolation
5
File-Centric Memory Is Structurally Fragile
Every failure mode is silent — no error, no alert, no recovery.
Forget
Agent omits write → fact lost permanently
Write Wrong
Vague fact persists · no validation
Duplicate
Index bloat · recall quality degrades
Conflict
Two agents contradict · no reconciliation
Failure mode comparison
6
Compaction Is Context Management, Not Memory Modeling
Compaction manages the context window. mem9 manages what the agent knows — permanently.
Compaction
- Summarizes old turns · frees context window
- Session-scoped · agent-triggered
- Does not persist across restarts
mem9 Memory
- Extracts atomic facts · reconciles Insights
- Persistent across sessions and agents
- Queryable · typed · governed
7
mem9 Runtime Pipeline
How mem9 captures, processes, types, and stores every agent interaction — server-side, asynchronously, without blocking the agent.
8
Replacing the File with an API Plugin
One plugin change routes OpenClaw memory through mem9 — no agent retraining required.
OpenClaw Agent
Runs normally
mem9 Plugin Gateway
before_prompt_build · agent_end
mem9 Server Hub
Ingest · Extract · Reconcile · Store
Plugin Contract
before_prompt_build
Retrieve + inject relevant memory into prompt
agent_end
Flush completed turn batch · wait only for ACK
9
Two Hooks, One Non-Blocking Memory Path
What happens at each hook — and what the agent never has to wait for.
① Retrieve
before_prompt_build fires. mem9 returns ranked memory for this agent and context.
② Inject
Relevant facts are prepended to the prompt. Raw session context is excluded.
③ Run
Agent executes with enriched context. No memory writes occur during the turn.
④ Flush
agent_end fires. Plugin POSTs the completed turn batch. Server ACKs; agent is unblocked.
10
Server Pipeline: From Turn Batch to Trusted Memory
Five server-side stages — all off the agent's critical path.
① ACK
Agent released immediately
② Strip
Remove injected context
③ Extract
LLM identifies atomic facts
④ Reconcile
Match or archive existing Insights
⑤ Persist
Write with full provenance
Off Path · All stages run asynchronously — zero agent wait
Durable · Every turn becomes structured memory with lineage
11
Smart Ingest: Extraction Policy and Fact Classification
Only atomic facts become durable memory — everything else is dropped or stored as fallback.
Injected Context Stripped First
Prevents re-extracting known facts.
Size-Aware Batching
Long sessions chunked by token budget.
Schema-Validated Output
Malformed extraction discarded · not stored.
12
Reconciliation Flow: Resolve Facts Without Losing History
Candidate facts are compared against existing Insights. Superseded memories are archived, not erased.
Candidate Fact
Atomic fact + embedding enters reconciliation.
Retrieve Neighbors
BM25 + vector search finds related Insights.
Resolve Outcome
New → ADD · Contradiction → UPDATE · Equivalent → No-op
Versioned Write
ADD appends new Insight. UPDATE archives old + appends replacement. Provenance stays attached.
13
Conflict Handling: Three Guardrails
mem9 resolves stale facts, isolates project context, and prioritizes personal memory before inherited memory.
① Reconcile
- Superseded fact → new Insight + archive old
- Duplicate → no-op
② Isolate
- appId partitions reads/writes inside one Space
- Project memories don't leak across partitions
③ Prioritize
- chain_ key: personal node searched first
- High-confidence hit → early stop
Pinned facts are AI-immutable — agents cannot overwrite operator-approved ground truth.
14
A First-Class Typed Memory Model
Three types. Explicit semantics, mutation rules, and lifecycle for each.
Pinned · Permanent ground truth · AI-immutable · Operator-only writes · Never auto-deleted
Insight · Reconciled atomic facts · ADD or UPDATE+archive · Archivable · Promotable to Pinned
Session · Raw interaction data · Append-only · Hash-deduplicated · Expires by retention policy
15
Recall and Trust
How mem9 retrieves the right memory at the right time — and proves it can be trusted.
16
Recall Engine: Search, Fuse, Rank
mem9 runs keyword and semantic search in parallel, fuses both rankings, then returns a candidate set for confidence evaluation.
CANDIDATE SET QUALITY
· Coverage
BM25 catches exact IDs, names, and recent strings. Vector catches intent and paraphrases.
· Fusion
RRF dedupes overlaps and reduces single-signal bias before ranking.
· Handoff
Candidates carry type, provenance, metadata, and chain_source into Confidence Policy.
Next: Confidence Policy →
17
Confidence Policy: Decide What Is Safe to Inject
After hybrid retrieval returns candidates, mem9 turns evidence into an action: inject, fallback to Session, or suppress.
Match Strength
Keyword + vector agreement across both search signals.
Evidence Shape
Literal answer, source type, and provenance metadata.
Freshness & Scope
Recency, appId, Space, and chain_source alignment.
Score
Combined signal weight
Score + Threshold + Source Prior
The policy layer evaluates all signals and emits a single decision.
Source Prior
Pinned > Insight > Session
Inject
High-confidence Insight enters the prompt context.
Fallback
Raw Session used when exact evidence is required.
Suppress
Low-confidence or stale match is withheld entirely.
18
Dual-Layer Memory: Facts First, Session as Fallback
Insights surface first. Raw Session provides full-fidelity fallback when precision matters.
Layer 1 — Insights (Primary)
Reconciled atomic facts · Deduplicated · Searched first · Best for: preferences · background · current state
Layer 2 — Raw Session (Fallback)
Verbatim records · Append-only · Searched when Insights don't satisfy · Best for: exact recall · time-based · verbatim evidence
19
Provenance: Per-Object Metadata on Every Memory Write
Set by the server at write time — not by the agent. Travels with the object through its lifecycle.
Written at Ingest · server stamps agent_id, session_id, appId, metadata, and timestamps
Travels with the Object · visible in Explorer and preserved on archive/supersede history
chain_source on Chain Recalls · adds chain_id, node_position, tenant_id, external_space_id
20
Spaces, appId, and Space Chain
The isolation, inheritance, and routing model that makes mem9 safe for multi-tenant, multi-app, and multi-team deployments.
21
Space: Bounded, Governed Memory Context for a Tenant
A Space is the fundamental memory unit — one tenant, one API key, one governed context.
Tenant Boundary
One Space = one tenant · appId provides finer partitioning within
API Key Access
Each Space accessed via API key · Keys rotatable and revocable
Unified Recall API
BM25 + vector hybrid · filterable by type · state · appId · agent · tags
Governed Lifecycle
Explicit creation/deletion · active/archived states · retention policies per Space
22
appId: Optional Application Isolation Within a Space
appId scopes memory/session writes and read filters within one Space; it is not a separate tenant.
— Write Rules
appId: "support"
Writes belong to the support sub-space
omitted / null / empty / whitespace appId
Writes belong to the default/global appId
API key ownership
Permissions, quota, and billing do not change regardless of appId
— Query Rules
omitted appId
Searches across all appIds under the API key
non-empty appId
Searches only that exact sub-space
appId=null or appId=""
Searches only the default/global appId
Use non-empty appId for app isolation; omit appId only when broad cross-app recall is intended.
23
Space Chain: Ordered Linear Chain of Spaces
An ordered linear sequence of Spaces accessed via a single chain_ key — not a graph.
Node 0 — First Active Node
Default ADD target · Recall starts here · No routing policy
Node 1 — Middle Node
Searched after Node 0 · Natural-language routing policy · Write or webhook-only
Node 2 — Last Node
Broadest scope · Routing policy · chain_source identifies this node
Ordered Traversal
Recall searches nodes in sequence · high-confidence early stop ends search
scanAll Mode
Searches all nodes · reranks aggregate · chain_source on every result
chain_ Key
Distinct from Space API keys · encodes ordered node list + traversal config
24
Space Chain Recall: Early Stop and scanAll
Two modes control the precision-vs-coverage tradeoff. Both return chain_source provenance on every result.
Early Stop
Stops at first node with high-confidence result · fastest path · chain_source included
scanAll
Searches all nodes regardless of confidence · aggregate reranked · chain_source on every result
25
Space Chain Writes: First Active Node, Locate-by-ID
ADD goes to the first active node. UPDATE and DELETE locate the owning node by ID — no broadcast.
ADD → First Active Node
All new writes via chain_ key go to Node 0 · most specific Space in the chain
UPDATE / DELETE → Locate-by-ID
Server finds the object across chain nodes · writes only to owning node
No Automatic Propagation
Routing policies on non-first nodes control ingest-time routing · not direct writes
26
Routing Policies: Natural-Language Prompts on Non-First Nodes
After extraction, each fact is evaluated against non-first node policies — write, webhook-only, or no match.
Extraction Complete
Classified facts with confidence scores.
Each is a routing candidate.
First Node Reconcile (always)
Candidate evaluated against Node 0 memory.
ADD / UPDATE+archive / No-op · Node 0 is the default target and has no routing policy.
memory.added fires only when a new object is written.
Non-First Node Policy Eval
Natural-language prompt per node.
Write · Webhook-only · No match
Routing Outcome
Write: fact stored in target Space; memory.added fires when ADD creates a memory.
Webhook-only: space_chain.fact_routed emitted.
No match: not routed.
27
Console and Automation
The operator interface for governing, inspecting, analyzing, and automating mem9 — without writing a single API call.
28
Console Hierarchy: Organization → Project → Space → Key
Four levels. Each with a distinct scope and responsibility.
Organization · Top-level account boundary · all Projects and Spaces belong here
Project · Logical grouping of Spaces · organize by product · team · or deployment
Space · Fundamental memory unit · API key · appId partitions · retention · recall config
Key · API key for Space or chain_ access · create · rotate · revoke from Space detail
29
Space Detail: Key Metrics, Imports, and Memory Workbench
The operator's primary workspace — live metrics, import tooling, and direct memory management.
Key Metrics
- Total objects by type: Pinned / Insight / Session
- Active vs archived counts
- Recall request count · sessions ingested
- Average confidence score across Insights
Space Configuration
- API key assignment and rotation
- appId partition list with per-appId counts
- Retention policy: Session expiry · Insight archival
- Recall default: early stop vs scanAll
Import Tooling
bulk import via CSV · JSON · or API · typed + provenance-stamped
Memory Workbench
browse · search · filter · bulk archive · pin · export
Mutation Metadata
operator identity · timestamp · operation type per object
30
Memories Explorer: Browse, Filter, and Manage Memory Objects
Full-text search and multi-dimension filtering — all within the Console, no API calls.
Text Search
Full-text across content + metadata · ranked by relevance
Filter by Type
Pinned · Insight · Session · combinable
Filter by State
Active or archived · archived objects remain queryable
Filter by Agent
Tags · appId · multi-select · scope to specific partition
31
Memory Analysis and Deep Analysis
Both run off the hot path. All recommendations require explicit operator action.
Taxonomy
categorizes objects by topic + entity type · filterable in Memories Explorer
Duplicate Cleanup
identifies near-duplicate Insights · operator reviews + archives · no auto-delete
Deep Analysis
operator-initiated · generates insight reports: knowledge gaps · stale facts · summary Insights
Insight Reports
advisory only · operator decides which recommendations to act on
32
Webhooks: React to Memory Events Without Polling
Signed JSON over HTTPS. Push, not pull. Three event types. No polling required.
Push, Not Pull
events delivered to your endpoint when they occur · no polling · no Recall API quota
Signed JSON over HTTPS
signing_secret provided once at creation or rotation · HMAC verified per delivery
Retry with Backoff
failed deliveries retried with exponential backoff · full delivery history in Console
33
Webhook Lifecycle: Configure → Sign → Deliver → Retry → Inspect
The signing_secret is provided once — store it securely. All steps visible in the Console.
Configure · Register HTTPS endpoint · select event types · set scope: Space or Space Chain
Sign · signing_secret generated once · store securely · HMAC verifies every delivery · rotate to invalidate
Deliver · Event fires → POST signed JSON to endpoint · payload: event type · object data · provenance · timestamp
Retry · Non-2xx or timeout → exponential backoff · failed deliveries logged with response code + latency
Inspect · Console shows full delivery history · event type · payload · response code · latency · retry count · manual re-trigger
HTTPS Required in Production · HTTP only in development environments
Scoped Subscriptions · one Space or one Space Chain per webhook
signing_secret Rotation · old secret immediately invalidated · no grace period overlap
34
Webhook Events: memory.added, memory.deleted, space_chain.fact_routed
Three supported event types. Each payload carries the event type, timestamp, and the relevant memory or routing data.
memory.added
Trigger: Direct writes · pinned writes · smart ingest ADD · successful routed target writes
- memory.id · content · memory_type · agent_id · session_id · appId · tags · metadata · created_at · updated_at
Note: Smart ingest UPDATE-only reconciliation does not emit memory.added
memory.deleted
Trigger: Single-memory or batch delete succeeds
- memory.id · tenant_id · deleted_by_agent · deleted_at
Note: Hard delete only · archive does not fire
space_chain.fact_routed
Trigger: Non-first-node routing policy matches a fact
- route_id · chain_id · source_tenant_id · target_tenant_id · target_external_space_id · routing_policy_node_id · source_facts · target_memory · webhook_only · agent_id · appId · session_id
Note: Emitted for routed writes and webhook-only routing; failed/quota-denied target writes do not emit a routed-write event
Only these 3 event types are supported. There is no memory.updated event; UPDATE-only reconciliation archives/supersedes internally and does not emit memory.added or memory.deleted.
35
Deployment and Differentiation
How mem9 deploys, what makes it different, and why the architecture matters for production agent fleets.
36
Four Cooperating Planes: Runtime · Control · Visualization · Analysis
Four planes. One complete memory infrastructure. Agent touches only the Runtime.
Runtime Plane — Always On
Go server · TiDB (SQL + vector) · Ingest · Smart Pipeline · Hybrid Recall · Provenance on every write
Control Plane — Operator Interface
API key management · Space config · Space Chain · Webhook config · signing_secret rotation
Visualization Plane — Human Window
Memories Explorer · Space detail · Memory Analysis · Deep Analysis reports
Analysis Plane — Off-Path Intelligence
Taxonomy · Duplicate detection · Deep Analysis jobs · All outputs advisory · operator approval required
Agent touches only the Runtime Plane
Control · Visualization · Analysis are operator-facing only
Analysis Plane is always async
Never on the hot path · never blocks agent recall
37
Ecosystem Flexibility: OpenClaw-First, API-First, Self-Hosted or Managed
Runs wherever your agents run — self-hosted, managed, or hybrid. No vendor lock-in.
Self-Hosted
- Full data sovereignty · your infrastructure
- Custom retention and lifecycle policies
- Bring your own embedding model
Managed (mem9.ai)
- mem9 operates the runtime on your behalf
- Managed embedding and indexing pipeline
- Console access without operating the runtime
Embedding Model Agnostic
pluggable models · no vendor lock-in on vector layer
OpenClaw Native
drop-in replacement · one config change · no agent retraining
API-First
every capability via REST API · integrate with any framework or stack
Framework Agnostic
REST API works with any agent framework · not OpenClaw-specific
38
Enterprise Memory Scorecard
OpenClaw Native vs mem9 — production readiness across 12 dimensions.
39
OpenClaw Native helps an agent keep notes.
mem9 helps a fleet of agents keep memory.
Governed
Typed writes · Pinned facts · Provenance on every object
Isolated
Space-level tenant isolation · appId-level app isolation
Persistent
Space Chains · Cross-session continuity · Cold-start solved
mem9.ai · Built on TiDB
40