# About openclaw-mem

`openclaw-mem` is a **local-first memory governance layer and context supply chain for AI agents** — OpenClaw-native, but not OpenClaw-only.

It gives operators a durable record of what the agent actually did and a practical recall surface they can inspect.
It also gives them a bounded packing surface they can inject, test, and roll back.

## What problem it solves

The hard part is not storing more memory. It is deciding what memory is allowed to become context, then proving why.

Most agent memory stories sound good until you need all of these in production:

- **fresh recall** of what happened recently
- **auditability** for tool outcomes, decisions, and ops breadcrumbs
- **cheap local lookup** before asking a remote semantic system again
- **bounded context assembly** that fits inside a prompt instead of flooding it
- **safe rollback** when a memory backend or embedding path gets weird

`openclaw-mem` exists to make memory and context assembly operational, not opaque.

## What it does today

- **Store**: JSONL/SQLite capture and ingest for local operational memory
- **Pack**: bounded `ContextPack` output with citations, trust policy, and receipts
- **Observe**: `timeline`, `get`, traces, and artifacts for debugging and rollback
- local recall with `search → timeline → get`
- sidecar capture on top of an existing OpenClaw install
- optional promotion to `openclaw-mem-engine` later when hybrid recall and stronger policy controls justify the extra surface
- optional advanced continuity side-car for derived self/continuity inspection, adjudication, public-safe summaries, and explicit control-plane receipts

## How the product is split

### Store (default starting point)

This is the normal starting point.

- captures observations into JSONL
- ingests them into SQLite
- gives you a local recall and pack loop you can inspect
- does **not** replace your active OpenClaw memory backend

### Pack (shipped contract)

When you need a bounded, injection-ready result instead of another search result list, `openclaw-mem pack` emits a stable `ContextPack` object:

- short `bundle_text` for direct injection
- structured items with `recordRef` citations
- optional redaction-safe trace receipts for include/exclude debugging
- protected-tail continuity hooks for caller-supplied recent turns
- graph-aware synthesis preference before final raw-ref admission

This keeps recall, packing, and debugging on one auditable path.

When the optional mem-engine role is active, this same Pack posture extends into live turns as **Proactive Pack**: a bounded pre-reply recall mode with receipts, scope policy, and fail-open behavior.

### Memory engine (optional)

This is the controlled next step when sidecar mode already proved useful.

- supports promotion toward active OpenClaw memory-backend ownership when that extra surface is justified
- adds hybrid recall and tighter policy controls
- exposes **Proactive Pack** for bounded pre-reply recall during prompt build
- keeps rollback explicit and configuration-driven

### Observe (cross-cutting)

Operators also need to see what the system kept, what it cut, and where large raw payloads went.

`openclaw-mem` therefore treats receipts and artifacts as first-class:

- retrieval traces explain pack decisions
- artifact handles keep raw payloads off-prompt but retrievable
- local files stay diffable and backup-friendly

### Governed continuity side-car (optional / advanced)

For operators who need a safer continuity surface, `openclaw-mem` also exposes a derived `continuity` lane.

- builds inspectable current snapshots from memory-of-record
- runs deterministic adjudication before stronger continuity phrasing is allowed
- emits bounded public-safe summaries instead of identity theater
- records explicit weaken / rebind / retire state transitions with replayable receipts

This lane stays derived and rebuildable by design.
It does not become a second truth owner.

## Why local-first matters

A lot of memory tooling gets harder to trust as soon as it becomes harder to inspect.

The local-first posture keeps the base layer simple:

- JSONL for append-only capture
- SQLite for local search and timeline inspection
- exportable artifacts you can diff, back up, and reason about

## Who it is for

- **OpenClaw operators** who want smaller, more inspectable memory packs
- **Agent builders** who want a practical memory layer without jumping straight to a hosted stack
- **Teams with decisions, notes, and specs to remember** who care about evidence and rollback, not just retrieval scores

## What it is not

- not a hosted SaaS memory product
- not a general-purpose memory SDK for every agent framework
- not a generic memory engine competing on retrieval scores alone
- not a requirement to capture everything forever
- not a promise that embeddings alone solve retrieval quality
- not a requirement to replace OpenClaw native memory on day one

## Recommended way to adopt it

1. **Start local** — prove the recall loop on a sample or your own JSONL.
2. **Add the sidecar** — wire capture + harvest into your existing OpenClaw install.
3. **Promote the engine only if needed** — switch slot ownership when hybrid recall and policy controls justify it.

## Read next

- [Why `openclaw-mem` still exists](why-openclaw-mem-still-exists.md)
- [OpenClaw 2026.4.15 comparison](openclaw-2026-4-15-comparison.md)
- [Choose an install path](install-modes.md)
- [Proactive Pack](proactive-pack.md)
- Context supply chain blueprint (maintainer archive; not part of the public evaluator path)
- [Quickstart](quickstart.md)
- [Reality check & status](reality-check.md)
- [Deployment guide](deployment.md)
- [Governed optimize assist lane](optimize-assist.md)
- [Ecosystem fit](ecosystem-fit.md)
- [Mem Engine reference](mem-engine.md)
- [Optional continuity side-car activation](deployment.md#2b-optional-governed-continuity-side-car)
