Cross-reference audit

04 — Cross-Reference Audit

Date: 2026-05-11 Auditor: Mac cross-reference auditor (subagent, Opus 4.7 1M) Method: Read all 17 research reports; flagged claims that disagree; ranked by which report cited primary docs vs. inferred from secondary sources. Scope: Contradictions only. Convergent findings collected at the end.

Reports audited:

research/01-github-recon.md
research/02-tool-comparison.md
research/03-memory-frameworks.md
research/04-community-signal.md
research/05-indexing-tech.md
sdk-patterns/01-claude-openai-sdk.md
sdk-patterns/02-multiagent-frameworks.md
sdk-patterns/03-knowledge-management.md
sdk-patterns/04-agent-persona-patterns.md
sdk-patterns/05-ccleaks-claude-internals.md
external-prior-art/github/_summary.md
external-prior-art/blogs/_summary.md
fleet-state/variants.md
fleet-state/recent-activity.md
fleet-state/broken-canon.md
fleet-state/extracted-concepts.md
fleet-state/extracted-facts.md

A “winner” is named where two reports disagree and one cites a more primary source (Anthropic docs > leaked-source extraction > community blog > model recollection).

1. Memory limits & loading

1.1 MEMORY.md size cap — three different numbers

sdk-patterns/01-claude-openai-sdk.md (§1.5): “MEMORY.md is treated as an index — first 200 lines / 25KB load at session start, topic files load on demand.” Cites Anthropic docs (code.claude.com/docs/en/memory).
sdk-patterns/05-ccleaks-claude-internals.md (§1d): “MEMORY.md (auto-memory entrypoint) has a HARD limit: first 200 lines OR 25KB, whichever comes first, loaded at session start. Beyond that is on-demand only.” Confidence: HIGH (official docs).
external-prior-art/blogs/_summary.md post #2 (milvus): “Treat the 200-line MEMORY.md cap as a hard physical limit — anything past line 200 is invisible.” Implies 200 lines is the only cap, no KB ceiling.
external-prior-art/blogs/_summary.md post #14 (youngleaders): “The 200-line MEMORY.md cap means anything in there is competing with actual learnings.” No KB cap mentioned.

Winner: ccleaks (#10) and SDK-patterns (#6) — they cite Anthropic’s own docs and converge on “200 lines OR 25KB, whichever first.” The blog posts elide the byte cap, which is real and can fire even on a sub-200-line file with long markdown. Use “200 lines OR 25KB.”

1.2 CLAUDE.md size target

sdk-patterns/05-ccleaks-claude-internals.md (§1d): “Target: under 200 lines per CLAUDE.md.” Cites official docs.
external-prior-art/blogs/_summary.md post #1 (humanlayer): “Keep CLAUDE.md under 300 lines, ideally far fewer. HumanLayer’s root file is under 60 lines.”
external-prior-art/blogs/_summary.md post #3 (parreo): “Global CLAUDE.md ≈ 50 lines is enough.” Project guidance: “20–80 lines (small repos), 80–200 lines (typical), >200 lines means split into .claude/rules/*.md.”
sdk-patterns/01-claude-openai-sdk.md (§8): “Target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.” Cites Anthropic docs.

Winner: Anthropic’s 200-line target is the canonical number (cited by SDK-patterns and ccleaks from official docs). HumanLayer’s 60 lines and Parreo’s 50 are practitioner advice, not contradictions — they’re tighter targets under the 200-line ceiling. No contradiction; practitioners run tighter than the doc target.

1.3 What survives compaction

sdk-patterns/05-ccleaks-claude-internals.md (§1e): “Project-root CLAUDE.md is RE-READ from disk after /compact and re-injected. Nested subdirectory CLAUDE.md files are NOT re-injected — they reload only when Claude next reads a file in that subdirectory.” Cites Anthropic docs.
fleet-state/extracted-concepts.md (Continuity section, “What survives compaction”): “Root CLAUDE.md imports, latest durable handoff, deep transcript scan artifacts, in-process agent audits (when enabled), vault/D1/config/log files actually persisted.”
external-prior-art/blogs/_summary.md post #5 (adolan-claude-brain): Uses six hooks including PreCompact + PostCompact pair to preserve state across compaction.
external-prior-art/blogs/_summary.md post #14 (youngleaders): “PreToolUse hook with PPID flag file gives per-process, once-per-session injection that survives compaction — critical insight, because session-start hooks don’t fire after in-session compaction.”

Conflict: youngleaders says SessionStart hooks DON’T fire after in-session compaction. ccleaks lists PostCompact (post-compact event) as a real hook (§2a). Both are consistent: SessionStart doesn’t fire post-compact, but PostCompact does. The contradiction is only with naive readings.

Winner: ccleaks (#10) — official hook list shows the real event chain. Use PostCompact hook, not SessionStart, for re-injection after compaction.

1.4 Auto-compact trigger threshold

sdk-patterns/05-ccleaks-claude-internals.md (§11b): “Triggers at ~187K of 200K tokens (~93.5% — not the loosely-stated 80%). 13K-token buffer preserved.” Source-extracted from leaked binary.
external-prior-art/github/_summary.md (#7 shanraisshan): “Context budget heuristics from Thariq/Dex: ‘dumb zone kicks in around ~40% context’; ‘context rot at ~300-400k on 1M model’.”
external-prior-art/blogs/_summary.md post #2 (milvus): Implies a higher figure but not precise.

Winner: ccleaks — the 187K/200K (93.5%) number is from the leaked source itself, not a loosely cited “80%” figure that floats around community discussion. Use 93.5% (~187K) as the auto-compact trigger.

1.5 Dream / consolidation cadence

external-prior-art/blogs/_summary.md post #2 (milvus): “Auto Dream trigger: >24h since last cleanup AND >=5 new sessions.”
sdk-patterns/05-ccleaks-claude-internals.md (§10c): “Defaults: min 24 hours between dreams, min 5 sessions accumulated.”

Convergent. Both numbers match. No contradiction.

1.6 Anthropic Memory tool ops

sdk-patterns/05-ccleaks-claude-internals.md (§10b): Six ops: view, create, str_replace, insert, delete, rename.
research/03-memory-frameworks.md (§2.5): Same six ops: view, create, str_replace, insert, delete, rename.

Convergent.

1.7 Memory types count

sdk-patterns/05-ccleaks-claude-internals.md (§10f): “ccleaks claims four memory types: user, feedback, project, reference.” Confidence: MEDIUM.
external-prior-art/blogs/_summary.md post #2 (milvus): “Auto Memory organizes notes into 4 categories: user_*, feedback_*, project_*, reference_*.”

Convergent. Both say four types with same names.

2. Hook lifecycle

2.1 Hook count — 6, 12-14, 20, 28

external-prior-art/blogs/_summary.md post #5 (adolan): “Use all six Claude Code hooks: session-start, user-prompt-submit, stop, session-end, pre-compact, post-compact.”
sdk-patterns/05-ccleaks-claude-internals.md (§2a): “Full hook event list (28 events as of v2.1.116, April 2026).” Cites official docs + ccleaks cross-check. Lists 28 events explicitly.
sdk-patterns/05-ccleaks-claude-internals.md (§2a) note: “ccleaks lists ‘20 events’ in the audit summary but the official docs have grown to 28.”
sdk-patterns/05-ccleaks-claude-internals.md citations: “claudefa.st/blog/tools/hooks/ hooks-guide — hooks guide with 12-14 events.” (older practitioner guides).

Winner: ccleaks (#10) — directly extracted the current 28-event list from official docs. The other counts are either older or describe a hooks-of-interest subset rather than the full event taxonomy.

Use 28 as the current event count (as of April 2026 / v2.1.116). The six listed by adolan are the commonly used hooks, not the full set.

2.2 Which hook fires on auto-memory extraction

sdk-patterns/05-ccleaks-claude-internals.md (§2f): “extractMemories runs ‘once at the end of each complete query loop (when the model produces a final response with no tool calls) via handleStopHooks’ — confirms Stop hook is the auto-memory trigger point.” Source-quoted.
external-prior-art/blogs/_summary.md post #9 (mindstudio-agentic-os): “Heartbeat — scheduled agents that run proactively, not reactively.” Different concern (scheduled, not hook-triggered).

Convergent on Stop being the auto-memory trigger. Mindstudio’s heartbeat is a separate concept, not contradictory.

2.3 Default hook baseline (Wes’s fleet)

fleet-state/extracted-concepts.md (Default Hook Baseline): SessionStart: load-memory.js
- load-handoff.js. SessionEnd: save-session-summary.js + write-handoff.js. PreCompact: pre-compact.js + write-handoff.js + deep-transcript-scan.js. PreToolUse (Bash|Read): pre-tool-use-secret-intercept.js. PermissionRequest: auto-allow shim. statusLine: statusline-tracker.sh.
CLAUDE.md session-protocol.md (loaded via import): Same baseline.

Convergent — same baseline cited consistently.

2.4 Hook input shape — fields

sdk-patterns/05-ccleaks-claude-internals.md (§2b): Lists session_id, transcript_path, cwd, permission_mode, hook_event_name, effort. Plus subagent: agent_id, agent_type.
external-prior-art/blogs/_summary.md post #14 (youngleaders): “CLAUDE_SESSION_ID does not exist in hooks — use os.getppid(). The PPID is stable within a session and new for each subagent.”

Conflict in field naming: youngleaders says CLAUDE_SESSION_ID env var doesn’t exist; ccleaks lists session_id as JSON input field. These are not contradictory — session_id is in the JSON payload (stdin), not the env. Youngleaders is correcting practitioners who try to read it from the env. Both are right.

No real contradiction. Caveat for the design doc: hook scripts read session_id from stdin JSON, not $CLAUDE_SESSION_ID env var.

2.5 Hook precedence / config sources

sdk-patterns/05-ccleaks-claude-internals.md (§2d): “Managed > Skill/Agent frontmatter > Project local > Project > Plugin > User.”
sdk-patterns/01-claude-openai-sdk.md (§1.2): “Settings precedence: managed > user > project > local.”

Conflict: ccleaks puts project-local ABOVE project; SDK-patterns puts user ABOVE project. Re-reading ccleaks: ccleaks lists project-local at rank 3, project at rank 4. SDK-patterns at §1.2 says “managed > user > project > local” — that ordering is INVERTED for the user/local relationship.

Winner: ccleaks — the “deeper specificity wins” rule of Claude Code is consistent across the leaked source. .claude/settings.local.json (project-local) overrides .claude/settings. json (project). User-level (~/.claude/settings.json) is BELOW project, not above. SDK-patterns section §1.2 has the user/project ordering wrong.

Actually re-reading SDK-patterns §1.2 more carefully: It says “managed > user > project > local” in one place but elsewhere implies user-level is LESS specific than project. There’s internal inconsistency in SDK-patterns. The Anthropic docs and ccleaks both make project > user. Use ccleaks’s ordering: Managed > .claude/settings.local.json > .claude/settings.json > plugin > ~/.claude/settings.json.

2.6 Hook timeout values

sdk-patterns/05-ccleaks-claude-internals.md (§2g): “General tool timeout: 10 minutes. SessionEnd timeout: 1.5 seconds (tight).” Confidence: MEDIUM (ccleaks claim, not in official docs).

No other report disagrees. Use with caveat — this is the only place that names the SessionEnd 1.5s timeout, which is a sharp number worth confirming before relying on it.

2.7 InstructionsLoaded hook

sdk-patterns/05-ccleaks-claude-internals.md (§1h): Documents InstructionsLoaded as an underused observability hook with payload including file_path, memory_type, load_reason. Cites official docs.
All other reports: Don’t mention it.

No contradiction — only one report mentions it, but it’s well-cited.

3. Folder structure recommendations

3.1 PARA vs Active/Reference/Logs/Archive vs role-based src/ vs JD

sdk-patterns/02-multiagent-frameworks.md: “Every production framework converges on roughly the same layout: src/<package>/{agents,tools,workflows,config}. Wes’s Active/Reference/Logs/Archive pattern: NO framework recommends it as a code-organization scheme.” Explicitly rejects Wes’s lifecycle-state layout.
sdk-patterns/03-knowledge-management.md: “Rank-ordered recommendation: 1. Lightly- numbered PARA top level + Johnny.Decimal inside structured zones + LYT-style MOCs in the linking surface + flat atomic notes inside workpads.” Argues PARA-flavored top level works across vault + agent runtime + repo.
external-prior-art/blogs/_summary.md post #9 (mindstudio-agentic-os): 4-layer model: Rules / Context / Skills / Memory.
external-prior-art/blogs/_summary.md post #5 (adolan): scoring + tagging dimensions, no fixed folder taxonomy.

Contradiction: SDK-patterns #7 (multiagent-frameworks) rejects lifecycle-state organization; SDK-patterns #8 (knowledge-management) endorses PARA (a lifecycle-state organization).

Reconciliation: They’re applying different scopes. Multiagent-frameworks is reviewing code organization for agent runtimes (where state-in-folder is bad practice). Knowledge- management is reviewing vault organization (where PARA is well-established). They actually agree that lifecycle state belongs in runtime DB, not in the code tree, but the vault can use lifecycle-state framing because it’s a knowledge surface, not code. No real contradiction once scopes are matched.

3.2 Top-level “use the same skeleton everywhere”

sdk-patterns/02-multiagent-frameworks.md: “Mastra-style agents/ tools/ workflows/ index.ts skeleton replicated per variant.”
sdk-patterns/03-knowledge-management.md: “ONE canonical layout used everywhere with surface-appropriate substitutions. The verbs map even when the nouns change.” Shows the Vault / Agent Runtime / Repo mapping table.

Convergent on the principle of replicating a skeleton across surfaces, though they propose different specific skeletons.

3.3 Where personas live

sdk-patterns/01-claude-openai-sdk.md (§1.1): Subagent persona = .claude/agents/<name>.md with YAML frontmatter + markdown body in one file. Cites Anthropic docs.
sdk-patterns/04-agent-persona-patterns.md (§1.1): Three surfaces — CLAUDE.md, subagent, skill — each with different lifetime + scope.
sdk-patterns/02-multiagent-frameworks.md (CrewAI section): Persona in agents.yaml (YAML key-keyed dict), tools wired in crew.py via @agent decorator.

No contradiction — these are different frameworks with different conventions.

3.4 Subagent file location precedence

sdk-patterns/01-claude-openai-sdk.md (§1.1): “1 (highest) Managed settings; 2 —agents CLI flag; 3 .claude/agents/; 4 ~/.claude/agents/; 5 Plugin’s agents/.”
sdk-patterns/04-agent-persona-patterns.md: “When subagent files exist in both ~/.claude/agents/ (user) and .claude/agents/ (project), project wins.”

Convergent. Same precedence (project > user > plugin).

4. Agent identity layering (SOUL / ETHOS / PERSONA / RUNTIME)

4.1 Number of layers in identity stack

sdk-patterns/04-agent-persona-patterns.md (§3.1): “4 layers: (1) IDENTITY (who am I, voice), (2) ETHOS (shared rules every agent obeys), (3) ROLE (job + capabilities + lane), (4) RUNTIME (model, tools, hooks, working directory).”
fleet-state/extracted-concepts.md (in practice): SOUL (soul.md) → ETHOS (fleet-ethos.md) → PERSONA (variants/.md) → ROLE+RUNTIME (scripts/sessions/.json).
external-prior-art/blogs/_summary.md post #9 (mindstudio): 4-layer: Rules / Context / Skills / Memory.

Conflict at the conceptual level:

agent-persona-patterns names them IDENTITY / ETHOS / ROLE / RUNTIME.
Wes’s fleet practice names them SOUL / ETHOS / PERSONA / ROLE+RUNTIME.
mindstudio names them Rules / Context / Skills / Memory.

Reconciliation: The mindstudio layers don’t map 1:1 with the agent-persona ones — they cover different concerns (mindstudio is operating-system-shaped, agent-persona is identity- shaped). The first two are nearly the same model, just different label preferences.

Use the SOUL / ETHOS / PERSONA / RUNTIME terminology — it matches Wes’s existing fleet docs (~/.claude/docs/soul.md, fleet-ethos.md, variants/<name>.md, scripts/sessions/) and is closer to the agent-persona-patterns canonical model.

4.2 Persona file recommended length

sdk-patterns/04-agent-persona-patterns.md (§3.3): “Length: 30–80 lines. The Nagatha example (38 lines) is the right length.”
external-prior-art/blogs/_summary.md post #1 (humanlayer): Refers to overall CLAUDE.md size <60 lines; doesn’t separately cap persona-files.

Convergent. No real conflict — agent-persona-patterns sets a tighter range for the persona specifically (it’s only one of multiple imports).

4.3 Re-injection cadence for persona drift

sdk-patterns/04-agent-persona-patterns.md (§2.5): “Llama2-chat-70B exhibits measurable persona drift within 8 conversation rounds.” Cites arXiv 2402.10962.
external-prior-art/blogs/_summary.md post #14 (youngleaders): “PreToolUse hook with PPID flag file gives per-process, once-per-session injection.” Doesn’t address mid-session cadence.

No contradiction. The arXiv finding is per-turn; the youngleaders pattern is per-session. Both can coexist (UserPromptSubmit hook every N turns + per-session PreToolUse). Agent- persona-patterns §3.6 recommends adding UserPromptSubmit role-pinning for long-running variants — that’s the explicit mid-session cadence answer.

4.4 Where persona lives

sdk-patterns/04-agent-persona-patterns.md (§3.2): ~/.claude/docs/variants/<name>.md.
fleet-state/variants.md: Per-variant persona files at ~/jarvis/hinesipedia/<Name>/ persona.md (Stark-drafted, 2026-04-30 deltas), with mirror copies in ~/.claude/docs/ variants/<name>.md.
fleet-state/broken-canon.md finding #20: Variant docs missing for half of Active 18 in ~/.claude/docs/variants/.

Conflict in practice: Two locations exist for persona files — vault/<Name>/persona.md (Stark-drafted recent) and ~/.claude/docs/variants/<name>.md (Apr 20 mirror, partial). The recon (fleet-state/variants.md) flags this as a drift surface — some variants have only the vault file, some have only the .claude/docs file, some have both.

Winner: agent-persona-patterns recommends ~/.claude/docs/variants/<name>.md as the canonical single location. The vault <Name>/persona.md is the recent Stark-authored work but the ~/.claude/docs/variants/ location is what gets loaded by the harness’s import cascade. Decision: load from ~/.claude/docs/variants/ per agent-persona-patterns §3.2; sync from vault into that location, but treat the harness-loaded copy as canon.

4.5 What “@import” does to context

sdk-patterns/01-claude-openai-sdk.md (§1.4): “@path/to/file.md syntax. Maximum depth of five hops. Relative paths resolve relative to the file containing the import.”
sdk-patterns/05-ccleaks-claude-internals.md (§1c): Same — “Recursion depth: 5 hops max.”
external-prior-art/blogs/_summary.md post #1 (humanlayer): “Splitting into @path imports helps organization but does not reduce context, since imported files load at launch.”
sdk-patterns/01-claude-openai-sdk.md (Antipattern): “Don’t expect imports to reduce context.”

Convergent. Both say 5-hop max + imports load at launch (don’t save tokens). No contradiction.

5. Storage / indexing tech

5.1 SQLite FTS5 vs DuckDB vs Tantivy vs hybrid

research/05-indexing-tech.md: “SQLite FTS5 + sqlite-vec, both as loadable extensions inside one .sqlite file. Single binary, no daemon.” Phase 2 only if Phase 1 hits a wall: DuckDB for analytics. Tantivy / Qdrant / Weaviate rejected as overkill.
research/03-memory-frameworks.md (§3.1): “SQLite (per-machine indexer) + D1 (fleet- wide read model). No Neo4j, no Postgres. SQLite handles 12 months of transcripts on a laptop.” Embeddings via sqlite-vec. BM25 via SQLite FTS5.
research/01-github-recon.md: Recommends marcelocantos/mnemo (SQLite FTS5) + wesm/ agentsview (Go binary, SQLite, optional Postgres for team dashboards via pg push).
research/02-tool-comparison.md: “Recommendation summary: SQLite with FTS5. Tables: sessions, messages, events (typed), tool_calls, topics, embeddings (optional).”
research/04-community-signal.md: Lists claude-mem (FTS5 + Chroma), claude-session- index (SQLite + FTS5).
external-prior-art/github/_summary.md (thedotmack/claude-mem): SQLite + ChromaDB.
external-prior-art/blogs/_summary.md post #5 (adolan-claude-brain): “Local SQLite with FTS5 keyword + sentence-transformer embeddings + fuzzy — three search modes, no cloud, no API keys.”

Convergent across all reports: SQLite FTS5 is the default. Vector layer is either sqlite-vec (recommended), Chroma (adolan, claude-mem), or none (most viewers).

Disagreements:

research/05-indexing-tech.md recommends sqlite-vec explicitly and rejects ChromaDB (“history of breaking API changes through 2024, mid-tier performance”).
external-prior-art/github/_summary.md notes claude-mem uses ChromaDB but suggests skipping the ChromaDB dep — “FTS5 (already in SQLite) would carry most of the value.”

Winner: sqlite-vec is recommended. ChromaDB is in the wild (claude-mem, claude-brain) but the indexing-tech analysis flags it as unstable. Use sqlite-vec or LanceDB (close alternative), not ChromaDB.

5.2 DuckDB vs SQLite for analytics

research/05-indexing-tech.md: “DuckDB wins the analytics lane outright. Recommendation: keep SQLite as the row store and attach DuckDB for ad-hoc analytics (duckdb> ATTACH 'events.db' AS s (TYPE sqlite);). Best of both worlds, zero ingestion cost.”
All other reports: SQLite-only.

No contradiction — indexing-tech recommends both together, not either/or.

5.3 Two-table vs single-table schema

research/02-tool-comparison.md: “Two-table model: api_messages (canonical replay) + ui_events (rich analytics). From Cline.”
research/03-memory-frameworks.md: Three layers: raw / episodes / chunks-with-vectors. Plus entities and facts (Graphiti-style triplets).
research/05-indexing-tech.md: Single events table with FTS5 + vec0 virtual tables.

Different shapes recommended. Reconciliation:

Indexing-tech (#5) recommends a simpler events-only schema (good for the “what was said and when” use case).
Memory-frameworks (#3) recommends the full episode/entity/fact schema (for drift detection, the actual use case here).
Tool-comparison (#2) borrows Cline’s api_messages + ui_events split for replay vs analytics.

These aren’t really contradictions — they’re different schemas for different use cases. The drift-detection use case argues for memory-frameworks’ richer schema. Indexing-tech’s simpler version would force adding entity/fact extraction as a separate layer later.

5.4 Embedding strategy — embed everything or selective

research/03-memory-frameworks.md (§3.7): “Embed: user prompts, assistant reasoning/decisions, episode summaries, entity summaries. Don’t embed: tool inputs, tool outputs, system reminders, hook output, raw JSON dumps.” Argues poisoning the embedding space hurts retrieval.
research/05-indexing-tech.md: “Encode in batches at ingest, store in events_vec, never re-embed unless the model changes.” Implies embed-all or embed-most.
external-prior-art/blogs/_summary.md post #5 (adolan-claude-brain): Embeds 67k messages across 1,321 sessions.

Conflict: Memory-frameworks (#3) argues for selective embedding (~20% of messages). Indexing-tech (#5) and adolan-claude-brain embed broadly.

Winner: Memory-frameworks (#3) makes the more careful case — tool output is high-volume and low-signal; embedding it dilutes recall. Use selective embedding unless the corpus is small enough that selectivity doesn’t matter.

5.5 Hybrid search — RRF vs reranker vs both

research/05-indexing-tech.md: “Phase 1: BM25 + dense + RRF (k=60). Phase 3 (only if measurement shows you need it): BGE-reranker on top-50.”
research/03-memory-frameworks.md (§3.6): “Fuse with RRF (k=60). Then for >50 candidates or precision-sensitive queries, run a cross-encoder rerank (a small local model or one Sonnet call).”
research/02-tool-comparison.md (cass section): “Two-layer index: Tantivy BM25 with edge n-grams for lexical, optional ONNX MiniLM/Arctic/Nomic embeddings in .fsvi vector files for semantic, combined via Reciprocal Rank Fusion when both are warm.”

Convergent — RRF (k=60) is the default fusion, reranker as opt-in upgrade.

5.6 D1 vs SQLite for fleet-wide read model

research/03-memory-frameworks.md: “SQLite (per-machine indexer) + D1 (fleet-wide read model).”
research/05-indexing-tech.md: Single SQLite file on Cheesegrater, replicated via rsync. Doesn’t mention D1 explicitly.
research/01-github-recon.md: “agentsview pg push from each of the 5 machines into one Postgres on Cheesegrater” — recommends Postgres, not D1.

Conflict in destination: memory-frameworks says D1 (Cloudflare’s distributed SQLite), indexing-tech says local SQLite on Cheesegrater + rsync, github-recon says Postgres on Cheesegrater (via agentsview’s pg push).

Reconciliation:

D1 is good for low-volume, globally-replicated read model (heartbeats, current state).
Local SQLite on Cheesegrater is good for the bulk transcript corpus (10GB+ doesn’t fit D1’s 10GB-per-DB limit anyway).
Postgres is the agentsview-recommended target but adds an ops dep that Wes’s fleet doesn’t currently run.

Pragmatic answer: Local SQLite on Cheesegrater for the corpus; D1 for the fleet-wide live read model (heartbeats, variant status). Postgres only if agentsview is adopted wholesale.

6. Multi-agent coordination patterns

6.1 Coordinator/Worker vs Wave vs Pipeline vs Consensus

external-prior-art/github/_summary.md (sethdford/claude-fleet): “Wave pattern: parallel exploration → sequential design → parallel impl → critic gate → loop.” Plus 7 named roles (Lead/Worker/Scout/Kraken/Oracle/Critic/Architect).
sdk-patterns/05-ccleaks-claude-internals.md (§8e): “Coordinator mode… feature ('COORDINATOR_MODE'). System prompt: ‘You are a coordinator. Your job is to: Direct workers to research, implement and verify code changes.’” Cites leaked source.
external-prior-art/blogs/_summary.md post #12 (gerred): “Decomposition selection: Functional / Spatial / Temporal / Data-driven. Coordination patterns: Pipeline / MapReduce / Consensus / Event-driven.”
external-prior-art/blogs/_summary.md post #13 (shipyard): “Three orchestrators (Agent Teams, Gas Town, Multiclaude) follow the same coordinator+subagents pattern.”

Multiple recommended patterns, no single winner. Reconciliation:

Gerred’s matrix (decomposition × coordination) is the most rigorous taxonomy.
Anthropic’s COORDINATOR_MODE is the upstream pattern.
claude-fleet’s Wave is a specific implementation of Pipeline + Consensus.

No contradiction — these are different levels of abstraction. For the design doc, use gerred’s taxonomy as the framework; cite COORDINATOR_MODE as Anthropic’s upstream answer.

6.2 tmux + claude-squad vs tmux + Agent Teams vs claude-tmux

external-prior-art/github/_summary.md (smtg-ai/claude-squad): Go TUI, tmux session per agent + git worktree per agent.
external-prior-art/github/_summary.md (wshobson/agents, agent-teams plugin): teammateMode: "tmux" + CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 — Anthropic’s official experimental multi-agent display mode.
external-prior-art/github/_summary.md (nielsgroen/claude-tmux): Rust TUI as tmux display-popup with status detection from pane content.
external-prior-art/blogs/_summary.md posts #6 #7 (hboon, ksingh): tmux config recipes, 3-5 concurrent CC sessions in windows.

Convergent on tmux as the multiplexing layer. Disagreement is on tooling layered on top (claude-squad vs Agent Teams vs claude-tmux vs hand-rolled). For Wes’s existing fleet (already running tmux + launchd-managed variant sessions), this is more “menu of options” than contradiction.

6.3 Agent count ceiling

external-prior-art/blogs/_summary.md post #7 (ksingh): “3-5 agents max — past that, token cost and coordination overhead dominate.”
external-prior-art/github/_summary.md (sethdford/claude-fleet): “biology-inspired noise. Wes runs 18 named variants; this is for actual N≫18 swarms.”
fleet-state/variants.md: Wes’s actual Active 18 roster.

Contradiction on what scale is sustainable:

ksingh: 3-5 max for tmux multi-agent within one machine.
Wes: 18 named variants across 5 machines.

Reconciliation: ksingh is talking about concurrently-attended agents inside one tmux window. Wes’s 18 are distributed across 5 machines and mostly long-running supervised sessions, not concurrent foreground panes. Both can be true. The design doc should distinguish “interactive concurrent agents” (3-5) from “supervised fleet variants” (much higher, gated by hardware).

6.4 Forked subagent vs fresh spawn

sdk-patterns/05-ccleaks-claude-internals.md (§8b): Direct quote from leaked source: “Research: fork open-ended questions. Launch parallel forks. A fork beats a fresh subagent — it inherits context and shares cache. Implementation: prefer to fork work that requires more than a couple of edits.”
research/01-github-recon.md: Closest analog in lee-fuhr/claude-session-index — uses in-session Haiku subagent for synthesis.

No contradiction — ccleaks’s quoted source establishes the canonical guidance (fork by default for short tasks; spawn fresh subagent only when a different persona is needed).

7. Drift / re-injection strategies

7.1 PreCompact + PostCompact pair vs SessionStart-only

sdk-patterns/05-ccleaks-claude-internals.md (§2a): Lists both PreCompact and PostCompact as real hooks. PreCompact can block (exit 2); PostCompact is fire-and-forget.
external-prior-art/blogs/_summary.md post #5 (adolan): “Use all six Claude Code hooks: session-start, user-prompt-submit, stop, session-end, pre-compact, post-compact. Pre/post-compact pair is critical for surviving in-session compaction.”
fleet-state/extracted-concepts.md “Default Hook Baseline”: Wes’s fleet uses PreCompact (pre-compact.js + write-handoff.js + deep-transcript-scan.js) but doesn’t list PostCompact.
external-prior-art/blogs/_summary.md post #14 (youngleaders): PreToolUse hook with PPID flag instead of SessionStart, because SessionStart doesn’t fire post-compact.

Convergent finding: PreCompact + PostCompact (or PreToolUse with PPID) is the canonical pattern. Wes’s current baseline has PreCompact but lacks an explicit PostCompact step — that’s a real gap.

Recommendation: Add PostCompact hook to the fleet baseline.

7.2 UserPromptSubmit re-injection cadence

sdk-patterns/04-agent-persona-patterns.md (§3.4): “Optional: a UserPromptSubmit hook that re-injects a 1-line ‘you are Pepper’ reminder every N turns.”
external-prior-art/blogs/_summary.md post #14 (youngleaders): Uses PreToolUse not UserPromptSubmit for the every-tool-call PPID-gated injection.

Different events for similar purpose. UserPromptSubmit fires on every user message; PreToolUse fires on every tool call. They serve different cadences (user-driven vs agent-driven). Both valid; pick one based on what you’re trying to debounce.

7.3 SillyTavern V2 `post_history_instructions`

sdk-patterns/04-agent-persona-patterns.md (§1.3): Names it as the canonical persona- pinning mechanism. “Re-injected near the tail of context.”
No other report mentions it.

No contradiction — one report cites it; others don’t address it directly.

7.4 Watcher post-clear push

fleet-state/extracted-concepts.md “Watcher authority”: “The named watcher has direct authority to (1) read/verify pre-clear handoff, (2) push rehydrate trigger post-clear, (3) verify rehydration via 3-item challenge, (4) re-clear and re-push on failure, (5) direct-inject /clear via stdin-pipe when peer-mesh can’t reach.”
All research reports: Don’t address this Wes-specific pattern.

No contradiction — fleet-specific protocol.

8. Star counts / popularity facts

8.1 thedotmack/claude-mem stars

external-prior-art/github/_summary.md: “Stars: 74,948 · Last push: 2026-05-12”
research/04-community-signal.md: Lists claude-mem but doesn’t quote a star count.
research/01-github-recon.md: Doesn’t list claude-mem in the survey table at all.

Conflict in coverage, not in star count. External-prior-art (#11) has the up-to-date star count (74,948); research/01-github-recon.md (#1) doesn’t include claude-mem in its top candidates list — this is a real research gap. Both other reports independently surface claude-mem as relevant.

Action item: github-recon should be updated to include claude-mem if it’s actually 74k+ stars. Either the star count is right (and github-recon missed a major repo) or there’s an error.

8.2 wshobson/agents stars

external-prior-art/github/_summary.md: “Stars: 35,230”

No other report mentions this repo. No contradiction.

8.3 shanraisshan/claude-code-best-practice stars

external-prior-art/github/_summary.md: “Stars: 52,455”

No other report addresses. No contradiction but this is a very popular repo not mentioned in the research/ directory’s deeper analyses.

8.4 ryoppippi/ccusage stars

research/01-github-recon.md: “Stars: 14,042”

No other report disputes.

8.5 raine/claude-history stars

research/04-community-signal.md: “(259 stars, the most-starred contender)” in practitioners list.
research/01-github-recon.md: Doesn’t include this repo in the inventory.

Coverage gap, not contradiction. github-recon missed raine/claude-history as one of the most-starred Claude history tools.

8.6 simonw/claude-code-transcripts stars

research/01-github-recon.md: “Stars: 1,507”

No other report disputes.

8.7 daaain/claude-code-log stars

research/01-github-recon.md: “Stars: 1,014”

No other report disputes.

8.8 jhlee0409/claude-code-history-viewer stars

research/01-github-recon.md: “Stars: 1,236”

No other report disputes.

8.9 marcelocantos/mnemo stars

research/01-github-recon.md: “Stars: 0 (new, but Apache-2.0, very active — last commit 2026-05-11)”

No other report mentions. Be careful — github-recon’s top recommendation is a 0-star project. Worth verifying maturity before adopting.

8.10 wesm/agentsview stars

research/01-github-recon.md: “Stars: 928, forks 123, MIT, last commit 2026-05-11. Author is Wes McKinney (pandas creator) — high signal.”

No other report disputes.

9. Specific config flags / env vars

9.1 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

external-prior-art/github/_summary.md (#2 wshobson/agents): Uses CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 flag with teammateMode: "tmux".
external-prior-art/blogs/_summary.md post #7 (ksingh): “Required settings: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1' + CLAUDE_CODE_SPAWN_BACKEND: 'tmux' + teammateMode: 'tmux' in ~/.claude/settings.json.”
external-prior-art/blogs/_summary.md post #13 (shipyard): Same flag.
sdk-patterns/05-ccleaks-claude-internals.md: Doesn’t explicitly list this flag in its env var inventory; it’s the experimental flag for Agent Teams which ccleaks describes separately as COORDINATOR_MODE.

Conflict / clarification: ksingh adds CLAUDE_CODE_SPAWN_BACKEND: "tmux" to the set; wshobson and shipyard don’t mention it. ccleaks doesn’t list either CLAUDE_CODE_EXPERIMENTAL_ AGENT_TEAMS or CLAUDE_CODE_SPAWN_BACKEND in its primary env var table.

Reconciliation: The flag IS real (multiple practitioner sources). CLAUDE_CODE_SPAWN_ BACKEND is the newer addition. The full activation set is probably:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
CLAUDE_CODE_SPAWN_BACKEND=tmux (optional)
teammateMode: "tmux" in settings.json

9.2 COORDINATOR_MODE vs AGENT_TEAMS

sdk-patterns/05-ccleaks-claude-internals.md (§3a): “CLAUDE_CODE_COORDINATOR_MODE activates orchestrator mode (workers + coordinator), gated by feature('COORDINATOR_MODE').”
external-prior-art/blogs/_summary.md post #13 (shipyard): Names “Agent Teams” as the Anthropic-official path forward.

Likely the same feature with different external/internal names. ccleaks pulled COORDINATOR_MODE from the leaked source; the shipping name in settings is “Agent Teams” / CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Both reports are consistent if you accept that internal name ≠ external name.

9.3 CLAUDE_ENV_FILE

sdk-patterns/05-ccleaks-claude-internals.md (§2c, §3e): CLAUDE_ENV_FILE set in SessionStart, Setup, CwdChanged, FileChanged hooks. “Write to $CLAUDE_ENV_FILE to persist env vars into all subsequent Bash commands in the session.” Cites official hook docs.
No other report addresses.

No contradiction. This is a useful undocumented-elsewhere pattern.

9.4 CLAUDE_CODE_DISABLE_* family

sdk-patterns/05-ccleaks-claude-internals.md (§3a, §3c): Lists CLAUDE_CODE_DISABLE_ AUTO_MEMORY, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS, CLAUDE_CODE_DISABLE_CRON, CLAUDE_CODE_DISABLE_THINKING, CLAUDE_CODE_DISABLE_FAST_MODE, CLAUDE_CODE_DISABLE_1M_ CONTEXT.
No other report enumerates this family.

No contradiction. Use ccleaks list with confidence: HIGH (direct source extraction).

9.5 ANTHROPIC_MODEL precedence

sdk-patterns/05-ccleaks-claude-internals.md (§3d): “Session > flag > ANTHROPIC_MODEL env > settings.json > default”
No other report explicitly addresses.

No contradiction.

9.6 CLAUDE_CODE_NEW_INIT

sdk-patterns/05-ccleaks-claude-internals.md (§3e): “=1 enables interactive multi- phase /init flow.”
No other report addresses.

No contradiction.

9.7 NODE_OPTIONS auto-set

sdk-patterns/05-ccleaks-claude-internals.md (§3a): “CLAUDE_CODE_REMOTE … bumps NODE_OPTIONS max-heap to 8GB.”
sdk-patterns/05-ccleaks-claude-internals.md (§3c): “NODE_OPTIONS — Set to --max-old-space-size=8192 when remote.”

Internally consistent in same report.

9.8 worktree settings

sdk-patterns/05-ccleaks-claude-internals.md (§4b, §11f): worktree.symlinkDirectories and worktree.sparsePaths settings; default path <project-root>/.claude/worktrees/.
external-prior-art/github/_summary.md (claude-squad): Uses git worktree per agent (its own implementation, predates the worktree settings).

No contradiction — ccleaks documents the official setting; claude-squad implements its own flavor of the same idea.

9.9 `autoMemoryDirectory` scope restriction

sdk-patterns/05-ccleaks-claude-internals.md (§10a): “Per autoMemoryDirectory (user/policy only — explicitly NOT accepted from project/local settings, since cloned repos could redirect to sensitive locations).”
No other report addresses.

No contradiction. Important security-relevant constraint to know.

9.10 `claudeMdExcludes`

sdk-patterns/05-ccleaks-claude-internals.md (§1f): “claudeMdExcludes setting (in settings.json at any layer) takes glob patterns matched against absolute file paths.”
No other report addresses.

No contradiction.

10. Other / miscellaneous contradictions

10.1 Subagent cannot spawn subagents

sdk-patterns/01-claude-openai-sdk.md (Antipattern): “Subagents cannot spawn other subagents. No nested delegation.”
sdk-patterns/05-ccleaks-claude-internals.md (§8e): Coordinator mode workers “can be set by CLAUDE_CODE_SIMPLE” with different capability sets. Doesn’t explicitly say workers can spawn workers.

Convergent on “no nesting” by default. Coordinator mode might lift this restriction, but the docs say even in coordinator mode the workers are leaf nodes.

10.2 Auto-memory: enable count

sdk-patterns/05-ccleaks-claude-internals.md (§10c, §10d): Auto-memory + auto-dream gate via tengu_onyx_plover GrowthBook flag.
fleet-state/extracted-facts.md “Auto Dream”: “If ~/.claude/.dream-pending exists at session start, run /dream as a subagent in background. Memory consolidation system runs every 24h.”
sdk-patterns/05-ccleaks-claude-internals.md Tier 1 §3: WARNING — “Wes has a custom /dream skill plus the auto-dream cron flag in his global CLAUDE.md. Per the extracted source, Claude Code’s isAutoDreamEnabled() defaults via tengu_onyx_plover GrowthBook gate; the gate could be ON. If both run, you get duplicate consolidation work and possibly conflicting writes to MEMORY.md.”

Real conflict in Wes’s setup: custom /dream skill AND Anthropic native auto-dream might both be firing.

Action item: Verify autoDreamEnabled settings.json on each machine; if Anthropic native is running, decide whether to disable native or disable custom.

10.3 fleet-node port

fleet-state/extracted-facts.md: “fleet-node runs on Cheesegrater port 7700.”
external-prior-art/github/_summary.md (claude-mem): Worker daemon on “port 37700 + (uid % 100).”

Different ports for different services. No conflict — fleet-node and claude-mem are different daemons.

10.4 hines-mcp port 3847 status

fleet-state/broken-canon.md finding #2: “hines-mcp on Grater :3847 was deprecated by Wes 2026-04-22 and confirmed dead by Flint’s grater-lane audit.” Multiple canon docs say deprecated.
Fleet/architecture/peer-bridge-runbook.md L128 (cited in broken-canon.md): Still names it as a live fleet-service.

Single conflict already flagged. The runbook line is stale; deprecation is canon. Use: hines-mcp:3847 = DEAD/DEPRECATED.

10.5 Active 18 list — minor reorderings

fleet-state/broken-canon.md finding #C5: Multiple canon docs list the Active 18 with slightly different orderings (Cultron vs Clase reordered). Same membership.

Not a real contradiction — just inconsistent ordering across docs.

10.6 Machine count

fleet-state/extracted-facts.md “Fleet is 5 machines”: Canon = 5 (Mac, PC, iMac, Cheesegrater, Clarvis).
~/.claude/docs/user.md L5: “4-machine fleet” — flagged stale by broken-canon.md finding #3.
MEMORY auto-memory: “5-Machine Fleet Status.”

Already-flagged contradiction. Use 5 machines.

10.7 Vault path on Clarvis

~/.claude/docs/fleet-rules.md L21-25: Lists vault paths for Cheesegrater, PC, Mac, iMac — missing Clarvis (M1).
machines.md L31: Clarvis = ~/jarvis/hinesipedia/ (Samba mount from Grater).
broken-canon.md finding #4: Already flags this.

Already-flagged contradiction. Add Clarvis to fleet-rules.md.

10.8 Coordination protocol tiebreaker

conventions.md L18: Cheesegrater > Clars > Clippy > iMac > Mac > PC.
machines.md L73: Cheesegrater > Clars > Clippy > iMac > Mac (no PC).
fleet-rules.md L31: cheesegrater > iMac > Mac > PC (no Clars; uses “PC” not “Clippy”).

Three different orderings across canon docs. Already-flagged contradiction. Use conventions.md ordering as canonical (most complete + most recent).

10.9 Mac hosts Clars workers?

machines.md L13: “Mac … Also hosts Clars worker agents.”
variant-mapping.md: Clars is on Clarvis (M1).
broken-canon.md finding #5: Already flags this.

Already-flagged contradiction. Use: Mac hosts Codex + ad-hoc; Clars-the-persona is on M1.

10.10 Subagent inheritance of CLAUDE.md cascade

sdk-patterns/05-ccleaks-claude-internals.md (§8c): “CLAUDE.md cascade applies to the subagent’s cwd at spawn time — so if you spawn a subagent in a subdirectory, the cascade is rooted there.”
sdk-patterns/01-claude-openai-sdk.md (§1.5): “Subagents receive only this system prompt (plus basic environment details like working directory), not the full Claude Code system prompt.”

Conflict on what loads in a subagent:

ccleaks says CLAUDE.md cascade applies at subagent cwd.
SDK-patterns says subagents get only their subagent system prompt + env details, not the parent’s full system prompt.

Reconciliation: Two different concepts conflated. CLAUDE.md is a user message (per docs), not the system prompt. SDK-patterns is saying subagent SYSTEM prompt is the subagent’s frontmatter+body, not Claude Code’s full system prompt. ccleaks is saying the CLAUDE.md USER-message cascade still applies based on the subagent’s cwd. Both are true.

10.11 Skills are loaded as system prompt entries

sdk-patterns/05-ccleaks-claude-internals.md (§6d): “At session start: ONLY name + description from every skill’s frontmatter is loaded into the system prompt.”
sdk-patterns/01-claude-openai-sdk.md (§3.1): Same — “Metadata (~100 tokens): The name and description fields are loaded at startup for all skills.”

Convergent.

10.12 Skills replace slash commands

sdk-patterns/05-ccleaks-claude-internals.md (§5e): “Custom slash commands have been merged into skills.”
sdk-patterns/01-claude-openai-sdk.md: Doesn’t explicitly say merged, but the Mapping table treats them as separate.

Soft conflict. ccleaks directly quotes Anthropic that slash commands are merged into skills. SDK-patterns implies they’re distinct surfaces. Use ccleaks (more current).

10.13 Tony→Clars rename date

fleet-state/extracted-facts.md: “Tony→Clars rename 2026-04-17.”
fleet-state/variants.md: “Session dir still named clarvis-tony-session (Tony→Clars rename 2026-04-17 not propagated).”

Convergent. No contradiction.

10.14 “Active 18” current liveness

fleet-state/variants.md: Roster of 18, mostly operational by persona presence; flags orphans (Stark, Lens, Quill, Prospecting, iMessage).
fleet-state/recent-activity.md: “Only 3 categories of variants kept doing meaningful work in the final week before pause.” Most variants paused.

Reconciliation: Active 18 is the canon roster, not the current liveness. The two reports cover different questions. Both correct, no contradiction.

10.15 Total session count in claude-brain (adolan)

external-prior-art/blogs/_summary.md post #5 (adolan): “1,321 sessions, 67k messages.”

No other report cites different numbers. No contradiction.

10.16 Codex auto-compact threshold

research/02-tool-comparison.md (Codex section): “Codex’s own desktop app gets laggy because it scans every rollout file rather than maintain its own index. That is the bug we are designing around.”
No other report addresses Codex’s threshold directly.

No contradiction, just supporting evidence.

10.17 SQLite vs LMDB for storage

research/02-tool-comparison.md (Zed section): Zed migrated from JSON-per-conversation to threads-db.1.mdb (LMDB-style).
All other recommendations: SQLite.

Not a contradiction — tool-comparison is reporting on Zed’s choice (which it flags as a regression), not recommending LMDB.

10.18 Per-session JSONL vs single DB

research/02-tool-comparison.md: Claude Code uses per-session JSONL at ~/.claude/ projects/<cwd-with-dashes>/<session-uuid>.jsonl.
research/05-indexing-tech.md: Single SQLite DB events.db for index.

No contradiction — these are different layers (raw storage vs derived index).

10.19 What `cwd` field looks like

research/02-tool-comparison.md (claude code schema): “cwd: '/home/user/myapp'” — absolute path in JSONL.
fleet-state/recent-activity.md: Directory names key sessions, e.g., -Users-clarvis-clarvis-orchestrator.bak-fresh-2026-05-06-22-54-51-292 — slashes replaced with dashes.

Two different surfaces: the JSONL stores absolute path; the ~/.claude/projects/ dir name encodes the path with slashes replaced. Both correct, different layers.

10.20 Subagent transcript path

sdk-patterns/01-claude-openai-sdk.md (§1.5): Session transcript “at ~/.claude/projects/<project>/<sessionId>/subagents/agent-<agentId>.jsonl.”
research/02-tool-comparison.md: Doesn’t address subagent transcripts specifically.

No contradiction — only one report covers this.

11. CONVERGENT FINDINGS — high-confidence inputs for design doc

These are statements that ALL reports addressing them agree on. Treat as load-bearing.

Memory architecture

MEMORY.md has a hard limit of 200 lines OR 25KB, whichever fires first.
Root project CLAUDE.md re-injects after /compact; nested CLAUDE.md files do not.
CLAUDE.md target: under 200 lines (Anthropic-cited; practitioners run 50-80 for personal globals).
@path imports have a maximum recursion depth of 5 hops, relative paths resolve to the file containing the import (not cwd).
@path imports load at launch and do NOT reduce context (organization only, not budget savings).
Auto-dream defaults: >24h since last cleanup AND >=5 new sessions accumulated.
Auto-memory writes via the Stop hook (handleStopHooks).
Four memory types in Anthropic auto-memory: user, feedback, project, reference.
Memory tool ops are 6: view, create, str_replace, insert, delete, rename.
Routing rules belong in CLAUDE.md (loads fully); learnings belong in MEMORY.md/topic files (200-line cap).

Hooks

Hook count: 28 events as of v2.1.116, April 2026 (older docs say 12-14 or 20; current is 28).
Hook precedence (highest first): Managed > Skill/Agent frontmatter > Project local > Project > Plugin > User.
PreCompact + PostCompact pair is required for surviving in-session compaction; the SessionStart hook does NOT fire after compaction.
Hook input is JSON on stdin; session_id is in JSON, not an env var.
CLAUDE_ENV_FILE (written to in SessionStart/Setup/CwdChanged/FileChanged) persists env vars into subsequent Bash calls — the legitimate way to load secrets without echoing.

Identity

PersonaName/canonical_name is the durable identity; runtime-id, peer-id, bot_username, cwd are transport artifacts.
Peer IDs roll after clear, compact, restart, or broker changes — always re-discover before sending.
Subagents do not nest (no subagent spawning subagents in default Claude Code).
AGENT-STATE.md is a lead, not authority — verify against fresh handoff/live probe/D1 before treating as truth.

Storage

SQLite FTS5 is the consensus default for transcript indexing across all reports.
sqlite-vec is preferred over sqlite-vss (vss is in maintenance mode; author migrated to sqlite-vec).
ChromaDB is discouraged for new builds (history of breaking changes, mid-tier perf).
BM25 + dense + RRF (k=60) is the consensus hybrid pattern; reranker (BGE) only if measurement shows it pulls weight.
Don’t ship embeddings as a hard dependency; FTS5 day-one, embeddings background opt-in.
parent_uuid graph should be preserved, not flattened at ingest; sidechains exist in Claude Code transcripts.
Schema fidelity preserves: uuid, parent_uuid, is_sidechain, cwd, session_id, timestamp, type, full message.content[] JSON, usage.*.

Subagent dispatch

Fork (no subagent_type) beats fresh spawn for research/short tasks — inherits parent’s prompt cache.
Use fresh subagent only when a different persona/system prompt is needed.

Folder organization

Frameworks converge on role-based (agents/, tools/, workflows/), not lifecycle- based (Active/, Archive/).
Runtime state lives in databases/checkpointers, not folders next to code.
.env.example + tests/ + config-at-root is universal across agent frameworks.

Compaction & continuity

Auto-compact triggers at ~187K/200K tokens (~93.5%), not 80% — ccleaks-sourced.
13K-token buffer is preserved across auto-compact.
Max 3 compact failures before falling back.

Identity / persona layering

Four-layer identity stack (SOUL / ETHOS / PERSONA / RUNTIME) maps cleanly to Wes’s fleet practice (soul.md / fleet-ethos.md / variants/<name>.md / scripts/sessions/).
Persona file recommended length: 30-80 lines.
Co-locate persona body + runtime config in one file via YAML frontmatter; enforcement settings (settings.json) stay separate.

Multi-agent / parallel work

3-5 concurrent interactive agents max per machine (token cost + coordination overhead).
18-variant supervised fleet is sustainable when variants are mostly long-running background processes across multiple machines (Wes’s actual fleet).
Anthropic’s official path: Agent Teams via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 + teammateMode: "tmux".
Coordinator mode (COORDINATOR_MODE) is the upstream pattern — Anthropic’s internal multi-agent system, still flag-gated for externals.

Fleet topology

5 machines — Mac (M3 Air), Clippy (Win 11), Cheesegrater (Ubuntu Mac Pro), iMac (headless Ubuntu), Clarvis (M1 Air). user.md saying 4 is stale.
Vault is at ~/jarvis/hinesipedia/ on Mac/M1 (Samba), /storage/jarvis/hinesipedia/ on Grater (native), /mnt/jarvis/hinesipedia/ on iMac (NFS), Z:\hinesipedia\ on PC (SMB).
hines-mcp on Cheesegrater :3847 is DEPRECATED/DEAD (since 2026-04-22).
Active 18 roster: Pepper, Nagatha, Bilby, Clippy-Main, Stark, Lens, Quill, Clarvis, Clars, Cultron, Clase, iMessage, Flint, Gravel, Prospecting, Aleph, Blue, Jiminy.
Only ~6 variants doing real work in past week — Flint/Gravel/Vaultmate (Grater), Aleph/Blue (iMac), KalshiWeather (project-level).

Security

NEVER Read integrations-keys.env — use grep against LHS only.
fleet-node /store/memory/<KEY>?namespace=X is the correct retrieval pattern; the namespace-dump pattern (no key in URL) leaks the entire namespace.
fleet-node /store/memory (no key in URL) is for WRITES; keyed path returns 404.
Transcripts are sensitive — anything that enters one is leaked permanently.

Frameworks adopted vs rejected (across memory-frameworks report)

Adopt patterns from: Graphiti (bi-temporal), Mem0 (single-pass ADD-only), Cognee (Memify), Letta (core-memory blocks).
Reject as runtime dependencies: Neo4j, Postgres, Mem0 server, full Letta.

Indexing prior art top picks

mnemo + agentsview (+ optional cchv-server) is the closest already-shipped feature set for Wes’s use case (per research/01-github-recon.md).
claude-mem (thedotmack) is the strongest single architecture template (hooks + SQLite
- daemon + multi-account isolation + graceful degradation) (per external-prior-art/github/_summary.md).

Critical anti-patterns

Never put all history into the harness’s KV store (globalState) — Cline/Roo crashed VS Code doing this.
Never opaque binary storage without a schema doc — Zed’s regression.
Never scan every JSONL on every search — Codex desktop + Claude Code UX both do this; the indexer is designed to solve it.
Never re-flow the conversation at ingest (linearization loses parent_uuid DAG).
Never put tokens through chat substrates (peer-mesh, Telegram, Slack, Notion) — those persist long-term.
Never accept relayed authorization for permissions/auth/billing/destructive ops.

12. Open contradictions (no winner declared — flag for design-doc author)

Two locations for persona files (vault <Name>/persona.md vs ~/.claude/docs/variants/ <name>.md). Decision needed: single source of truth.
Mac hosts Clars workers — machines.md says yes, variant-mapping.md says no. Resolve before restarts.
autoDreamEnabled collision risk — custom /dream skill + Anthropic native auto-dream might both fire. Verify per-machine settings.json and pick one.
D1 vs Postgres vs SQLite for fleet-wide read model — depends on corpus size + ops tolerance. Indexing-tech recommends local SQLite; memory-frameworks recommends D1; github-recon recommends Postgres (via agentsview).
Single events table vs episodes/entities/facts schema — depends on whether drift detection is in-scope for Phase 1 or deferred.
Selective vs broad embedding — depends on corpus size. Below ~5M events, broad is probably fine; above, selective wins on recall.

13. Coverage gaps (research issues to flag)

These are repos / patterns mentioned in one report but missing from another’s coverage:

thedotmack/claude-mem (~74k stars per external-prior-art; not in research/01-github- recon.md survey table).
raine/claude-history (259 stars, “most-starred contender” per research/04-community- signal.md; not in research/01-github-recon.md either).
shanraisshan/claude-code-best-practice (52k stars, encyclopedia-as-repo; only in external-prior-art).
wshobson/agents (35k stars, plugin marketplace; only in external-prior-art).

These are coverage gaps in the GitHub recon. Worth back-filling if the design doc needs to cite the most-popular tools in the space.

14. Process notes

All “contradictions” flagged here are either real disagreements between reports OR cases where two reports use different terminology for similar concepts (and the resolution is “they both work, pick your terms”).
For genuine factual disagreements, the rule of thumb is: the report citing primary docs (Anthropic / ccleaks-source-extracted) wins over reports citing community blog posts.
Reports based on the fleet’s own internal docs (fleet-state/*) are trusted for fleet state but can themselves contain stale claims (per broken-canon.md).
Where Wes’s existing fleet practice contradicts a research recommendation, the practice generally wins (he’s the operator; the research informs adjustments).

15. One-line takeaway

Reports converge on more than they disagree on. The high-confidence convergent findings (§11) are the load-bearing inputs for the design doc; the conflicts (§§1-10) are mostly resolved by preferring reports that cited official docs or leaked-source extracts over those that cited community blogs. The handful of unresolved disagreements (§12) need a decision from Wes or further verification before the design doc commits.

Cross-reference audit

04 — Cross-Reference Audit

1. Memory limits & loading

1.1 MEMORY.md size cap — three different numbers

1.2 CLAUDE.md size target

1.3 What survives compaction

1.4 Auto-compact trigger threshold

1.5 Dream / consolidation cadence

1.6 Anthropic Memory tool ops

1.7 Memory types count

2. Hook lifecycle

2.1 Hook count — 6, 12-14, 20, 28

2.2 Which hook fires on auto-memory extraction

2.3 Default hook baseline (Wes’s fleet)

2.4 Hook input shape — fields

2.5 Hook precedence / config sources

2.6 Hook timeout values

2.7 InstructionsLoaded hook

3. Folder structure recommendations

3.1 PARA vs Active/Reference/Logs/Archive vs role-based src/ vs JD

3.2 Top-level “use the same skeleton everywhere”

3.3 Where personas live

3.4 Subagent file location precedence

4. Agent identity layering (SOUL / ETHOS / PERSONA / RUNTIME)

4.1 Number of layers in identity stack

4.2 Persona file recommended length

4.3 Re-injection cadence for persona drift

4.4 Where persona lives

4.5 What “@import” does to context

5. Storage / indexing tech

5.1 SQLite FTS5 vs DuckDB vs Tantivy vs hybrid

5.2 DuckDB vs SQLite for analytics

5.3 Two-table vs single-table schema

5.4 Embedding strategy — embed everything or selective

5.5 Hybrid search — RRF vs reranker vs both

5.6 D1 vs SQLite for fleet-wide read model

6. Multi-agent coordination patterns

6.1 Coordinator/Worker vs Wave vs Pipeline vs Consensus

6.2 tmux + claude-squad vs tmux + Agent Teams vs claude-tmux

6.3 Agent count ceiling

6.4 Forked subagent vs fresh spawn

7. Drift / re-injection strategies

7.1 PreCompact + PostCompact pair vs SessionStart-only

7.2 UserPromptSubmit re-injection cadence

7.3 SillyTavern V2 post_history_instructions

7.4 Watcher post-clear push

8. Star counts / popularity facts

8.1 thedotmack/claude-mem stars

8.2 wshobson/agents stars

8.3 shanraisshan/claude-code-best-practice stars

8.4 ryoppippi/ccusage stars

8.5 raine/claude-history stars

8.6 simonw/claude-code-transcripts stars

8.7 daaain/claude-code-log stars

8.8 jhlee0409/claude-code-history-viewer stars

8.9 marcelocantos/mnemo stars

8.10 wesm/agentsview stars

9. Specific config flags / env vars

9.1 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

9.2 COORDINATOR_MODE vs AGENT_TEAMS

9.3 CLAUDE_ENV_FILE

9.4 CLAUDE_CODE_DISABLE_* family

9.5 ANTHROPIC_MODEL precedence

9.6 CLAUDE_CODE_NEW_INIT

9.7 NODE_OPTIONS auto-set

9.8 worktree settings

9.9 autoMemoryDirectory scope restriction

9.10 claudeMdExcludes

10. Other / miscellaneous contradictions

10.1 Subagent cannot spawn subagents

10.2 Auto-memory: enable count

10.3 fleet-node port

10.4 hines-mcp port 3847 status

10.5 Active 18 list — minor reorderings

10.6 Machine count

10.7 Vault path on Clarvis

10.8 Coordination protocol tiebreaker

10.9 Mac hosts Clars workers?

10.10 Subagent inheritance of CLAUDE.md cascade

10.11 Skills are loaded as system prompt entries

7.3 SillyTavern V2 `post_history_instructions`

9.9 `autoMemoryDirectory` scope restriction

9.10 `claudeMdExcludes`

10.19 What `cwd` field looks like