codenamev · codenamev · Jul 16, 2026 · Jul 16, 2026
diff --git a/docs/improvements.md b/docs/improvements.md
@@ -1,6 +1,6 @@
 # Improvements to Consider
 
-*Updated: 2026-07-10 (implemented) - Same-session `/improve` shipped all 4 re-study items: #94 (server_tool_use/advisor recognition in ToolExtractor), #92 (valid SessionStart hookSpecificOutput on no-op/error paths), #95 (truncation-aware ingest gate — Distill::TruncationDetector + audit C015), and #93 (error-handling anti-pattern scanner — Audit::ErrorHandlingScanner Prism AST + `rake audit:error_handling` gate, breadth-gated so narrow typed rescues stay clean; `lib/` shipped green with 3 deliberate broad swallows annotated). Each with tests + atomic commits on feature/influencer-restudy-2026-07-09. Full suite green. Earlier 2026-07-09 - Re-checked all 8 cloneable influencer repos, 9 days after the 2026-06-30 baseline. Only 3 moved, all patch/minor: claude-mem v13.9.1→v13.10.2, lossless-claw v0.13.1→v0.13.2, cq v0.2.0→v0.2.1. No motion in claude-supermemory (v0.0.9, 42cc164), episodic-memory (v1.4.2), grepai (v0.35.0), qmd (v2.6.3), kbs (v0.2.1) — all HEADs predate the baseline. Added 4 items (#92–#95), all robustness/correctness rather than new capability. **Headline:** cq's `server_tool_use` recognition exposed a real silent gap in our `ToolExtractor` — `advisor()` tool calls never reached our `tool_calls` table, so they were invisible to `memory.facts_by_tool` (#94, one-line guard fix). Cross-repo pattern this cycle: all three moved repos' motion was dominated by robustness/idempotency hardening, not features. Previously: 2026-06-30 - Re-studied all 8 cloneable influencer repos against their 2026-03-30 baselines (one agent per repo; each influence doc carries a dated re-study note). Added 16 items (#76–#91). **Headline:** claude-mem (v13.9.1) and claude-supermemory both independently moved recall to a per-turn `UserPromptSubmit` decision — strongest cross-repo signal, targets `project_headless_retrieval_gap` (#76). High-value/low-effort wins: per-connection `PRAGMA busy_timeout` fixing the hook-contention gotcha (#77, qmd), version-drift CI spec (#78, episodic-memory), untrusted-data framing in distillation (#79, lossless-claw), 2× original-query RRF boost (#80, qmd), observer output classifier (#81, claude-mem), ingest subagent transcripts (#82, cq). Repos that moved: claude-mem v10.6.3→v13.9.1 (mostly infra we reject), claude-supermemory→v0.0.9, cq→v0.2.0, episodic-memory v1.0.15→v1.4.2 (active again), lossless-claw v0.5.2→v0.13.1, qmd v2.0.1→v2.6.3. No change: grepai (v0.35.0, 1 stray commit → #85), kbs (v0.2.1). Previously: 2026-06-17 - Added #70 (recall-preserving fact precision on real transcripts — live obs-experiment found Layer-1 fact noise from prose/comparisons/English-word collisions; claim-context gating was measured to crater the distillation benchmark Fact F1 0.958→0.64, so the lever is downstream: wire ReferenceMaterialDetector into the ingest path / Layer-2. Observation extraction was tightened in-branch; facts left at baseline). Earlier 2026-06-16 - Added #69 (self-heal the FTS rank index after concurrent ingest — live incident: hook-vs-MCP write contention leaves `ORDER BY rank` malformed while data stays intact, silently degrading recall until a manual `compact`). Earlier 2026-06-16 - Added Mastra Observational Memory study — one High Priority item (#68, episodic observation layer: Observer + Reflector + observation→fact promotion bridge) and one Medium item (compression/cache telemetry + LongMemEval episodic suite). Key insight: ClaudeMemory has no episodic layer; observations ("what happened") complement facts ("what is true"). See `docs/influence/mastra-observational-memory.md`. Previously: 2026-05-23 - Added AI Memory Systems Landscape Analysis (Nakajima/Opus 4.6 Research article, 2026-03-26) — meta-study of 7 benchmarks + ~12 systems. Four High Priority items: graph traversal as third RRF source (#64), temporal-aware retrieval (#65), bi-temporal schema cleanup (#66), LongMemEval integration (#67). One promotion: improvement #57 (provenance-strength ranking) Medium → High, validated as the "soft epistemic separation" pattern. See `docs/influence/ai-memory-systems-2026.md`. Previously: 2026-05-01 - Added Strands Agent SOPs study (article, not repo) — one M-priority item (parameter blocks in skill frontmatter); rest already implemented or deferred. See `docs/influence/strands-agent-sops.md`. Previously: 2026-04-28 (post-0.10.0) - Restructured 1.0 punchlist around milestone versions. **0.11.0 "Trust & Cost"** ships #47 (token budget), #48 (hallucination rate), #51 (claude-memory show), #53 (first-week ROI nudge — moved up from post-1.0), and a 3-scenario prototype of #49 (harm benchmark). **0.12.0 "Release Discipline"** ships #49 full corpus, #50 (CLAUDE.md baseline), #52 (benchmark scoreboard). **1.0.0** lands soak-validated #54/#55/#56 if time + new #59 API stability audit. See `docs/1_0_punchlist.md` for the full plan with calendar targets. Also added 2026-04-28: two ranking-signal gaps surfaced by the Mercury / "Why Karpathy's Second Brain Breaks" article (Zaid, 2026-04-28) — provenance-strength-aware ranking (#57) and reinforcement/decay scoring (#58). Earlier 2026-04-28 updates: opened the 1.0 punchlist track + added cq study. Previously: 2026-03-30 - Re-studied all 7 influencer repos. New recommendations: CLAUDE_CONFIG_DIR support (#26, from episodic-memory), Usage Stats / ROI Tracking (#27, from grepai v0.35.0). New Features to Avoid: AST-Aware Code Chunking (QMD), Custom Instructions via Env Var (lossless-claw v0.5.2), OpenClaw Context Injection (claude-mem v10.6.0). Repos with no changes: kbs (v0.2.1), claude-supermemory (v2.0.1), episodic-memory (v1.0.15). Previously: 14 features implemented through 2026-03-24.*
+*Updated: 2026-07-16 - Added OKF (Open Knowledge Format) study — three High Priority items: OKF export target (#96, `export --format okf` vendor-neutral markdown bundle from the publish layer), corrective re-prompt errors + loss-refusing guards in `store_extraction` (#97, targets Layer-2 extraction loss from #72), and four-gate reference mint test in the SessionStart prompt (#98, targets reference-junk/distiller-hallucination). Key insight: OKF is a treaty, not a tool — adopt it as an export dialect, never as the store of record (no truth maintenance, no queryable provenance). See `docs/influence/okf.md`. Earlier 2026-07-10 (implemented) - Same-session `/improve` shipped all 4 re-study items: #94 (server_tool_use/advisor recognition in ToolExtractor), #92 (valid SessionStart hookSpecificOutput on no-op/error paths), #95 (truncation-aware ingest gate — Distill::TruncationDetector + audit C015), and #93 (error-handling anti-pattern scanner — Audit::ErrorHandlingScanner Prism AST + `rake audit:error_handling` gate, breadth-gated so narrow typed rescues stay clean; `lib/` shipped green with 3 deliberate broad swallows annotated). Each with tests + atomic commits on feature/influencer-restudy-2026-07-09. Full suite green. Earlier 2026-07-09 - Re-checked all 8 cloneable influencer repos, 9 days after the 2026-06-30 baseline. Only 3 moved, all patch/minor: claude-mem v13.9.1→v13.10.2, lossless-claw v0.13.1→v0.13.2, cq v0.2.0→v0.2.1. No motion in claude-supermemory (v0.0.9, 42cc164), episodic-memory (v1.4.2), grepai (v0.35.0), qmd (v2.6.3), kbs (v0.2.1) — all HEADs predate the baseline. Added 4 items (#92–#95), all robustness/correctness rather than new capability. **Headline:** cq's `server_tool_use` recognition exposed a real silent gap in our `ToolExtractor` — `advisor()` tool calls never reached our `tool_calls` table, so they were invisible to `memory.facts_by_tool` (#94, one-line guard fix). Cross-repo pattern this cycle: all three moved repos' motion was dominated by robustness/idempotency hardening, not features. Previously: 2026-06-30 - Re-studied all 8 cloneable influencer repos against their 2026-03-30 baselines (one agent per repo; each influence doc carries a dated re-study note). Added 16 items (#76–#91). **Headline:** claude-mem (v13.9.1) and claude-supermemory both independently moved recall to a per-turn `UserPromptSubmit` decision — strongest cross-repo signal, targets `project_headless_retrieval_gap` (#76). High-value/low-effort wins: per-connection `PRAGMA busy_timeout` fixing the hook-contention gotcha (#77, qmd), version-drift CI spec (#78, episodic-memory), untrusted-data framing in distillation (#79, lossless-claw), 2× original-query RRF boost (#80, qmd), observer output classifier (#81, claude-mem), ingest subagent transcripts (#82, cq). Repos that moved: claude-mem v10.6.3→v13.9.1 (mostly infra we reject), claude-supermemory→v0.0.9, cq→v0.2.0, episodic-memory v1.0.15→v1.4.2 (active again), lossless-claw v0.5.2→v0.13.1, qmd v2.0.1→v2.6.3. No change: grepai (v0.35.0, 1 stray commit → #85), kbs (v0.2.1). Previously: 2026-06-17 - Added #70 (recall-preserving fact precision on real transcripts — live obs-experiment found Layer-1 fact noise from prose/comparisons/English-word collisions; claim-context gating was measured to crater the distillation benchmark Fact F1 0.958→0.64, so the lever is downstream: wire ReferenceMaterialDetector into the ingest path / Layer-2. Observation extraction was tightened in-branch; facts left at baseline). Earlier 2026-06-16 - Added #69 (self-heal the FTS rank index after concurrent ingest — live incident: hook-vs-MCP write contention leaves `ORDER BY rank` malformed while data stays intact, silently degrading recall until a manual `compact`). Earlier 2026-06-16 - Added Mastra Observational Memory study — one High Priority item (#68, episodic observation layer: Observer + Reflector + observation→fact promotion bridge) and one Medium item (compression/cache telemetry + LongMemEval episodic suite). Key insight: ClaudeMemory has no episodic layer; observations ("what happened") complement facts ("what is true"). See `docs/influence/mastra-observational-memory.md`. Previously: 2026-05-23 - Added AI Memory Systems Landscape Analysis (Nakajima/Opus 4.6 Research article, 2026-03-26) — meta-study of 7 benchmarks + ~12 systems. Four High Priority items: graph traversal as third RRF source (#64), temporal-aware retrieval (#65), bi-temporal schema cleanup (#66), LongMemEval integration (#67). One promotion: improvement #57 (provenance-strength ranking) Medium → High, validated as the "soft epistemic separation" pattern. See `docs/influence/ai-memory-systems-2026.md`. Previously: 2026-05-01 - Added Strands Agent SOPs study (article, not repo) — one M-priority item (parameter blocks in skill frontmatter); rest already implemented or deferred. See `docs/influence/strands-agent-sops.md`. Previously: 2026-04-28 (post-0.10.0) - Restructured 1.0 punchlist around milestone versions. **0.11.0 "Trust & Cost"** ships #47 (token budget), #48 (hallucination rate), #51 (claude-memory show), #53 (first-week ROI nudge — moved up from post-1.0), and a 3-scenario prototype of #49 (harm benchmark). **0.12.0 "Release Discipline"** ships #49 full corpus, #50 (CLAUDE.md baseline), #52 (benchmark scoreboard). **1.0.0** lands soak-validated #54/#55/#56 if time + new #59 API stability audit. See `docs/1_0_punchlist.md` for the full plan with calendar targets. Also added 2026-04-28: two ranking-signal gaps surfaced by the Mercury / "Why Karpathy's Second Brain Breaks" article (Zaid, 2026-04-28) — provenance-strength-aware ranking (#57) and reinforcement/decay scoring (#58). Earlier 2026-04-28 updates: opened the 1.0 punchlist track + added cq study. Previously: 2026-03-30 - Re-studied all 7 influencer repos. New recommendations: CLAUDE_CONFIG_DIR support (#26, from episodic-memory), Usage Stats / ROI Tracking (#27, from grepai v0.35.0). New Features to Avoid: AST-Aware Code Chunking (QMD), Custom Instructions via Env Var (lossless-claw v0.5.2), OpenClaw Context Injection (claude-mem v10.6.0). Repos with no changes: kbs (v0.2.1), claude-supermemory (v2.0.1), episodic-memory (v1.0.15). Previously: 14 features implemented through 2026-03-24.*
 *Sources:*
 - *[thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) - Memory compression system (v13.10.2, re-studied 2026-07-09 — minor, mostly infra)*
 - *[obra/episodic-memory](https://github.com/obra/episodic-memory) - Semantic conversation search (v1.4.2, re-checked 2026-07-09 — no motion)*
@@ -11,6 +11,7 @@
 - *[martian-engineering/lossless-claw](https://github.com/martian-engineering/lossless-claw) - DAG-based lossless context management (v0.13.2, re-studied 2026-07-09 — minor patch)*
 - *[technicalpickles/cq](https://github.com/technicalpickles/cq) - Claude Code transcript SQL observability (v0.2.1, re-studied 2026-07-09 — minor)*
 - *[Mastra Observational Memory](https://mastra.ai/blog/observational-memory) - Text-based dual-agent episodic memory (studied 2026-06-16)*
+- *[GoogleCloudPlatform/knowledge-catalog `okf/`](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) - Open Knowledge Format spec + reference agent (v0.1 draft, studied 2026-07-16)*
 
 This document contains only unimplemented improvements. Completed items are removed.
 
@@ -768,6 +769,43 @@ Source: 2026-06-23 observational-layer audit.
 
 ---
 
+## OKF (Open Knowledge Format) Study (2026-07-16)
+
+Source: `docs/influence/okf.md` — study of Google Cloud's OKF (knowledge-catalog repo, `okf/` subdirectory, spec v0.1 draft): a vendor-neutral *specification* for knowledge as markdown files with YAML frontmatter in a directory hierarchy ("bundle"), paired with a proof-of-concept producer (ADK/Gemini BigQuery-enrichment agent) and consumer (self-contained HTML graph viewer).
+
+**Headline finding.** OKF and ClaudeMemory are complementary, not competing: OKF specifies the *interchange surface* and has no engine (no truth maintenance, no queryable provenance, no ranked retrieval); ClaudeMemory is an *engine* whose only interchange surface is one generated monolith. OKF is what our publish layer could speak. Secondary findings: their tool-side guardrails (budgets enforced in the tool, invented URLs structurally unfetchable, ground-truth sections that refuse to shrink) and corrective re-prompt error shape are directly transplantable; their deterministic-pass-then-LLM-augment rule independently converges with our Layer 1/2 split.
+
+### High Priority Recommendations
+
+- [ ] **96. OKF export target — `claude-memory export --format okf`** ⭐
+  - Value: Vendor-neutral, git-reviewable, per-concept export of the memory corpus — one markdown file per fact with frontmatter (`type`, `description`, `tags`, `timestamp`, plus `fact_id`/`status` extension keys), provenance-derived `# Citations`, supersession/conflict cross-links, auto-generated `index.md` progressive disclosure, and a `log.md` from `memory.changes`. Answers the lock-in question ("stop using the gem, keep a plain-markdown bundle") and positions ClaudeMemory as an OKF producer in an interop space Google is seeding.
+  - Evidence: SPEC.md §3–§9 (format core is tiny: `bundle/document.py` 61 lines, `bundle/index.py` 103 lines); our `publish.rb` already renders facts to markdown — this is a second renderer, not new infrastructure.
+  - Effort: Small-Medium (2–3 days incl. conformance specs). Import is out of scope (resolver stays the write path).
+
+- [ ] **97. Corrective re-prompt errors + loss-refusing guards in `memory.store_extraction`** ⭐
+  - Value: Turn handler-border rejections into self-healing loops. OKF's write-tool errors name the invariant, state what to preserve, and say which tool to re-call (`bundle_tools.py:100-108, 114-154`); ours should do the same for ReferenceMaterialDetector reclassifications, observation coercion failures, and unknown predicates — every recovered call matters given Layer-2 dormancy (#72). Second half: refuse net-information-loss updates (e.g. a resubmitted `decision` fact that drops the stored reason clause) — write-time enforcement of what BareConclusionDetector currently only scores. Start the loss guard in warn-mode telemetry to avoid new reject-churn.
+  - Evidence: `okf/src/reference_agent/tools/bundle_tools.py:114-154` (schema/citation shrink guard with re-call instructions).
+  - Effort: Small (1–2 days; mostly message-shape work + guard specs).
+
+- [ ] **98. Four-gate reference mint test in the SessionStart distillation prompt** ⭐
+  - Value: A crisp refusal rubric against reference junk — (1) topic shape: referenceable by a concrete noun; (2) not meta: slug/title blocklist (`overview`, `getting-started`, `tutorial`, `changelog`, `faq`…); (3) citation test: can you write "See the [X reference] for …" where X is concrete; (4) reuse test: ≥2 facts would cite it. Plus "when in doubt, skip — zero references is fine." Prompt-side gate layered over the tool-side ReferenceMaterialDetector mirrors OKF's dual defense, and targets the documented distiller-hallucination/reference-junk pattern.
+  - Evidence: `okf/src/reference_agent/prompts/web_ingestion_instruction.md` (mint gates); GA4 bundle outcome — `references/` holds only metrics/joins, zero meta junk.
+  - Effort: Small (half-day + prompt spot-check).
+
+### Medium Priority (from this study)
+
+- [ ] **`log.md`-style narrative changelog in the published snapshot** — date-grouped, newest-first, bold-verb entries rendered from `memory.changes` (SPEC.md §7 format); bundle with #96's renderer.
+- [ ] **Sorted-pair canonical naming for symmetric relationships** — OKF names join docs `<a>__<b>` alphabetically so one canonical doc exists regardless of discovery direction; defer until a symmetric predicate lands.
+
+### Features to Avoid (from this study)
+
+- **Separate LLM API calls for synthesis** — OKF's `synthesizer.py` calls Gemini per directory and both agent passes are metered API runs; violates the no-extra-API-cost convention. Export index descriptions render deterministically.
+- **Markdown files as the store of record** — OKF has no resolver; adopting it as storage forfeits truth maintenance, provenance queries, and hybrid retrieval. Export dialect only.
+- **Module-global mutable tool context** (`tools/context.py` `_ctx`/`_web` globals) — opposite of our DI-everywhere testing strategy.
+- **CDN-dependent generated artifacts** (viz.html loads Cytoscape.js/marked from CDN) — breaks offline; any exported artifact must vendor its assets.
+
+---
+
 ## Medium Priority
 
 ### ~~18. Shell Completion for CLI~~ ✅ Implemented 2026-03-20