OpenClaw Memory Architecture

Canonical markdown page for this topic. Rendered reference version: openclaw-memory-architecture.

Last Updated: 2026-03-28 Status: Active architecture reference

This document describes the current memory architecture for OpenClaw inside Jorvis.

It is the canonical reference for:

memory-search runtime truth
scope boundaries
namespace behavior
the difference between runtime contract and operational policy

Current Scope Model

OpenClaw memory behavior in Jorvis currently has three important layers:

Chat/session memory routing in the Open WebUI bridge
OpenClaw gateway memory-search configuration
Jorvis-side internal memory API contract

These layers are related but not identical.

1. Bridge-Level Session and Scope Routing

Current bridge logic lives in:

analytics-platform/deploy/openwebui/functions/openclaw_bridge.py

Current behavior:

deterministic session keys are generated from environment, tenant, user, and scope context
the bridge distinguishes user/admin/reference-oriented behaviors
tenant-aware scoping exists in the current OpenClaw/session-memory path

This bridge logic is the current routing mechanism, but it is not the long-term desired control plane.

2. OpenClaw Memory-Search Runtime Truth

Current runtime truth comes from:

deploy/openclaw/openclaw.json
deploy/openclaw/boot-openclaw.sh

Canonical current values:

provider = gemini
model = gemini-embedding-2-preview
fallback = none

Important clarification:

this is the embedding/search lane
it is not the same as the OpenClaw chat model lane
the live semantic store was intentionally reset/rebuilt onto this model on 2026-03-28 because historical semantic memory was treated as disposable
gemini-embedding-001 remains a rollback-only baseline for this lane; do not mix vector spaces in the same active store

Do not put chat-model IDs into the memory-search embedding slot.

3. Jorvis-Side Internal Memory API

Current Jorvis-side internal surface lives in:

analytics-platform/src/internal/openclaw-memory.types.ts
analytics-platform/src/internal/openclaw-memory.service.ts
analytics-platform/src/internal/openclaw-memory.controller.ts

This surface is responsible for:

exposing internal query
exposing internal stats
exposing internal purge
exposing internal search-config

Current important nuance:

the runtime OpenClaw memory-search contract is stable
the Jorvis-side search-config response contract is now aligned to that runtime truth after PR #399

Runtime Contract vs Operational Policy

These must be kept separate.

Runtime contract

This is what the active OpenClaw config exposes and uses:

provider
model
fallback

Operational policy

This is Jorvis-side boot or safety policy around that runtime:

whether a provider API key is required at startup
whether bootstrap should fail fast
how environment variables are mapped before OpenClaw starts

Example:

OPENCLAW_MEMORY_PROVIDER_REQUIRED is an operational/boot-time policy input
it is not part of the canonical active memory-search response contract

Current Constraints

The bridge still owns too much memory-routing truth.
Memory architecture is current-state and operationally useful, but not yet the final control-plane design.

Future Expansion

These are future directions, not active guarantees:

clearer separation of user, admin, and reference memory layers
richer durable user/work memory semantics
stronger operator/admin memory boundaries
Jorvis-side typed capability/control surface

Do not describe those items as already implemented unless the corresponding runtime/code/docs changes are merged.

What This Doc Does Not Cover

This doc does not define:

full future capability registry
plugins/skills memory semantics
multi-agent binding memory semantics
external channel memory routing

Those should be documented only after implementation.

docs/operations/OPENCLAW_RUNTIME_OPERATIONS.md
docs/configuration/MODEL_POLICY_CURRENT.md
docs/operations/OPENWEBUI_MODEL_SETUP.md
docs/agent_ops/OUTBOX/task_openclaw_search_contract_normalization_20260306.md