@matrixorigin/thememoria 0.4.0 → 0.4.1

package/README.md

@@ -2,165 +2,90 @@
 
 This package turns [MatrixOrigin Memoria](https://github.com/matrixorigin/Memoria) into an installable OpenClaw `memory` plugin.
 
-The plugin targets the current Rust Memoria CLI and API release line. Installer release tag is configurable via `--memoria-version` / `MEMORIA_RELEASE_TAG`. There is no bundled Python runtime, no virtualenv, and no `pip install` step.
-
 ## Architecture
 
-- `backend: "embedded"` runs the Rust `memoria` CLI locally via `memoria mcp --db-url ... --user ...`
-- `backend: "http"` connects to an existing Rust Memoria API server
-- OpenClaw keeps its own tool and hook surface, but the storage and retrieval backend is Memoria
+| Backend | Transport | Binary needed | Use case |
+|---------|-----------|---------------|----------|
+| `embedded` | Rust `memoria` CLI → local MatrixOne DB | Yes | Self-hosted / local dev |
+| `api` | Direct HTTP → Memoria REST API | No | Cloud OpenClaw, any environment |
+
+```
+api mode:
+  Plugin → MemoriaHttpTransport → fetch() → Memoria REST API
 
-In practice that means:
+embedded mode:
+  Plugin → MemoriaMcpSession → spawn("memoria mcp") → local MatrixOne DB
+```
 
-- durable memory still lives in MatrixOne
-- snapshots, rollback, branches, merge, diff, governance, reflect, and entity extraction are handled by Rust Memoria
-- the plugin shells out to the `memoria` binary instead of importing bundled backend code
-- the `memoria` binary is required even in cloud mode — it serves as the local MCP stdio bridge between OpenClaw and the Memoria backend
+- Durable memory lives in MatrixOne
+- Snapshots, rollback, branches, merge, diff, governance, reflect, and entity extraction are handled by Memoria
+- In `embedded` mode the plugin shells out to the `memoria` binary via MCP stdio
+- In `api` mode the plugin calls the Memoria REST API directly — no binary needed
+- OpenClaw keeps its own tool and hook surface; the storage backend is Memoria
 
 ## Quick Start
 
-### Preflight
-
-Verify prerequisites before installing:
+### Prerequisites
 
 ```bash
 openclaw --version
 # -> OpenClaw vX.Y.Z (CLI is installed and in PATH)
-
-memoria --version 2>/dev/null || echo "not installed (installer can install it)"
-# -> memoria X.Y.Z or fallback message
-
-openclaw plugins list
-# -> command succeeds and prints plugin table
 ```
 
-Assume OpenClaw is already installed and healthy.
-
-### Usage Paths
-
-1. GitHub README (this file): cloud-first setup plus local setup.
-2. OpenClaw chat/agent: user asks agent to install, agent runs commands and returns raw outputs.
-
-### 1) Cloud (Recommended)
-
-Cloud is the default path for new users.
+### Cloud Setup (Recommended)
 
-#### Developer Flow
+Cloud mode connects directly to the Memoria REST API. No binary download needed.
 
 ```bash
-# A0. Optional cleanup (if you installed an older/source-linked memory-memoria before)
-openclaw plugins uninstall memory-memoria
-```
-
-```bash
-# A0.5. Ensure memoria CLI exists (required even for cloud mode)
-command -v memoria >/dev/null || \
-  curl -sSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/scripts/install.sh | bash -s -- -y -d ~/.local/bin
-```
-
-```bash
-# A1. Install plugin from npm
+# 1. Install plugin
 openclaw plugins install @matrixorigin/thememoria
-openclaw plugins enable memory-memoria
-# Note: OpenClaw may print "Restart the gateway to apply."
-# This is unnecessary for CLI commands like `setup` below, but harmless if you do restart.
-```
 
-```bash
-# A2. If npm package is unavailable, use source-link instead
-mkdir -p ~/.openclaw/plugins-src
-if [ ! -d ~/.openclaw/plugins-src/Memoria/.git ]; then
-  git clone https://github.com/matrixorigin/Memoria.git ~/.openclaw/plugins-src/Memoria
-else
-  git -C ~/.openclaw/plugins-src/Memoria pull --ff-only
-fi
-openclaw plugins install --link ~/.openclaw/plugins-src/Memoria/plugins/openclaw
-openclaw plugins enable memory-memoria
-```
-
-```bash
-# B. Setup Memoria Cloud
+# 2. Setup cloud backend (also enables the plugin)
 openclaw memoria setup \
   --mode cloud \
   --api-url <MEMORIA_API_URL> \
-  --api-key <MEMORIA_API_KEY> \
-  --install-memoria
-```
+  --api-key <MEMORIA_API_KEY>
 
-Success standard:
-
-```bash
+# 3. Verify
 openclaw memoria health
-# must include: "status": "ok"
+# Expected: "status": "ok"
 ```
 
-#### Agent Prompt (Cloud)
+If the npm package is not yet published, install from source:
 
-```text
-Install Memoria plugin for my OpenClaw in cloud mode.
-Use:
-- apiUrl: <MEMORIA_API_URL>
-- apiKey: <MEMORIA_API_KEY>
-
-Execute exactly:
-1) Ensure memoria CLI exists:
-   command -v memoria >/dev/null || curl -sSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/scripts/install.sh | bash -s -- -y -d ~/.local/bin
-2) Try npm install first:
-   openclaw plugins install @matrixorigin/thememoria
-3) If step 2 fails, fallback:
-   mkdir -p ~/.openclaw/plugins-src
-   if [ ! -d ~/.openclaw/plugins-src/Memoria/.git ]; then git clone https://github.com/matrixorigin/Memoria.git ~/.openclaw/plugins-src/Memoria; else git -C ~/.openclaw/plugins-src/Memoria pull --ff-only; fi
-   openclaw plugins install --link ~/.openclaw/plugins-src/Memoria/plugins/openclaw
-4) Enable plugin:
-   openclaw plugins enable memory-memoria
-5) Setup cloud:
-   openclaw memoria setup --mode cloud --api-url <MEMORIA_API_URL> --api-key <MEMORIA_API_KEY> --install-memoria
-6) Verify:
-   openclaw memoria health
-
-Output requirements:
-- Return all executed commands and raw outputs
-- If failed, classify as network/auth/config and provide exact fix commands
-- Do not hide or summarize errors
+```bash
+mkdir -p ~/.openclaw/plugins-src
+git clone https://github.com/matrixorigin/Memoria.git ~/.openclaw/plugins-src/Memoria
+openclaw plugins install --link ~/.openclaw/plugins-src/Memoria/plugins/openclaw
 ```
 
-### 2) Local (Embedded)
+Then continue with step 2 above.
 
-Use local mode when you explicitly want self-hosted storage/runtime.
+### Local Setup (Embedded)
 
-#### Developer Flow
+Local mode runs the Rust `memoria` binary against a self-hosted MatrixOne instance.
 
 ```bash
-# A. Install memoria CLI (if missing)
+# 1. Install memoria CLI
 curl -sSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/scripts/install.sh | bash -s -- -y -d ~/.local/bin
 
-# B1. Install + enable plugin from npm
+# 2. Install plugin
 openclaw plugins install @matrixorigin/thememoria
-openclaw plugins enable memory-memoria
-```
-
-```bash
-# B2. If npm package is unavailable, use source-link instead
-mkdir -p ~/.openclaw/plugins-src
-if [ ! -d ~/.openclaw/plugins-src/Memoria/.git ]; then
-  git clone https://github.com/matrixorigin/Memoria.git ~/.openclaw/plugins-src/Memoria
-else
-  git -C ~/.openclaw/plugins-src/Memoria pull --ff-only
-fi
-openclaw plugins install --link ~/.openclaw/plugins-src/Memoria/plugins/openclaw
-openclaw plugins enable memory-memoria
-```
 
-```bash
-# C0. Local quick start (use plugin defaults for db/provider/model)
+# 3. Setup local backend (also enables the plugin, quick start with defaults)
 openclaw memoria setup \
   --mode local \
   --install-memoria \
   --embedding-api-key <EMBEDDING_API_KEY>
+
+# 4. Verify
+openclaw memoria health
+# Expected: "status": "ok"
 ```
 
+For advanced local configuration:
+
 ```bash
-# C. Setup local backend (advanced/custom values)
 openclaw memoria setup \
   --mode local \
   --db-url <MATRIXONE_DSN> \
@@ -172,197 +97,118 @@ openclaw memoria setup \
   --memoria-bin ~/.local/bin/memoria
 ```
 
-Success standard:
-
-```bash
-openclaw memoria health
-# must include: "status": "ok"
-```
+## Agent Install Prompt
 
-#### Agent Prompt (Local)
+Use this prompt to have an OpenClaw agent install the plugin automatically.
+Replace `<MEMORIA_API_URL>` and `<MEMORIA_API_KEY>` with your credentials.
 
 ```text
-Install Memoria plugin for my OpenClaw in local mode.
-Use:
-- dbUrl: <MATRIXONE_DSN>
-- embeddingProvider: <provider>
-- embeddingModel: <model>
-- embeddingApiKey: <embedding_key>
-- embeddingDim: <dim>
-
-Execute exactly:
-1) Ensure memoria CLI exists (install if missing):
-   curl -sSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/scripts/install.sh | bash -s -- -y -d ~/.local/bin
-2) Try npm install first:
-   openclaw plugins install @matrixorigin/thememoria
-3) If step 2 fails, fallback:
-   mkdir -p ~/.openclaw/plugins-src
-   if [ ! -d ~/.openclaw/plugins-src/Memoria/.git ]; then git clone https://github.com/matrixorigin/Memoria.git ~/.openclaw/plugins-src/Memoria; else git -C ~/.openclaw/plugins-src/Memoria pull --ff-only; fi
-   openclaw plugins install --link ~/.openclaw/plugins-src/Memoria/plugins/openclaw
-4) Enable plugin:
-   openclaw plugins enable memory-memoria
-5) Setup local (quick start):
-   openclaw memoria setup --mode local --install-memoria --embedding-api-key <EMBEDDING_API_KEY>
-   If custom MatrixOne/provider/model is required, append:
-   --db-url <MATRIXONE_DSN> --embedding-provider <provider> --embedding-model <model> --embedding-dim <dim>
-6) Verify:
-   openclaw memoria health
-
-Output requirements:
-- Return all executed commands and raw outputs
-- If failed, report the missing dependency/permission/config exactly
-- Do not hide or summarize errors
-```
-
-## Local Installer Inputs (Optional)
-
-Use this section when you choose `openclaw memoria install` for local bootstrap/repair.
+Install the Memoria memory plugin for my OpenClaw in cloud mode.
 
-> **Cloud users:** skip all embedding and LLM environment variables below. These are only used in local/embedded mode. Cloud mode only needs `--api-url` and `--api-key` via `openclaw memoria setup`.
+Credentials:
+- API URL: <MEMORIA_API_URL>
+- API Key: <MEMORIA_API_KEY>
 
-Important environment variables (local/embedded mode only):
+Run these steps in order. Stop and report if any step fails.
 
-- `MEMORIA_DB_URL`: embedded MatrixOne DSN. Default: `mysql://root:111@127.0.0.1:6001/memoria`
-- `MEMORIA_EMBEDDING_PROVIDER`: usually `openai`; `local` only works if your `memoria` binary was built with the `local-embedding` feature
-- `MEMORIA_EMBEDDING_MODEL`: for example `text-embedding-3-small` or `BAAI/bge-m3`
-- `MEMORIA_EMBEDDING_API_KEY`: required for local/embedded mode unless embedding provider is `local`. Not needed for cloud mode.
-- `MEMORIA_EMBEDDING_BASE_URL`: optional for official OpenAI, required for compatible gateways
-- `MEMORIA_EMBEDDING_DIM`: must match the embedding model before first startup
-- `MEMORIA_LLM_API_KEY`, `MEMORIA_LLM_BASE_URL`, `MEMORIA_LLM_MODEL`: optional, only needed for `autoObserve` and internal LLM-backed Memoria tools
-- `MEMORIA_EXECUTABLE`: optional explicit path to an existing `memoria` binary
-- `MEMORIA_RELEASE_TAG`: Rust Memoria release tag to install. Default: installer-defined release tag
-
-Installer flags:
-
-- `--openclaw-bin <path|command>`: use an explicit `openclaw` executable
-- `--memoria-bin <path|command>`: use an existing `memoria` executable
-- `--memoria-version <tag>`: override the Rust Memoria release tag
-- `--memoria-install-dir <path>`: where to install `memoria` if it is missing
-- `--binary-only`: install/validate `memoria` binary only, skip plugin config rewrite
-- `--skip-memoria-install`: require an existing `memoria` executable
-- `--skip-plugin-install`: only rewrite plugin config; assume OpenClaw already installed and the plugin already loaded
-- `--verify`: run a post-install smoke check
-
-## ⚠️ Common Pitfalls
+1) Install plugin:
+   openclaw plugins install @matrixorigin/thememoria
 
-**macOS `sh` vs `bash`:** The installer script is bash (`#!/usr/bin/env bash`) and uses bash-specific syntax.
-If you pipe a script, use `bash -s --`, not `sh -s --`.
+2) Setup cloud backend (this also enables the plugin):
+   openclaw memoria setup --mode cloud --api-url <MEMORIA_API_URL> --api-key <MEMORIA_API_KEY>
 
-```bash
-# ✅ Correct
-curl -fsSL <url> | bash -s --
+3) Verify:
+   openclaw memoria health
+   Expected: "status": "ok"
 
-# ❌ May fail with "bad substitution"
-curl -fsSL <url> | sh -s --
+Rules:
+- Show every command you run and its full raw output
+- Do not summarize or hide errors
+- If a step fails, classify the error (network / auth / config / missing-binary) and suggest the exact fix command
+- Do NOT use `openclaw memory` commands — those are built-in file memory, not Memoria
 ```
 
-**Explicit memory mode is default (`autoObserve=false`):** the plugin does not auto-write memories from conversation turns.
-Writes happen when the agent explicitly calls tools like `memory_store` (or related write tools).
-This keeps memory writes intentional and reviewable.
-If you want auto-capture, set `MEMORIA_AUTO_OBSERVE=true` and provide `MEMORIA_LLM_API_KEY` + `MEMORIA_LLM_MODEL`.
+## Environment Variables (Local/Embedded Only)
 
-**Old schema vs new runtime:** If you upgraded from an older Memoria setup, existing DB schema may not match current Rust runtime expectations.
-Use a fresh database name in `MEMORIA_DB_URL` for a clean install path.
+> Cloud users: skip this section. Cloud mode only needs `--api-url` and `--api-key`.
 
-```text
-# Old/default style
-mysql://root:111@127.0.0.1:6001/memoria
-
-# Clean-start recommendation
-mysql://root:111@127.0.0.1:6001/memoria_v2
-```
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MEMORIA_DB_URL` | MatrixOne DSN | `mysql://root:111@127.0.0.1:6001/memoria` |
+| `MEMORIA_EMBEDDING_PROVIDER` | Embedding service | `openai` |
+| `MEMORIA_EMBEDDING_MODEL` | Model name | `text-embedding-3-small` |
+| `MEMORIA_EMBEDDING_API_KEY` | Required unless provider is `local` | — |
+| `MEMORIA_EMBEDDING_BASE_URL` | Optional for OpenAI, required for gateways | — |
+| `MEMORIA_EMBEDDING_DIM` | Must match model before first startup | — |
+| `MEMORIA_LLM_API_KEY` | Optional, for `autoObserve` and LLM-backed tools | — |
+| `MEMORIA_LLM_BASE_URL` | Optional OpenAI-compatible base URL | — |
+| `MEMORIA_LLM_MODEL` | Model for auto-observe and reflection | `gpt-4o-mini` |
+| `MEMORIA_EXECUTABLE` | Explicit path to `memoria` binary | — |
+| `MEMORIA_RELEASE_TAG` | Rust Memoria release tag to install | installer default |
 
 ## Tool Surface
 
-The OpenClaw plugin exposes:
+The plugin exposes these tools to OpenClaw:
 
 - `memory_search`, `memory_get`, `memory_store`, `memory_retrieve`, `memory_recall`
 - `memory_list`, `memory_stats`, `memory_profile`, `memory_correct`, `memory_purge`, `memory_forget`, `memory_health`
 - `memory_observe`, `memory_governance`, `memory_consolidate`, `memory_reflect`, `memory_extract_entities`, `memory_link_entities`, `memory_rebuild_index`, `memory_capabilities`
 - `memory_snapshot`, `memory_snapshots`, `memory_rollback`
 - `memory_branch`, `memory_branches`, `memory_checkout`, `memory_branch_delete`, `memory_merge`, `memory_diff`
-- compatibility CLI aliases under `openclaw ltm ...`
+- Compatibility CLI aliases under `openclaw ltm ...`
 
-## Compatibility Notes
+## Common Pitfalls
 
-This plugin now follows the Rust Memoria behavior, not the old embedded Python bridge.
+**`openclaw memoria` vs `openclaw memory`:** This plugin uses `openclaw memoria`. The `openclaw memory` namespace is OpenClaw's built-in file memory — a different system entirely.
 
-Current differences to be aware of:
+**macOS `sh` vs `bash`:** The installer script uses bash syntax. If piping, use `bash -s --`, not `sh -s --`.
 
-- `memory_get` is resolved from recent tool results plus a bounded scan, because the Rust MCP toolset does not expose a direct get-by-id call
-- `memory_stats` is derived from available MCP outputs, so inactive-memory totals and entity totals are not currently available
-- `memory_entities` is no longer exposed, because the Rust Memoria MCP toolset does not provide a matching tool
-- old `mysql+pymysql://...` DSNs are normalized to `mysql://...` automatically during install and config parsing
-- if you previously used an older Memoria stack, schema drift can cause runtime errors; using a fresh DB name (for example `memoria_v2`) avoids most upgrade collisions
+**Explicit memory mode is default (`autoObserve=false`):** The plugin does not auto-write memories from conversation turns. Writes happen when the agent explicitly calls tools like `memory_store`. To enable auto-capture, set `MEMORIA_AUTO_OBSERVE=true` and provide `MEMORIA_LLM_API_KEY` + `MEMORIA_LLM_MODEL`.
 
-## Uninstall
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/plugins/openclaw/scripts/uninstall-openclaw-memoria.sh | \
-  bash -s --
-```
-
-That removes the plugin entry, tool policy additions, managed skills, and the default managed checkout path.
+**Old schema vs new runtime:** If upgrading from an older Memoria setup, use a fresh database name in `MEMORIA_DB_URL` to avoid schema drift.
 
 ## Verification
 
-### Success Criteria
-
 | Level | Check | Command | Pass |
 |---|---|---|---|
-| 1. Plugin loaded | OpenClaw recognizes plugin | `openclaw plugins list` | `memory-memoria` is listed and enabled |
-| 2. Backend reachable | Memoria can reach configured backend | `openclaw memoria health` | returns `status: ok` |
-| 3. Memory persisted | Store -> retrieve round-trip works | `openclaw memoria stats` + `openclaw ltm list --limit 10` | non-zero memory appears after a write |
+| 1. Plugin loaded | OpenClaw recognizes plugin | `openclaw plugins list` | `thememoria` listed and enabled |
+| 2. Backend reachable | Memoria connectivity | `openclaw memoria health` | `status: ok` |
+| 3. Memory persisted | Store → retrieve round-trip | `openclaw memoria stats` | Non-zero memory count after a write |
 
-Before the smoke check, confirm the CLIs you are about to use are the ones you expect:
+Additional diagnostics:
 
 ```bash
-openclaw --version
-openclaw memoria verify
-```
-
-After install:
-
-```bash
-openclaw memoria capabilities
-openclaw memoria stats
-openclaw ltm list --limit 10
+openclaw memoria capabilities   # config/plugin check (no live backend needed)
+openclaw memoria verify          # deeper diagnostic
+openclaw ltm list --limit 10     # list recent memories
 ```
 
 Notes:
+- `openclaw memoria setup` is the recommended onboarding command
+- `openclaw memoria connect` remains available as the lower-level config-only variant (no `--install-memoria` support)
+- `setup`/`connect` will merge `thememoria` into `plugins.allow` to satisfy OpenClaw allow-list policy
+- OpenClaw may print "Restart the gateway" after `plugins install` — this is unnecessary for CLI commands like `setup` and `health`
 
-- `openclaw memoria capabilities` is a config/plugin check and does not require a live Memoria backend
-- `openclaw memoria stats` and `openclaw ltm list` require the configured backend to be reachable; in embedded mode that means MatrixOne must be up and the embedding config must be valid
-- OpenClaw reserves `openclaw memory` for its built-in file memory, so this plugin uses `openclaw memoria` and the compatibility alias `openclaw ltm`
-- `openclaw memoria setup` is the recommended onboarding command for cloud/local setup
-- `openclaw memoria connect` remains available as the lower-level config-only entrypoint (no `--install-memoria` support)
-- `setup/connect` will merge `memory-memoria` into `plugins.allow` to satisfy OpenClaw allow-list policy
-- on fresh install without explicit backend config, `openclaw plugins enable` logs a one-time hint with cloud (recommended), local (optional), and `openclaw memoria setup --help`
-- OpenClaw may print "Restart the gateway" after `plugins install` or `plugins enable` — this is unnecessary for CLI commands like `setup` and `health`, but harmless if you do restart
-- `openclaw memoria install` is optional local bootstrap/repair (runtime + config rewrite)
-- `openclaw memoria verify` is an optional deeper diagnostic; `openclaw memoria health` is the primary quick connectivity check
-
-If `openclaw memoria setup` (or `connect`) is missing:
+## Uninstall
 
 ```bash
-openclaw plugins update memory-memoria
-openclaw plugins enable memory-memoria
-openclaw memoria --help
+curl -fsSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/plugins/openclaw/scripts/uninstall-openclaw-memoria.sh | \
+  bash -s --
 ```
 
-Low-level fallback:
+Removes the plugin entry, tool policy additions, managed skills, and the default managed checkout path.
 
-```bash
-node scripts/verify_plugin_install.mjs \
-  --openclaw-bin "$(which openclaw)" \
-  --memoria-bin "$(which memoria)"
-```
+## Compatibility Notes
 
-## Development
+- `memory_get` is resolved from recent tool results plus a bounded scan (Rust MCP has no direct get-by-id)
+- `memory_stats` is derived from available MCP outputs (inactive-memory and entity totals not currently available)
+- `memory_entities` is not exposed (no matching Rust MCP tool)
+- Old `mysql+pymysql://...` DSNs are normalized to `mysql://...` automatically
+- Schema drift from older Memoria stacks can cause runtime errors — use a fresh DB name to avoid
 
-What changed in this repo:
+## Development
 
-- `openclaw/client.ts` now talks to Rust Memoria over MCP stdio
-- the plugin manifest and config surface now use `memoriaExecutable`
-- the installer/uninstaller are pure shell + Node, with no Python dependency
-- the package no longer publishes the old bundled Python runtime
+- `openclaw/client.ts` talks to Rust Memoria over MCP stdio (embedded) or HTTP (api)
+- Plugin manifest and config use `memoriaExecutable` for embedded mode
+- Installer/uninstaller are pure shell + Node, no Python dependency
+- No bundled Python runtime

package/openclaw/__tests__/client.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Group 5: Session & Backend Routing
+ * "Does the right transport get used?"
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { MemoriaClient } from "../client.js";
+import { MemoriaHttpTransport } from "../http-client.js";
+import { buildApiConfig, buildEmbeddedConfig, mockFetch } from "./helpers.js";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe("Group 5: Session & Backend Routing", () => {
+  it("5.1 getSession with backend=api returns MemoriaHttpTransport", async () => {
+    const fetchMock = mockFetch();
+    fetchMock.respondWith(200, { results: [] });
+    const client = new MemoriaClient(buildApiConfig());
+    // Trigger a call to force session creation
+    await client.retrieve({ userId: "u1", query: "test", topK: 5 });
+    // Verify it used fetch (HTTP transport), not spawn (MCP session)
+    expect(fetchMock.calls.length).toBeGreaterThan(0);
+    expect(fetchMock.lastCall()!.url).toContain("/v1/memories/retrieve");
+    client.close();
+  });
+
+  // 5.2 is hard to test without spawning a real binary — skip for unit tests
+
+  it("5.3 same userId reuses session (no extra fetch for session setup)", async () => {
+    const fetchMock = mockFetch();
+    fetchMock.respondWith(200, { results: [] });
+    const client = new MemoriaClient(buildApiConfig());
+    await client.retrieve({ userId: "u1", query: "q1", topK: 5 });
+    const callCount1 = fetchMock.calls.length;
+    await client.retrieve({ userId: "u1", query: "q2", topK: 5 });
+    const callCount2 = fetchMock.calls.length;
+    // Second call should add exactly 1 more fetch (the retrieve), not 2 (no session setup)
+    expect(callCount2 - callCount1).toBe(1);
+    client.close();
+  });
+
+  it("5.4 rebuildIndex in api mode returns cloud-managed message", async () => {
+    const fetchMock = mockFetch();
+    const client = new MemoriaClient(buildApiConfig());
+    const result = await client.rebuildIndex("mem_memories");
+    expect(result.message).toMatch(/cloud/i);
+    // No HTTP call should have been made
+    expect(fetchMock.calls.length).toBe(0);
+    client.close();
+  });
+
+  it("5.5 health in api mode calls healthCheck on transport", async () => {
+    const fetchMock = mockFetch();
+    fetchMock.respondWith(200, { status: "ok", instance_id: "i-1", db: true });
+    const client = new MemoriaClient(buildApiConfig());
+    const result = await client.health("u1");
+    expect(result.status).toBe("ok");
+    expect(result.mode).toBe("api");
+    expect(fetchMock.lastCall()!.url).toContain("/health/instance");
+    client.close();
+  });
+
+  it("5.6 close() does not throw", () => {
+    const client = new MemoriaClient(buildApiConfig());
+    expect(() => client.close()).not.toThrow();
+  });
+});