# openclaw-mem v0.5.9 Adapter Spec (archived)

> Archived historical reference for the v0.5.9 adapter-annotation rollout.
> Current stable: v1.x. See: `ecosystem-fit.md` and `deployment.md`.


## Goal
Keep `openclaw-mem` valuable in **both** memory backends:
- `memory-core` (native `memory_search` / `memory_get`)
- `memory-lancedb` (official `memory_store` / `memory_recall` / `memory_forget`)

without re-owning canonical memory tools or introducing slot conflicts.

---

## Non-goals (explicit)
- Do **not** register `memory_store` / `memory_recall` / `memory_forget` inside `openclaw-mem`.
- Do **not** replace `plugins.slots.memory` behavior.
- Do **not** require config migrations for existing users.

---

## Design

### 1) Capture plugin stays sidecar-only
`extensions/openclaw-mem` continues to only listen on `tool_result_persist` and append JSONL.

### 2) Backend-aware adapter annotations
Add optional metadata into captured rows (`detail_json`) so downstream SQLite recall/triage can understand backend context:
- `memory_backend` (resolved from `plugins.slots.memory` when `backendMode=auto`)
- `memory_backend_ready` (entry enabled check)
- `memory_backend_mode` (`auto` / pinned)
- `memory_tool` (whether current tool is in memory tool set)
- `memory_operation` (`store|recall|forget|search|get` when matched)

### 3) Ingest preserves extra JSONL fields
`openclaw-mem ingest` merges unknown top-level fields into `detail_json` (backward compatible), so adapter metadata is queryable.

### 4) CLI backend monitor
New command:
- `openclaw-mem backend --json`

Output includes active slot, enabled flags, lancedb key readiness, and fallback posture guidance.

---

## Config additions (plugin)
- `backendMode`: `auto|memory-core|memory-lancedb` (default `auto`)
- `annotateMemoryTools`: `boolean` (default `true`)
- `memoryToolNames`: `string[]` (default canonical memory tool names)

All are optional; existing config keeps working.

---

## Rollout plan
1. Release `0.5.9` with adapter annotations + backend CLI.
2. Enable `memory-lancedb` as active slot in OpenClaw config.
3. Keep `openclaw-mem` enabled to capture + annotate memory tool outcomes.
4. Observe logs + JSONL + `openclaw-mem backend` for readiness.
5. If regressions appear: switch slot back to `memory-core` (no uninstall required).

---

## Rollback / fallback
Single-switch fallback:
- `plugins.slots.memory: "memory-core"`

`openclaw-mem` remains unchanged and continues capture in both modes.

---

## Success criteria
- `memory-lancedb` tools are callable when slot is active.
- Captured rows include backend/action metadata in `detail_json`.
- `openclaw-mem backend --json` reports expected slot/readiness.
- Reverting slot to `memory-core` restores previous baseline without code changes.
