solution-erp/docs/changelog/sessions/2026-05-12-1800-s21-turn2-rag-planning.md

Session 21 turn 2 — RAG Hybrid setup planning + Cách A validation deep dive

Date: 2026-05-12 (tiếp S21 turn 1 từ 0030 sáng — sang sáng-chiều-tối discussion deep RAG) Dev: Claude (Opus 4.7 1M Max — em main solo, no SOLUTION_ERP sub-agent spawn) Base commit: 3a34831 (S21 turn 1 chốt cicd-monitor) Commits: 1f8e9af (RAG plan save) + this chốt (2 commit S21 turn 2)

Bối cảnh

Sau S21 turn 1 chốt cicd-monitor (4 sub-agents seeds-only), bro đặt câu hỏi về RAG infrastructure cho 5 dự án future > 1M MD context. Cuộc thảo luận deep ~15+ turn covering:

1. RAG fundamentals + Vector DB role
2. Embedding model "AI nhúng" + Voyage AI cost mechanics
3. Multi-project shared architecture (5 projects)
4. Audit procedure 3-tier + change tracking SQLite
5. UI/UX Streamlit dashboard 7 pages
6. Cách A defensive (giữ blanket) vs Cách B aggressive (cắt 60-70%)
7. Reasoning depth comparison (lazy current vs Cách A vs Cách B)
8. Industry validation via claude-code-guide research
9. Multi-agent cumulative cost reality (4 agents → ~520K cumulative blanket)
10. 3-layer hybrid pattern (Anthropic Contextual Retrieval: embeddings + BM25 + reranking)

Deliverables

File mới — docs/rag-setup-plan.md (commit 1f8e9af, 1223 LOC)

Cross-project reference plan với 12 section comprehensive:

1. Context + Why
2. Architecture overview (6-layer diagram)
3. BLANKET load list (~100K, 28% MD)
4. RAG store list (~254K, 72% MD)
5. Tool stack recommend
6. Setup scripts copy-paste ready (~250 LOC Python)
7. Audit procedure 3-tier (weekly/monthly/quarterly)
8. Multi-AI client access (Claude Code + Desktop + Cursor + GPT-4)
9. Timeline rollout 10-14h dedicated session
10. Caveats + risks
11. Success metrics + decision gate
12. Future enhancements

File extend S21 turn 2 (this chốt commit)

Add 2 sections vào rag-setup-plan.md:

• Section 13: Multi-agent cumulative cost reality (Anthropic 8-10× warning)
• Section 14: 3-layer hybrid RAG upgrade path (Phase 1-3 Anthropic Contextual Retrieval)

Quyết định chốt — Cách A vs Cách B

Chọn Cách A (defensive hybrid) ⭐

Blanket: GIỮ NGUYÊN ~120K em main (35% MD)
RAG: ADD as supplement (retrieve on-demand)
Multi-agent: 4 sub-agents share retrieve cache
Sub-agent spawn blanket: ~80-100K each (auto-inject + skills + spec)
Cumulative blanket 5 entities: ~520K
Heavy session billed: ~560K (saving 20% vs lazy)

Why Cách A (priority bro: em main control flow strong):

1. ✅ State ownership strong — em main biết direct project state
2. ✅ Decision quality 90% (vs Cách B 75-80% do fragmentation)
3. ✅ Wall-clock per task 12 phút (vs Cách B 16 phút)
4. ✅ UX smooth — em response fast direct cho state question
5. ✅ Risk-averse — graceful degradation nếu RAG fail (blanket fallback)
6. ✅ Multi-agent leverage cache hit 70-90% common queries
7. ✅ Quality recall +25-55pp (5-15 sources cross-validated vs lazy 1-3)

Bỏ Cách B (aggressive cut)

Blanket: CẮT MẠNH 60-70% (40-50K còn lại)
RAG: PRIMARY access mechanism cho mọi thứ

Why bỏ:

1. ❌ Vi phạm priority "em main control flow strong"
2. ❌ State ownership weak — phải retrieve mỗi câu state question
3. ❌ UX latency +1-2s per state Q
4. ❌ Decision quality 75-80% do reasoning fragmentation
5. ❌ Risk severe nếu RAG fail (em main ngơ ngác)
6. ❌ Anthropic research warn: "context rot inevitable cutting aggressively"
7. ❌ Cascade retrieve problem (1 task → 2-3 retrieves)

Industry validation via claude-code-guide research

Spawn 2 lần claude-code-guide agent research (NOT SOLUTION_ERP sub-agents):

Round 1: Anthropic setup inventory (10 features)

• Memory tool beta (content-management-2025-06-27)
• Prompt caching extensions (5min/1h beta)
• Files API beta (files-api-2025-04-14)
• Citations stable
• MCP servers official + community (9,400+ in 2026)
• Voyage AI embedding partnership
• Context compaction tool
• Claude Agent SDK orchestration
• Batch API 50% discount
• RAG best practices Anthropic official

Round 2: Industry practice validation

5/5 dimensions Cách A fit Anthropic explicit recommend:

Dimension	Bro setup	Anthropic pattern
Context approach	Hybrid blanket+RAG	✅ Recommended explicit
Sub-agent count	4	✅ "3-5 optimal"
MD scale	5 project > 1M	✅ "Use RAG khi >200K"
Stack	Qdrant+Voyage+MCP	✅ Production validated
Coordination	Em main + agents	✅ "Coordinator+workers"

Source 4 Anthropic blog posts:

• "Effective Context Engineering for AI Agents" (2025)
• "Contextual Retrieval" (Sept 2024 flagship)
• "Effective Harnesses for Long-Running Agents"
• "Multi-Agent Coordination Patterns"

Community consensus (Tier 1 tools all Hybrid):

• Cursor IDE @codebase indexing
• Continue.dev MCP transport
• Cline / Roo-Cline filesystem + AST + dynamic context
• Aider code-as-graph
• Sourcegraph Cody graph-aware

→ ZERO tools adopt aggressive Cách B pattern. ALL evolve toward Cách A hybrid.

3-layer hybrid pattern (Anthropic Contextual Retrieval Sept 2024)

Layer 1: Embeddings (Voyage-3-large)
  → Semantic + synonym + multilingual catch
  Performance: baseline ~50% recall
  
+ Contextual prefix (Haiku-generated context):
  → +35% improvement = ~67% recall

Layer 2: BM25 (bm25s Python lib free)
  → Exact identifier + technical terms catch
  + Layer 1 = ~75% recall
  
Layer 3: Reranking (Voyage rerank-2)
  → Cross-attention deep relevance
  + Layer 1+2 = ~85% recall

Phase rollout incremental:

Phase	Layer	Recall	Cost/month
Phase 1 (Week 1-4)	Layer 1 vector only	~70%	~$1.50
Phase 2 (Month 2)	+ Layer 2 BM25	~78%	~$1.50 (BM25 free local)
Phase 3 (Month 3)	+ Layer 3 + Contextual	~92%	~$4-5

Multi-agent cost reality (Anthropic warn 8-10× multiplier)

Per entity blanket:
  Em main: ~120K
  Sub-agent each spawn: ~80-100K (auto-inject baseline + skills + spec)
  
Cumulative blanket 5 entities = ~520K

Heavy session full 4-agent spawn:
  Lazy current:  ~700K effective billed
  Cách A:        ~560K (-20% saving from multi-agent shared cache)
  
Cost multiplier vs solo em main: ~8-10×
Anthropic acknowledged: "Expect 3-10× token multiplier"

Saving Cách A breakdown (-140K):

• Em main lazy Read → retrieve: -25K
• 4 agents lazy Read → cached retrieve: -160K (share cache 70-90%)
• Reasoning streamlined: -20K
• Plus +60K retrieve cost added
• Net: -145K ≈ -20% per heavy session

Stack validated

Component	Tool	Reason
Vector DB	Qdrant local	Rust binary 50MB, agent-native 2026 leader
Embedding	Voyage-3-large	Anthropic partner, multilingual 26 lang, $0.18/M
MCP server	FastMCP Python	Official Anthropic SDK
Chunking	Custom adaptive Python	§6.5 compliant, transparent
Tracking	SQLite local	Event log + audit + cost analytics
Dashboard	Streamlit custom	7 pages multi-project
Re-index	Pre-commit hook	Native git, delta on commit

Total cost 5 projects: ~$1.50-5/month depending Phase. ~$0.50 initial embed.

Em main solo S21 turn 2 (no SOLUTION_ERP sub-agent spawn)

Spawn này session:
  ✅ claude-code-guide × 2 (generic agent for Anthropic research)
  ❌ Investigator / Implementer / Reviewer / CI/CD Monitor (vẫn seeds-only)
  
Em main solo qua context paste + Write file + research delegate.

Skills check

6 skills hiện tại unchanged. Decision KHÔNG add skill mới cho RAG vì:

• RAG là decision/architectural pattern, không phải workflow project-specific
• Cross-project applicable → memory entry phù hợp hơn skill
• Per rule §9.5 anti-pattern "viết skill chỉ để có thêm"
• Defer skill creation sau Phase 1 trial validate

Tests

Unit test 81 unchanged (0 test added — pure planning, không code change).

Memory entry mới

feedback_rag_hybrid_pattern.md (NEW — cross-project pattern reusable):

• Decision Cách A rationale (control flow priority)
• Multi-agent cost reality (8-10× multiplier)
• 3-layer hybrid pattern Phase 1-3 incremental rollout
• Stack validated (Voyage + Qdrant + FastMCP)
• When to apply / when NOT apply triggers
• Anti-patterns documented
• Anthropic 4 blog cross-ref

Verify chain

Check	Status
dotnet build	Không chạy (no .cs change)
dotnet test	Không chạy (no test added — pure docs)
npm build	Không chạy (no FE change)
Push origin	Pending end of turn
CI Gitea Actions	Skip per path filter .md
IIS prod deploy	KHÔNG xảy ra (CI skip, expected)

Docs updates

• ✅ docs/STATUS.md — Last updated S21 turn 2 + Recently Done row top
• ✅ docs/HANDOFF.md — TL;DR Session 21 turn 2 section + Last updated
• ✅ docs/rag-setup-plan.md — extend +Section 13 (cost reality) +Section 14 (3-layer)
• ✅ docs/changelog/sessions/2026-05-12-1800-s21-turn2-rag-planning.md — file này
• ✅ Memory user-level new: feedback_rag_hybrid_pattern.md
• ✅ Memory user-level: MEMORY.md index + 1 entry pointer
• ⏭ KHÔNG đụng: rules.md / architecture.md / gotchas.md / database/* / flows/* / skills/* / CLAUDE.md (no real change cho 8 file này)
• ⏭ KHÔNG flush 4 sub-agent MEMORY.md (chưa spawn, per §6.5 KHÔNG add noise)

Handoff Session 21 turn 3+

Plan I NEW — RAG Setup Implementation

Trigger: Bro confirm 5 dự án path + stack + pilot choice + Voyage API key + disk cleanup 5-8GB free.

Schedule: Dedicated session 10-14h weekend (per memory feedback_drastic_refactor_scope rule).

Phases:

• Phase 1 (Week 1-4): Layer 1 vector embeddings only — ~70% recall — ~$1.50/mo
• Phase 2 (Month 2): + Layer 2 BM25 hybrid — ~78% recall — ~$1.50/mo
• Phase 3 (Month 3): + Layer 3 Reranking + Contextual — ~92% recall — ~$4-5/mo

Pre-flight task: Spawn 🔵 Investigator audit MD inventory 5 dự án parallel → tinh chỉnh blanket list per project.

Plan B Contract V2 wire (vẫn pending S21 turn 1)

• Trial Week 1 multi-agent kick-off SOLUTION_ERP
• 6 tasks (Mig 28+29 + Service + Controller + FE × 2 + Pin V2)
• 4 sub-agents pipeline coordinate (lần đầu spawn 4 agents thật)

Plan C Test gap fill (vẫn pending)

Bundle Chunk E Plan B — 5 test pending:

• B4 silent 403 regression (gotcha #44 vi phạm §7)
• V2 Service ApproveV2Async UPSERT opinion
• Section gộp Chunk C render
• Mig 25 PATCH /user-selectable
• Mig 27 PATCH /api/menus/{key}

Plan D-F-G unchanged

• D: Hard blockers ops (UAT/SMTP/creds/backup) — BLOCKED chờ user
• F: Audit định kỳ 2026-06-01 (~3 tuần nữa, KHÔNG tự chạy)
• G: Multi-agent trial 4-week (post-S21 t1 + S21 t2 setup complete)

Stats cumulative S21 turn 2

Metric	Trước S21 t2	Sau S21 t2	Δ
DB tables	59	59	0
Migrations	27	27	0
Endpoints	~142	~142	0
FE pages	34	34	0
Unit tests	81	81	0
Gotchas	44	44	0
Memory entries	16	17	+1 (RAG hybrid pattern)
Skills	6	6	0
Sub-agents	4 seeds-only	4 seeds-only	0 (chưa spawn)
Commits S21	2 (f1c61c9 + 3a34831)	4	+2 (1f8e9af + this chốt)
MD plan files	0	1	+1 (rag-setup-plan.md 1223 LOC + 2 section extend)

Cross-ref

• S21 turn 1 session log: 2026-05-12-0030-s21-cicd-monitor-add.md
• Plan file: docs/rag-setup-plan.md (1223 + extend ~300 LOC = ~1500 LOC)
• Memory new: feedback_rag_hybrid_pattern.md (cross-project reusable)
• Industry research: claude-code-guide × 2 spawn agent reports
• 4 Anthropic blog cross-ref trong memory entry

Bài học chốt S21 turn 2

1. Em main control flow strong là priority bro — quyết định Cách A defensive over Cách B aggressive
2. Multi-agent cost realistic 8-10× solo — KHÔNG tránh được spawn baseline ~400K cumulative 4 agents
3. Anthropic recommend 3-layer hybrid pattern — embeddings + BM25 + reranking compound effect
4. Industry consensus = hybrid — Cursor + Continue + Cline + Aider all evolve toward hybrid
5. Voyage Vietnamese quality cần verify Week 1 — voyage-3-large multilingual nhưng explicit Vietnamese benchmark chưa publish
6. RAG setup = dedicated session 10-14h — per feedback_drastic_refactor_scope rule
7. 5 projects scale workable — single Qdrant + per-project collection + ~$2-5/month cost