From af6bfda2d8d183c98ca8b0697b4801d11433d4e0 Mon Sep 17 00:00:00 2001 From: Alessandro Costa Date: Wed, 1 Apr 2026 22:41:56 -0300 Subject: [PATCH] fix: address CodeRabbit review on PR #1574 - architecture-overview: add 'text' language to all fenced code blocks (MD040) - architecture-overview: split 'Stop' lifecycle into 'Summary' + 'SessionEnd' to match canonical 5-hook naming - production-guide: reference PR numbers for proposed settings not yet upstream Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/architecture-overview.md | 17 +++++++++-------- docs/production-guide.md | 6 +++--- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/architecture-overview.md b/docs/architecture-overview.md index ae66db29..10a4b457 100644 --- a/docs/architecture-overview.md +++ b/docs/architecture-overview.md @@ -2,7 +2,7 @@ ## System Layers -``` +```text +-----------------------------------------------------------+ | Claude Code (host) | | +-- Hook System (5 events) | @@ -36,11 +36,12 @@ | SessionStart | smart-install.js + context | Install deps + start worker + inject context | 60s | | UserPromptSubmit | session-init | Register session + start SDK agent + semantic injection | 60s | | PostToolUse | observation | Capture tool usage -> enqueue in worker | 120s | -| Stop | summarize + session-complete | Request summary + end session | 120s+30s | +| Summary | summarize | Request session summary from SDK agent | 120s | +| SessionEnd | session-complete | End session + drain pending messages | 30s | ## Data Flow -``` +```text User prompt -> session-init -> /api/sessions/init + /api/context/semantic | Tool use -> observation -> /api/sessions/observations @@ -63,7 +64,7 @@ Stop -> summarize -> /api/sessions/summarize ### CLAIM-CONFIRM (PendingMessageStore) -``` +```text enqueue() -> INSERT status='pending' claimNextMessage() -> UPDATE status='processing' (atomic) confirmProcessed() -> DELETE (success) @@ -74,7 +75,7 @@ Self-healing: messages in 'processing' for >60s reset to 'pending' ### Circuit-Breaker (SessionRoutes) -``` +```text Generator crash -> retry 1 (1s) -> retry 2 (2s) -> retry 3 (4s) -> consecutiveRestarts > 3 -> CIRCUIT-BREAKER -> markAllSessionMessagesAbandoned(sessionDbId) @@ -85,7 +86,7 @@ Counter resets to 0 when generator completes work naturally. ### Graceful Degradation (hook-command.ts) -``` +```text Transport errors (ECONNREFUSED, timeout, 5xx) -> exit 0 (never block Claude Code) Client bugs (4xx, TypeError, ReferenceError) -> exit 2 (blocking, needs fix) ``` @@ -94,7 +95,7 @@ The worker being unavailable NEVER blocks the user's Claude Code session. ### Deduplication (observations) -``` +```text SHA256(memory_session_id + title + narrative) -> content_hash If hash exists within 30s window -> return existing ID (no insert) ``` @@ -123,7 +124,7 @@ The conversion between them is handled by SessionStore and is critical for FK co Vector embeddings for semantic search. Each observation generates multiple documents: -``` +```text obs_{id}_narrative -> main text obs_{id}_fact_0 -> first fact obs_{id}_fact_1 -> second fact diff --git a/docs/production-guide.md b/docs/production-guide.md index b02500da..f77325ec 100644 --- a/docs/production-guide.md +++ b/docs/production-guide.md @@ -7,9 +7,9 @@ Practical guide based on 23 days of production usage with 3,400+ observations ac | Setting | Default | Recommended | Why | |---------|---------|-------------|-----| | CLAUDE_MEM_MAX_CONCURRENT_AGENTS | 2 | 3 | Better throughput without overload | -| CLAUDE_MEM_SEMANTIC_INJECT | (new) | true | Relevant context >> recent context | -| CLAUDE_MEM_SEMANTIC_INJECT_LIMIT | (new) | 5 | Sweet spot for token cost vs coverage | -| CLAUDE_MEM_TIER_ROUTING_ENABLED | (new) | true | ~52% cost savings, no quality loss | +| CLAUDE_MEM_SEMANTIC_INJECT | (proposed in PR #1568) | true | Relevant context >> recent context | +| CLAUDE_MEM_SEMANTIC_INJECT_LIMIT | (proposed in PR #1568) | 5 | Sweet spot for token cost vs coverage | +| CLAUDE_MEM_TIER_ROUTING_ENABLED | (proposed in PR #1569) | true | ~52% cost savings, no quality loss | ## Health Monitoring