fix(docs,cli): audit batch 9 — extract_every help text + 12 README count drifts (#152)

pszymkowiak · patrick · claude · web-flow · commit 834ddd3197c7 · 2026-04-30T11:25:37.000+02:00
Two quick wins from the audit punch-list. ## CLI: extract_every help text was three different numbers Audit M3/M6 caught that the `--every` flag on `icm hook post`: - declared `default_value = "15"` in clap (the sentinel for "use config default") - had help text reading "default from config, fallback: 10" - the actual code default in `ExtractionConfig` was 3 Three numbers, none of them telling the truth. Replaced the sentinel with a proper `Option<usize>` and updated the help string to document the real default (3). Behaviour is unchanged: an absent flag falls back to `cfg.extraction.extract_every` (which, in turn, defaults to 3 in the Rust source). Also added `extract_every = 3` and `store_raw = true` to `config/default.toml` so the file is no longer silent on these knobs. ## Docs: 12 translated READMEs all stale at "MCP Tools (22)" The English README has been at 31 since PR #142. All 12 translated READMEs (`README_{ar,de,es,fr,it,ja,ko,nl,pl,pt,ru,zh}.md`) still showed 22 in their MCP-tools section heading. Mechanical bump to 31 in each, preserving the language-specific count notation: ar: (22 أداة) → (31 أداة) de: (22) → (31) es: (22) → (31) fr: (22) → (31) it: (22) → (31) ja: （22個） → （31個） ko: (22개) → (31개) nl: (22) → (31) pl: (22) → (31) pt: (22) → (31) ru: (22) → (31) zh: （22 个） → （31 个） What is NOT in this PR (still in B4b backlog): - The 4 missing tools rows (`icm_memory_forget_topic`, `icm_memory_extract_patterns`, `icm_wake_up`, `icm_learn`) are English-only in the EN README. Adding them to the translations needs native-speaker review — not a mechanical edit. - The "Dashboard" section is still missing from all 12 translations. Same reason: needs translation, not just transliteration. ## Test plan - 324 tests passing (no behaviour change) - `cargo clippy --workspace -- -D warnings` clean - `cargo fmt --all -- --check` clean Co-authored-by: patrick <patrick@rtk-ai.app> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/README_ar.md b/README_ar.md
@@ -201,7 +201,7 @@ icm memoir export -m "system-architecture" -f json     # JSON منظم مع جم
 icm memoir export -m "system-architecture" -f dot | dot -Tsvg > graph.svg
 ```
 
-## أدوات MCP (22 أداة)
+## أدوات MCP (31 أداة)
 
 ### أدوات الذاكرة
 
diff --git a/README_de.md b/README_de.md
@@ -201,7 +201,7 @@ icm memoir export -m "system-architecture" -f json     # Strukturiertes JSON mit
 icm memoir export -m "system-architecture" -f dot | dot -Tsvg > graph.svg
 ```
 
-## MCP-Tools (22)
+## MCP-Tools (31)
 
 ### Gedächtnis-Tools
 
diff --git a/README_es.md b/README_es.md
@@ -201,7 +201,7 @@ icm memoir export -m "system-architecture" -f json     # JSON estructurado con t
 icm memoir export -m "system-architecture" -f dot | dot -Tsvg > graph.svg
 ```
 
-## Herramientas MCP (22)
+## Herramientas MCP (31)
 
 ### Herramientas de Memory
 
diff --git a/README_fr.md b/README_fr.md
@@ -201,7 +201,7 @@ icm memoir export -m "system-architecture" -f json     # JSON structuré avec to
 icm memoir export -m "system-architecture" -f dot | dot -Tsvg > graph.svg
 ```
 
-## Outils MCP (22)
+## Outils MCP (31)
 
 ### Outils Memory
 
diff --git a/README_it.md b/README_it.md
@@ -217,7 +217,7 @@ icm memoir export -m "system-architecture" -f json     # JSON strutturato con tu
 icm memoir export -m "system-architecture" -f dot | dot -Tsvg > graph.svg
 ```
 
-## Tool MCP (22)
+## Tool MCP (31)
 
 ### Tool per le memorie
 
diff --git a/README_ja.md b/README_ja.md
@@ -201,7 +201,7 @@ icm memoir export -m "system-architecture" -f json     # 全メタデータ付
 icm memoir export -m "system-architecture" -f dot | dot -Tsvg > graph.svg
 ```
 
-## MCPツール（22個）
+## MCPツール（31個）
 
 ### メモリツール
 
diff --git a/README_ko.md b/README_ko.md
@@ -201,7 +201,7 @@ icm memoir export -m "system-architecture" -f json     # 모든 메타데이터
 icm memoir export -m "system-architecture" -f dot | dot -Tsvg > graph.svg
 ```
 
-## MCP 도구 (22개)
+## MCP 도구 (31개)
 
 ### 메모리 도구
 
diff --git a/README_nl.md b/README_nl.md
@@ -217,7 +217,7 @@ icm memoir export -m "systeem-architectuur" -f json     # Gestructureerde JSON m
 icm memoir export -m "systeem-architectuur" -f dot | dot -Tsvg > graph.svg
 ```
 
-## MCP-tools (22)
+## MCP-tools (31)
 
 ### Geheugentools
 
diff --git a/README_pl.md b/README_pl.md
@@ -201,7 +201,7 @@ icm memoir export -m "architektura-systemu" -f json     # Strukturalny JSON ze w
 icm memoir export -m "architektura-systemu" -f dot | dot -Tsvg > graph.svg
 ```
 
-## Narzędzia MCP (22)
+## Narzędzia MCP (31)
 
 ### Narzędzia pamięci
 
diff --git a/README_pt.md b/README_pt.md
@@ -217,7 +217,7 @@ icm memoir export -m "system-architecture" -f json     # JSON estruturado com to
 icm memoir export -m "system-architecture" -f dot | dot -Tsvg > graph.svg
 ```
 
-## Ferramentas MCP (22)
+## Ferramentas MCP (31)
 
 ### Ferramentas de memória
 
diff --git a/README_ru.md b/README_ru.md
@@ -201,7 +201,7 @@ icm memoir export -m "system-architecture" -f json     # Структуриро
 icm memoir export -m "system-architecture" -f dot | dot -Tsvg > graph.svg
 ```
 
-## MCP-инструменты (22)
+## MCP-инструменты (31)
 
 ### Инструменты памяти
 
diff --git a/README_zh.md b/README_zh.md
@@ -201,7 +201,7 @@ icm memoir export -m "system-architecture" -f json     # 包含所有元数据
 icm memoir export -m "system-architecture" -f dot | dot -Tsvg > graph.svg
 ```
 
-## MCP 工具（22 个）
+## MCP 工具（31 个）
 
 ### 记忆工具
 
diff --git a/config/default.toml b/config/default.toml
@@ -44,6 +44,17 @@ min_score = 3.0
 # Maximum facts per extraction pass
 max_facts = 10
 
+# Extract every N PostToolUse hook fires (i.e. every N tool calls in a
+# Claude Code / Gemini / Codex / Copilot session). Lower = more
+# aggressive (more memories, more noise); higher = quieter. The
+# `--every` CLI flag on `icm hook post` overrides this.
+extract_every = 3
+
+# Store the raw tool output as a low-importance memory when the
+# rule-based extractor produces no facts. Useful as a coarse safety
+# net; set to `false` if you only want signal-rich extractions.
+store_raw = true
+
 [recall]
 # Layer 2: context injection before sessions
 enabled = true
diff --git a/crates/icm-cli/src/main.rs b/crates/icm-cli/src/main.rs
@@ -434,9 +434,16 @@ enum HookCommands {
     Pre,
     /// PostToolUse hook: auto-extract context every N tool calls
     Post {
-        /// Extract every N tool calls (default from config, fallback: 10)
-        #[arg(long, default_value = "15")]
-        every: usize,
+        /// Override how often to extract (every N tool calls).
+        ///
+        /// When omitted, uses `[extraction] extract_every` from config
+        /// (built-in default: 3). Audit M3/M6 found that the previous
+        /// help text claimed "default 15, fallback 10" while the actual
+        /// config default was 3 — three different numbers across help,
+        /// config example, and code. Made it Option-typed to drop the
+        /// sentinel and document the real default.
+        #[arg(long)]
+        every: Option<usize>,
     },
     /// PreCompact hook: extract memories from transcript before context compression
     Compact,
@@ -1237,11 +1244,8 @@ fn main() -> Result<()> {
         Commands::Hook { command } => match command {
             HookCommands::Pre => cmd_hook_pre(),
             HookCommands::Post { every } => {
-                let extract_every = if every != 15 {
-                    every // CLI flag overrides config
-                } else {
-                    cfg.extraction.extract_every
-                };
+                // CLI flag wins over config; absent flag falls back to config.
+                let extract_every = every.unwrap_or(cfg.extraction.extract_every);
                 #[cfg(feature = "embeddings")]
                 let emb_ref = embedder.as_ref().map(|e| e as &dyn icm_core::Embedder);
                 #[cfg(not(feature = "embeddings"))]
