docs(FN-2094): align memory plugin contract with OpenClaw layout

- Rewrite memory backend contract docs to match shipped MemoryBackend interfaces, capabilities, and registry behavior
- Clarify .fusion/memory/ as the canonical layered workspace and keep .fusion/memory.md compatibility-only
- Document backend resolution through memoryBackendType with qmd as the default and qmd-to-file search fallback behavior
- Synchronize architecture, contributing, and settings reference docs with the updated memory model terminology

docs/architecture.md

@@ -270,14 +270,10 @@ const backend = resolveMemoryBackend(settings);
 
 **Settings integration:**
 - `memoryEnabled`: Toggle controls whether memory instructions are injected into prompts
-- `memoryBackendType`: Select which backend to use (`file`, `readonly`, `qmd`, or custom). Unknown types are accepted and persisted verbatim; the system falls back to `file` at runtime.
+- `memoryBackendType`: Select which backend to use (`file`, `readonly`, `qmd`, or custom). Unknown types are accepted and persisted verbatim; runtime resolution falls back to `DEFAULT_MEMORY_BACKEND` (`qmd`).
 
-**QMD Backend Fallback Behavior:**
-The QMD backend (`qmd`) routes operations through the `qmd` CLI tool. When QMD is unavailable or fails:
-- Exit code 127 (binary not found): Falls back to file backend
-- Command timeout (30s): Falls back to file backend
-- Exit code 1 (general error): Falls back to file backend
-- Other exit codes: Throws error without fallback
+**QMD Backend Behavior:**
+The QMD backend (`qmd`) delegates read/write I/O to the file backend and schedules background QMD index refreshes. For search, it attempts QMD query first and falls back to local `.fusion/memory/` file search when QMD is unavailable, errors, or returns no matches.
 
 **Dashboard API:**
 - `GET /api/memory/backend` — Returns current backend status and capabilities
@@ -484,7 +480,7 @@ SQLite schema is initialized in `packages/core/src/db.ts` and uses:
   - `.fusion/memory/MEMORY.md`
   - `.fusion/memory/YYYY-MM-DD.md`
   - `.fusion/memory/DREAMS.md`
-- Upgrade migration may seed `MEMORY.md` from legacy `.fusion/memory.md` if present.
+- Legacy `.fusion/memory.md` is compatibility-only (migration seed + mirrored alias path) and is not canonical storage.
 
 ### File-based side stores
 Some data remains intentionally filesystem-based:

docs/contributing.md

@@ -109,7 +109,7 @@ When enabled, Fusion uses OpenClaw-style memory files:
 - `.fusion/memory/MEMORY.md` — long-term project memory
 - `.fusion/memory/YYYY-MM-DD.md` — daily running notes
 - `.fusion/memory/DREAMS.md` — dream-processing memory file
-- Legacy `.fusion/memory.md` is only used as a one-time migration seed for upgrades
+- Legacy `.fusion/memory.md` is compatibility-only (migration seed + mirrored alias) and should not be treated as canonical
 
 Use project memory for reusable patterns, constraints, and pitfalls that should persist across tasks.
 
@@ -117,7 +117,7 @@ Use project memory for reusable patterns, constraints, and pitfalls that should
 
 Fusion can automatically extract insights from memory and prune transient content. Enable via `insightExtractionEnabled` setting:
 
-- `.fusion/memory/MEMORY.md` — Working/long-term memory source compacted and pruned by extraction jobs
+- `.fusion/memory/MEMORY.md` — Canonical long-term working memory file (inside the layered `.fusion/memory/` workspace) compacted/pruned by extraction jobs
 - `.fusion/memory-insights.md` — Distilled insights output
 - `.fusion/memory-audit.md` — Audit report after each extraction (includes pruning outcome)
 

docs/settings-reference.md

@@ -390,7 +390,7 @@ Fusion can automatically extract insights from project memory and prune transien
 
 1. **Scheduled Extraction**: When `insightExtractionEnabled` is `true`, a background automation runs on the configured `insightExtractionSchedule` (default: daily at 2 AM).
 
-2. **AI-Powered Analysis**: The automation uses an AI agent to read `.fusion/memory/MEMORY.md` and `.fusion/memory-insights.md`, extract new insights, and produce a pruned working memory candidate.
+2. **AI-Powered Analysis**: The automation uses an AI agent to read canonical long-term memory (`.fusion/memory/MEMORY.md`) from the layered `.fusion/memory/` workspace plus `.fusion/memory-insights.md`, extract new insights, and produce a pruned working memory candidate.
 
 3. **Insight Merging**: New insights are automatically merged into `.fusion/memory-insights.md` under the appropriate category (Patterns, Principles, Conventions, Pitfalls, Context). Duplicates are skipped.