Ruflo memory in the operating flow

.okf/log.md

@@ -2493,3 +2493,18 @@ codex-review line gaining the "user-facing" qualifier to match par.5.
 Method note: the compression is safe ONLY because the verifier enumerated
 rules and returned counts, not an opinion - author self-review missed all
 four losses.
+
+## 2026-08-21 - Ruflo memory wired into the flow; three verified gotchas
+
+Instructions now route memory through ruflo: par.4 step 0 (memory_search
+before deciding - a stored correction outranks fresh reasoning), par.9
+(decisions/corrections ALSO stored via memory_store, prefix conventions),
+CLAUDE.md par-Memory rule, AGENTS.md SOP line. Reviewer caught 6 findings
+pre-commit incl. a measurably false claim (hybrid search is NOT empty - it
+degrades to its keyword leg) and a prefix-token split. Backfill: 541
+knowledge rows re-embedded via CLI store (0 failures); coordination-state
+rows deliberately left unembedded. Verified gotchas stored in memory key
+jt-gotcha-cli-semantic-search-broken: CLI semantic empty without ruvector;
+global HNSW misses CLI-written vectors until server restart (scoped search
+finds them); sql.js whole-image flushes resurrect external SQL deletes -
+mutate only via MCP/CLI, never raw SQL while the server runs.

AGENTS.md

@@ -7,6 +7,8 @@ Session start: always read `@docs/workflows/BASE_HANDBOOK.md` and `@docs/workflo
 
 **Four eyes on every stage, author != verifier (SOP for ALL agents):** the point is agents collaborating to find the TRUTH — a single agent cannot find its own blind spot, because it checks the thing it MEANT to build. Every change is **written by one sub-agent and verified by a different one**; the author never produces the evidence for its own claim. The review lands before the artifact leaves the workshop: a plan is peer-reviewed BEFORE the user is asked, a diff BEFORE commit, a finding is reproduced before it is reported, a measurement re-derived before it is quoted. Brief reviewers with the goal and the artifact, never your conclusions; ask for measurements, not verdicts. Routing: internal sub-agents for every per-stage review, `/codex:review` ONCE at the final verify before merge for USER-FACING changes (it is slow — never in the inner loop); docs-only and instruction-layer changes ship on internal review + CI and apply its findings as a follow-up. No reviewer tooling in this runtime? Fall back agent → external → peer session → human, and mark the change UNREVIEWED if none is reachable. Full protocol: `docs/workflows/autonomous-delivery-prompt.md`.
 
+**Session memory (ruflo-first, SOP for ALL agents):** search ruflo memory (`mcp__ruflo__memory_search`, MCP path) before non-obvious decisions; store decisions/corrections via `mcp__ruflo__memory_store` as they land. Details + prefix conventions: `CLAUDE.md` §Memory.
+
 **OKF maintenance (ENFORCED, parallel by default):** durable learnings (canon numbers, root causes, workflow gotchas) go into `.okf/` — dispatch an okf-maintainer in parallel with the main work, not after it; the bundle update rides the same commit as the change. Weekly scheduled maintain pass back-fills misses. See CLAUDE.md OKF section for the full rule.
 
 <skills>

CLAUDE.md

@@ -46,6 +46,8 @@ Operational knowledge lives in `.okf/` (`build/`, `content/`, `design/`, `workfl
 
 **Session start**: read `@docs/workflows/BASE_HANDBOOK.md` + `@docs/workflows/flow-router.md`, run `/okf:okf` consume. Prefer skills over agents unless the workflow requires them.
 
+**Memory — search before deciding, store as you learn (ruflo-first, Paul 2026-08-21)**: at session start and before any non-obvious decision, `mcp__ruflo__memory_search` with a semantic query from the task's actual words — a past 🔧 CORRECTION outranks fresh reasoning. Store cross-session decisions/corrections/state the moment they land via `mcp__ruflo__memory_store` (one fact per entry; 🎯 GOAL / 📋 PLAN / 🔄 RETRO / 💡 LESSON / 🔧 CORRECTION / ⚠️ ANTIPATTERN prefixes; corrections upsert the existing key — never a second copy). This is IN ADDITION to the ENFORCED OKF rule above — `.okf/` owns repo-canonical knowledge, ruflo memory owns what a future session must recall before deciding. Terminal gotcha: CLI `memory search --type semantic` returns empty (needs @ruvector/core) and hybrid degrades to its keyword leg — use `--type keyword` in terminals; real semantic search works only via the MCP tools. Fallback when ruflo is down: memoria / mem0.
+
 **Markdown search (docs/, content/, .okf/) — `qmd` FIRST** (Paul 2026-08-01; collection `jt-site`; `qmd embed` after big doc batches): known terms → `qmd search "..." -c jt-site -n 5`; conceptual → `qmd query` with lex/vec/hyde fields; then `qmd get`/`multi-get` — never answer from snippets. **Code** (templates/CSS/Ruby): claude-context MCP (`Search the codebase at <repo root> for: "[pattern]"`, root via `git rev-parse --show-toplevel`) or grepai/tokensave; DeepWiki `ask_question` on `jetthoughts/jetthoughts.github.io` for repo-level questions; `rg`/`ls` after, for exact names. `knowledge/` is a host-only symlink — never depend on it in container/CI sessions.
 
 **Blog internal links**: qmd first; slug/tag lookups in `docs/blog-post-index.md` (regenerate: `bin/generate-blog-index`; never trust its count if the date stamp is old). Never guess slugs — verify `ls content/blog/<slug>/index.md`.

docs/workflows/autonomous-delivery-prompt.md

@@ -248,9 +248,15 @@ same breath.
 Agent experience is stale by construction. Before any non-obvious technical or
 design decision:
 
+0. **Memory first.** `mcp__ruflo__memory_search` (semantic, MCP path — the
+   CLI's semantic mode is broken, keyword only in terminals) for prior
+   decisions and corrections on the topic. A stored 🔧 CORRECTION outranks
+   fresh reasoning; a stored 🎯-prefixed decision is not re-litigated without
+   new evidence.
 1. **In-tree first.** `qmd` for markdown (`docs/`, `.okf/`, `content/`),
    semantic code search for code, `rg` last. The answer is usually already
-   written down and being argued from memory is the recurring error.
+   written down and arguing from the model's own recollection instead of
+   looking is the recurring error.
 2. **Then the world.** Current docs (`context7`), targeted web research
    (`tavily-*`, `lightpanda` for headless fetch); substantial multi-source
    research goes through the NotebookLM MCP (Paul 2026-08-21). Take the best
@@ -464,7 +470,10 @@ Both directions: what failed *and* what worked.
 
 Write it where it will be read again — the affected `.okf/` concept plus a dated
 `log.md` entry, in the same commit as the change it describes. Not at session
-end; the batch loses the detail that made it useful.
+end; the batch loses the detail that made it useful. Decisions, corrections,
+and cross-session state ALSO go to ruflo memory (`mcp__ruflo__memory_store`,
+one fact per entry, prefix conventions per `CLAUDE.md` §Memory) — that is what
+§4's step 0 searches, so an unstored decision is invisible to the next pass.
 
 Store what a competent successor could not derive: decisions and their reasons,
 corrections, non-obvious failure modes. Not what the code already says.