# v8.10 FAISS Conversation Index Backend Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Add a production-safe FAISS backend option for conversation semantic recall so Engram can run transcript-chunk retrieval independent of QMD.

**Architecture:** Keep existing QMD conversation-index path as default. Add `faiss` backend as an optional adapter with strict fail-open behavior, bounded index refresh cadence, and compatibility with current recall query-policy guards. Implement as a sidecar-style process boundary to avoid embedding heavy Python/FAISS dependencies directly into the Node plugin runtime.

**Tech Stack:** TypeScript plugin adapter layer, Python FAISS sidecar script, transcript chunk pipeline in `src/conversation-index/*`, existing orchestrator recall path, node:test.

---

## Task 1: Define FAISS backend config and contracts

**Files:**
- Modify: `src/types.ts`
- Modify: `src/config.ts`
- Modify: `openclaw.plugin.json`
- Test: `tests/config-conversation-index-faiss.test.ts`
- Docs: `docs/config-reference.md`, `docs/context-retention.md`

**Steps:**
1. Add explicit FAISS config fields (binary/script path, model id, index dir, timeouts, max batch sizes).
2. Keep `conversationIndexBackend` default as `qmd`.
3. Add strict parsing/clamping and zero-safe semantics.
4. Add config tests for defaults and malformed inputs.

## Task 2: Build FAISS adapter interface + fail-open behavior

**Files:**
- Create: `src/conversation-index/faiss-adapter.ts`
- Modify: `src/conversation-index/indexer.ts`
- Modify: `src/conversation-index/search.ts`
- Test: `tests/conversation-index-faiss-adapter.test.ts`

**Steps:**
1. Define adapter API for `upsertChunks`, `searchChunks`, `health`.
2. Implement subprocess wrapper with timeout and stderr capture.
3. Enforce fail-open fallback to no conversation recall on adapter errors (no throw into hook path).
4. Add tests for success, timeout, non-zero exit, malformed payload.

## Task 3: Implement Python sidecar CLI

**Files:**
- Create: `scripts/faiss_index.py`
- Create: `scripts/faiss_requirements.txt`
- Create: `scripts/faiss/README.md`
- Test: `tests/conversation-index-faiss-smoke.test.ts` (skip when deps unavailable)

**Steps:**
1. Implement commands: `upsert`, `search`, `health`.
2. Store index + metadata in plugin-managed path under `memoryDir/state/conversation-index/faiss/`.
3. Keep deterministic JSON I/O contract with adapter.
4. Add smoke test harness and explicit skip behavior.

## Task 4: Wire FAISS backend into orchestrator flow

**Files:**
- Modify: `src/orchestrator.ts`
- Modify: `src/recall-query-policy.ts`
- Test: `tests/conversation-index-integration.test.ts`
- Test: `tests/cron-recall-hardening.test.ts` (if needed for backend parity)

**Steps:**
1. Instantiate backend based on `conversationIndexBackend`.
2. Mirror existing query normalization and cron safety policy for FAISS path.
3. Ensure conversation recall section formatting remains identical across backends.
4. Add integration tests for backend switching and fallback behavior.

## Task 5: Add operational tooling and docs

**Files:**
- Modify: `src/cli.ts`
- Docs: `docs/operations.md`, `docs/setup-config-tuning.md`, `CHANGELOG.md`
- Test: `tests/cli-conversation-index-health.test.ts`

**Steps:**
1. Add `openclaw engram conversation-index-health` command showing backend, index stats, and last update.
2. Document setup, dependency installation, and rollback to QMD backend.
3. Add rollout guidance: shadow mode first, then targeted enablement.

## Task 6: Verification and rollout gate

**Steps:**
1. Run:
   - `npm run check-types`
   - `npm test`
   - `npm run preflight:quick`
2. Validate parity checks:
   - disabled path unchanged
   - QMD backend unchanged when selected
   - FAISS backend fails open cleanly
3. Run soak test with synthetic transcript volume and confirm P95 recall latency budget.

