diff --git a/.okf/log.md b/.okf/log.md index 2f04febd3..997e7bb46 100644 --- a/.okf/log.md +++ b/.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. diff --git a/AGENTS.md b/AGENTS.md index b705c7e8a..29651db95 100644 --- a/AGENTS.md +++ b/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. diff --git a/CLAUDE.md b/CLAUDE.md index 62ebd7fea..37f0d7401 100644 --- a/CLAUDE.md +++ b/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 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//index.md`. diff --git a/docs/workflows/autonomous-delivery-prompt.md b/docs/workflows/autonomous-delivery-prompt.md index b4f8da2f8..7d97ae6d0 100644 --- a/docs/workflows/autonomous-delivery-prompt.md +++ b/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.