solution-erp/docs/guides/rag-onboarding-guide.md

RAG Unified — Onboarding Guide cho dự án mới

Phiên bản: 1.0 (2026-05-22) — chốt bởi em main SOLUTION_ERP S26+S27. Pattern: Approach B Distributed Bootstrap + Option 4a Manual PowerShell Scripts (per memory user-level feedback_rag_distributed_ownership.md). Audience: Em main project Y/Z (NamGroup / DH Y Dược / Ashico / Vipix / dự án mới khác) khi anh pqhuy mở Claude Code session. Cấu trúc nguồn: SOLUTION_ERP em main đã pioneer setup D:\.claude-rag\ infrastructure + 4 PS scripts + custom Dashboard. Project khác TỰ BOOTSTRAP theo guide này (~10 phút mỗi project), KHÔNG em main project khác làm hộ.

---

§1 TL;DR (Quick start — 3 phút)

Anh pqhuy đã có RAG infrastructure global ở D:\.claude-rag\ (Voyage AI + Qdrant Windows native + FastMCP). Em main project X mới chỉ cần 3 bước:

# 1. Verify Qdrant + MCP server running (em pioneer đã setup)
rag-status

# 2. Tạo .claude/rag.json trong project root (template §4)
# 3. Bootstrap corpus
python D:\.claude-rag\bootstrap.py --project <project_id>

Restart Claude Code → 6 MCP tools mcp__rag-unified__* khả dụng trong session project mới.

Em main project mới responsibility:

• Tạo .claude/rag.json declare project_id + corpus_paths + sensitivity flag
• Run bootstrap.py ~5 phút embed
• Brief 4 sub-agent (nếu có setup multi-agent) qua MEMORY.md
• KHÔNG modify D:\.claude-rag\server.py (shared infrastructure)

---

§2 Background — Tại sao Approach B Distributed?

Bối cảnh

Anh pqhuy dev solo, có 5+ dự án cùng máy localhost (SOLUTION_ERP + NamGroup + DH Y Dược + Ashico + Vipix + tương lai). Mỗi project có 100-2000 file MD docs + agent memory.

Quyết định chốt (per memory feedback_rag_distributed_ownership.md)

Approach	Verdict
A. Em main SOLUTION_ERP làm hộ tất cả 4 project	❌ Vi phạm Cognition "writes single-threaded" - em không có context project khác
B. Distributed - 4 em main project khác tự bootstrap khi mở session	✅ CHỌN - đúng boundary, ownership rõ, sensitivity per project tự decide
C. Hybrid em làm 1 mẫu + 3 tự follow	🤔 Vẫn còn cross-boundary 1 lần

Lý do CHỌN Approach B

1. Cognition "writes single-threaded" principle - mỗi em main own context flow project mình
2. Em main project khác hiểu codebase sâu hơn - SOLUTION_ERP em không có context active NamGroup
3. Sensitivity per project - vd DH Y Dược client confidential, em main DH biết set share_to_global=false. Em main SOLUTION_ERP KHÔNG biết → có thể set sai → leak risk
4. Self-ownership re-bootstrap - khi project Y thêm 50 file mới, em main Y biết để re-bootstrap. Em main X không monitor được Y
5. Knowledge propagation natural - em main Y bootstrap → store_memory pattern → share_to_global=true → các em main khác hưởng lợi qua RAG cross-share

---

§3 Pre-check (Verify infrastructure global đã sẵn sàng)

Trước khi bootstrap, em main project mới CHECK:

# 1. Aliases hoạt động (sẽ load $PROFILE auto)
rag-status

Output kỳ vọng:

• [Qdrant Server] Status: Running PID xxx port 6333 (em pioneer đã start)
• [MCP Server] Registration: rag-unified [OK] Connected (user-level)
• [Voyage AI] API key set: [OK]

Nếu Qdrant DOWN:

rag-start    # Em pioneer setup, just start

Nếu MCP NOT REGISTERED: Em main project mới KHÔNG self-register. Báo anh pqhuy để re-add user-level (1 lần duy nhất per Windows user):

claude mcp add -s user -e "VOYAGE_API_KEY=$env:VOYAGE_API_KEY" -- rag-unified python "D:\.claude-rag\server.py"

Nếu API key MISSING:

[Environment]::SetEnvironmentVariable("VOYAGE_API_KEY", "pa-MiN...", "User")
# Restart Claude Code để pick up env var

---

§4 Bootstrap 3 steps cho project mới

Step 1: Tạo .claude/rag.json ở project root

Template generic:

{
  "project_id": "<kebab-or-snake-case-id>",
  "display_name": "<Tên đầy đủ project>",
  "corpus_paths": [
    "docs/**/*.md",
    ".claude/agent-memory/**/MEMORY.md",
    ".claude/skills/**/SKILL.md"
  ],
  "exclude_paths": [
    "docs/_archive/**",
    "node_modules/**",
    "bin/**",
    "obj/**",
    ".git/**"
  ],
  "extra_corpus": [
    "C:\\Users\\pqhuy\\.claude\\projects\\<project-folder>\\memory\\*.md"
  ],
  "share_to_global": true,
  "search_scope_default": ["self", "shared_global"],
  "auto_reindex": true,
  "chunk_size": 1500,
  "chunk_overlap": 200,
  "contextual_retrieval": true
}

Checklist customize:

Field	Hướng dẫn
project_id	Lowercase + underscore. Ví dụ: namgroup_main, dh_y_duoc, ashico_erp, vipix_multisite. Phải UNIQUE cross 5 project.
display_name	Tên đầy đủ cho dashboard hiển thị, vd "NamGroup - HRM"
corpus_paths	Glob patterns relative project root. Default 3 path cover docs + agent memory + skills. Tăng thêm nếu project có folder docs khác (vd tests/specs/**/*.md).
exclude_paths	KHÔNG embed file tạm/binary/archive
extra_corpus	Memory user-level Claude Code (path absolute). Folder: C:\Users\pqhuy\.claude\projects\<your-project-folder-name>\memory\*.md
share_to_global	CRITICAL DECISION: true = chunks promote-able to shared_global collection (cross-project search visible). false = client confidential, chỉ self-project access. Em main project decide based on data sensitivity (vd DH Y Dược client → false, NamGroup internal HRM → true).
search_scope_default	Default ["self", "shared_global"] - cân bằng project-specific + cross-project pattern reuse
chunk_size / chunk_overlap	Default 1500/200 chars - đã tune cho MD docs Vietnamese. KHÔNG đổi unless project có docs structure khác hẳn.
contextual_retrieval	true - Anthropic Contextual Retrieval prepend "From > :" - +15% recall

Step 2: Run bootstrap

python D:\.claude-rag\bootstrap.py --project <project_id>

Expected output:

[1/4] Scanning corpus... Found N files
[2/4] Chunking + contextual prepend... Total chunks: M
      Estimated tokens: ~XXX,XXX (Voyage free tier: 200M/month)
[3/4] Voyage-4-large embedding + Qdrant upsert + SQLite BM25... Upserted M chunks in T seconds
[4/4] Update registry...
[OK] Bootstrap complete: <project_id> ready (M chunks)

Performance benchmark (SOLUTION_ERP 2026-05-22):

• 126 files → 2,628 chunks → ~484K tokens → 60.9s embed + upsert
• 2nd bootstrap với cache hit: 6.5s (10× speedup)

Step 3: Verify

rag-status   # See new project in [Collections] section
rag-dashboard   # Visual verify via browser

Test query in Claude Code session (project mới):

search_memory("pattern X tôi đã làm chưa")

Should return chunks từ project mới + shared_global (nếu có).

---

§5 6 MCP Tools matrix

Tool	Scope	Use case
search_memory(query, scope, top_k, use_rerank)	self / shared_global / all_projects / default	Tìm pattern, gotcha, narrative trong project hiện tại + shared
cross_project_search(query, top_k)	All projects	"Pattern X tao đã làm ở dự án nào trước chưa?" - explore cross-project knowledge
search_code(query, file_pattern, top_k)	Self only (BM25-heavy)	Tìm exact symbol/function name trong source code
store_memory(content, source_path, tags)	Self	Save pattern on-the-fly cuối session, không cần re-bootstrap
promote_to_shared(chunk_id)	Self → shared_global	Pattern proven cross-project ≥2x use → visible to all projects (v0 stub, defer v1)
list_projects()	All registry	Overview projects + collection chunk counts

Em main project mới brief 4 sub-agent (nếu có setup):

Agent	Skills preload + RAG access
🟦 Investigator	Auto-detect cwd → project_id → mcp__rag-unified__search_memory(scope="self") cho research patterns
🟨 Implementer	Same auto-detect + search_code cho symbol lookup khi cookie-cutter mirror
🟥 Reviewer	Same auto-detect + cross_project_search để verify pattern proven elsewhere trước commit
🟩 CICD Monitor	Same + list_projects cho infra state checks

---

§6 4 Sub-agent setup brief (optional - cho project ≥10K LOC, ≥3 month)

Per memory feedback_multi_agent_setup.md - setup multi-agent CHỈ khi pass 6/6 decision gate. SOLUTION_ERP S20 turn 12 đã match (59 tables + 142 endpoints + 6 skills + 44 gotchas).

Pattern reusable cho project mới:

1. Tạo .claude/agents/ folder + 4 .md files (Investigator + Implementer + Reviewer + CICD Monitor)
2. Tạo .claude/agent-memory/<name>/MEMORY.md seed per agent
3. Copy template từ SOLUTION_ERP .claude/agents/README.md (master coordination guide)
4. Customize project-specific:
   • Skills preload (tùy stack: .NET / React / Python / Go)
   • Domain entities + workflow patterns
   • Live prod URLs + bearer tokens
   • Gotcha catalog reference
5. End-of-session: 4 agent flush MEMORY.md updates → em main synthesize cross-agent learnings → integrate vào memory + session log

Reference SOLUTION_ERP files (paste-friendly templates):

• .claude/agents/README.md - master coordination guide với 6-criteria decision gate
• .claude/agents/investigator.md - frontmatter + system prompt template
• .claude/agents/implementer.md - REFUSE strict 6-criteria
• .claude/agents/reviewer.md - 5-category checklist + Smart Friend guard
• .claude/agents/cicd-monitor.md - 5-stage post-deploy verify

---

§7 Permission + Security

MCP user-level scope (1 lần setup per Windows user)

claude mcp add -s user registers rag-unified ở %USERPROFILE%\.claude.json - persist across ALL Claude Code sessions cho user pqhuy. Bất kỳ project nào pqhuy mở đều có access 6 tools (KHÔNG cần re-register).

VOYAGE_API_KEY scope

[Environment]::SetEnvironmentVariable("VOYAGE_API_KEY", "...", "User") - Windows User registry, persist boot-to-boot. KHÔNG commit vào git. KHÔNG share cross-machine.

share_to_global flag (per-project)

• true → chunks có thể promote vào shared_global collection → cross-project search visible (em main khác có thể thấy)
• false → strict isolated cho project (client confidential, NDA, regulated data)

KIẾN NGHỊ: Em main project mới BẮT BUỘC review sensitivity TRƯỚC khi bootstrap. Vd:

• DH Y Dược (client confidential): share_to_global=false + exclude paths chứa client name
• NamGroup (internal HRM): share_to_global=true ok
• Vipix multisite (public docs): share_to_global=true

---

§8 Workflow daily — Em main project mới

# Morning - mở session Claude Code project mới
rag-status         # Check infra OK
rag-dashboard      # Visual sanity check

# Trong session - search context
search_memory("workflow X")           # MCP tool call trong session
cross_project_search("pattern Y")     # Find proven pattern elsewhere

# End of session - save new pattern
store_memory("Pattern Z chốt 2026-XX-XX...", tags=["pattern", "<topic>"])

# Periodic - re-bootstrap khi docs thay đổi nhiều
python D:\.claude-rag\bootstrap.py --project <project_id> --re-embed

Khi nào re-bootstrap?

• Sau session lớn thêm > 20 file MD docs mới
• Sau drastic refactor MD structure (rename folders, restructure)
• Monthly cadence per feedback_md_compact_narrative.md audit + curate cycle

Khi nào KHÔNG re-bootstrap (cache hit)?

• File MD chỉ patched < 30% content - bootstrap re-embed sẽ skip chunks unchanged (SHA256 cache hit)
• Session khác không touch corpus paths

---

§9 Troubleshooting

Q: rag-status báo Qdrant DOWN nhưng anh đã rag-start?

A: Check 30s timeout - Qdrant cần ~10s warmup. Retry sau:

Start-Sleep -Seconds 10
Invoke-RestMethod -Uri "http://localhost:6333/healthz" -TimeoutSec 10

Nếu vẫn DOWN, check logs:

Get-Content "D:\.claude-rag\logs\qdrant-$(Get-Date -Format 'yyyyMMdd').log" -Tail 30

Q: MCP server rag-unified NOT CONNECTED?

A: 3 nguyên nhân thường gặp:

1. VOYAGE_API_KEY chưa load vào Claude Code env → Restart Claude Code completely (close all windows)
2. Python deps thiếu → pip install fastmcp voyageai qdrant-client watchdog python-dotenv
3. MCP đăng ký sai path → Check claude mcp list - phải có dòng rag-unified: python D:\.claude-rag\server.py - [OK] Connected

Q: bootstrap.py báo Voyage rate limit hoặc 429?

A: Free tier 200M tokens/month chia equally across requests. Nếu hit limit:

• Wait 1 phút retry (Voyage rate limit window ~60s)
• Batch nhỏ hơn: --batch-size 32 thay vì default 128
• Check Voyage dashboard: https://dash.voyageai.com/

Q: SQLite FTS5 query error no such column: in?

A: Gotcha #48 cousin - reserved keyword. _sanitize_fts5_query() strip non-alphanumeric. Nếu vẫn fail, simplify query (remove -, :, ())

Q: Qdrant batch upsert WinError 10053 "connection aborted"?

A: Batch quá lớn. lib/retrieval.py:UPSERT_BATCH = 64 đã limit. Nếu vẫn fail, giảm xuống 32.

Q: HuggingFace symlinks warning Windows?

A: Non-critical (cache works degraded efficiency). Suppress: $env:HF_HUB_DISABLE_SYMLINKS_WARNING=1

---

§10 Tunings (advanced)

Tăng recall (sacrifice cost)

{
  "chunk_size": 1000,        // smaller chunks = more granular match
  "chunk_overlap": 300,      // higher overlap = catch boundary patterns
  "use_rerank_default": true // rerank-2.5 = +20-30% recall vs vector-only
}

Cost trade-off: smaller chunks = N% more tokens to embed + rerank.

Giảm cost (sacrifice recall)

{
  "chunk_size": 2500,
  "chunk_overlap": 100,
  "use_rerank_default": false  // rely on vector + BM25 only
}

Saving: ~30% Voyage tokens. Recall drop ~10-15%.

BM25 weight tuning

Default RRF k=60 (Reciprocal Rank Fusion). Tăng k = giảm BM25 dominance, tăng vector. Em main project mới KHÔNG tune trừ khi có golden benchmark dataset.

---

§11 Best practices cross-project

1. store_memory defensive - cuối session save new pattern proven, không đợi monthly bootstrap
2. Cross-project search BEFORE design - cross_project_search("pattern X") check trước khi implement mới
3. Sensitivity audit per session - khi push file mới có client info → confirm share_to_global flag đúng
4. Dashboard daily - mở rag-dashboard mỗi sáng để verify infra healthy + collection counts không drop bất thường
5. Document .claude/rag.json decisions - comment trong file lý do chốt sensitivity flag, exclude paths
6. Cron monthly audit cadence - per rule §6.4 SOLUTION_ERP, project mới adopt monthly cron skill+doc audit. Drift trigger sớm nếu +5 gotcha mới

---

§12 Status Monitoring + Manual Control (Option 4b NSSM Windows Service ⭐ UPGRADED S27)

Upgrade S27: Qdrant chạy as Windows Service (NSSM)

Phiên bản S26 dùng Option 4a (manual PS scripts only). S27 upgrade lên Option 4b với NSSM Windows Service:

	Option 4a (S26)	Option 4b NSSM (S27 RECOMMEND)
Auto-start timing	Sau anh login Windows (Startup folder)	✅ Boot-time (trước login)
Auto-restart on crash	❌ Stay crashed	✅ Auto-respawn 3s delay
Survive logout/login	❌ Stop khi logout	✅ Service runs background
Control	rag-start/stop/status/dashboard	Same + Get-Service Qdrant native
Setup once	~30 phút	~35 phút (+ install NSSM elevated)
OOM recovery (vd 8.4MB OOM em pioneer S27)	Manual rag-restart	✅ Auto-respawn

Setup elevated PowerShell (1 lần duy nhất):

# 1. Download NSSM 2.24 (~3 MB, may retry nssm.cc 503 transient)
$nssmDir = "D:\.claude-rag\nssm"
Invoke-WebRequest -Uri "https://nssm.cc/release/nssm-2.24.zip" -OutFile "$nssmDir\nssm-2.24.zip"
Expand-Archive "$nssmDir\nssm-2.24.zip" $nssmDir -Force
Copy-Item "$nssmDir\nssm-2.24\win64\nssm.exe" "$nssmDir\nssm.exe"

# 2. Run install script (em pioneer write D:\.claude-rag\scripts\install-service.ps1)
& "D:\.claude-rag\scripts\install-service.ps1"

Script tự động: stop manual qdrant + register service + AppDirectory + log paths + Start SERVICE_AUTO_START + AppExit Default Restart 3s delay + DisplayName "Qdrant Vector DB (RAG Unified)" + Description + start service + health verify.

Verify post-install:

Get-Service Qdrant   # Should show Status: Running, StartType: Automatic

Troubleshooting nếu start fail (WAL lock conflict):

# Pre-existing qdrant.exe manual holding WAL → kill + retry
& "D:\.claude-rag\scripts\fix-service-start.ps1"  # elevated

Aliases trong $PROFILE (~30 phút first-time setup)

function rag-start     { & "D:\.claude-rag\scripts\start.ps1" }     # Start Qdrant background
function rag-stop      { & "D:\.claude-rag\scripts\stop.ps1" }      # Graceful stop
function rag-status    { & "D:\.claude-rag\scripts\status.ps1" }    # Full status report 6 section
function rag-dashboard { & "D:\.claude-rag\scripts\dashboard.ps1" } # Custom HTML dashboard + open browser
function rag-restart   { & "D:\.claude-rag\scripts\stop.ps1"; Start-Sleep 2; & "D:\.claude-rag\scripts\start.ps1" }
function rag-boot      { & "D:\.claude-rag\scripts\boot.ps1" }      # Manual trigger boot sequence

6 PS scripts khả dụng (em pioneer SOLUTION_ERP đã build — Service mode S27)

Script	Mục đích	Output
start.ps1	Start-Service Qdrant (needs Admin if stopped)	Service status + PID + RAM
stop.ps1	Stop-Service Qdrant -Force (needs Admin)	Status verification
status.ps1	Full status: Service + Process + MCP + Voyage + Collections + Disk + Agent MEMORY	Terminal 6 section colored (no Admin)
dashboard.ps1	Generate custom HTML dashboard (STATIC snapshot) + open browser	D:\.claude-rag\dashboard.html
boot.ps1	Post-login: verify service Running + regen Dashboard + open browser	Used by Startup folder shortcut
install-service.ps1	NSSM register Qdrant as Windows Service (1 lần)	Service Running + Auto-start verified
fix-service-start.ps1	Recover service after WAL lock conflict (rare)	Service Running verified

Custom MCP Dashboard

URL: file:///D:/.claude-rag/dashboard.html (auto-generated, auto-open by rag-dashboard command)

⚠️ IMPORTANT (S27 fix): Dashboard HTML là STATIC SNAPSHOT tại thời điểm anh chạy rag-dashboard. KHÔNG auto-poll Qdrant API live — browser meta refresh chỉ reload HTML cached, KHÔNG re-run PS script. Muốn data live → mở Qdrant Native Dashboard (http://localhost:6333/dashboard) fetch API real-time. Custom Dashboard chỉ dùng cho ecosystem overview (Service+MCP+Voyage+Agent MEMORY combined panel mà Qdrant native không có).

Panels:

1. Qdrant Vector DB - PID/version/uptime/RAM/storage + link Qdrant native dashboard
2. MCP Server (FastMCP) - Registration status + 6 tools matrix
3. Collections - List all proj_* + shared_global chunk counts
4. Voyage AI - API key + scope + embedding/rerank model + free tier
5. System - Disk usage + Python version + paths
6. Agent MEMORY - 4 agent MEMORY.md sizes (SOLUTION_ERP) with curate threshold warnings
7. Recent Qdrant Logs - last 10 lines

Auto-refresh: 60s via <meta http-equiv="refresh" content="60">. Manual refresh via "Refresh Now" button.

Customization cho project mới (optional):

• Edit dashboard.ps1 Section 6 $memDir path → point to project mới .claude/agent-memory/
• Add custom panels (vd Section "Recent commits" via git log --oneline -10)
• Color palette: change #f59e0b (orange) → project brand color

Auto-start on Windows boot (S27 — 2-layer)

Layer 1 — NSSM Windows Service (auto-start Qdrant):

• Service Qdrant StartType=Automatic → boot-time auto-start (trước login)
• Auto-restart on crash (AppExit Default Restart 3s delay)
• Survive logout/login

Layer 2 — Startup folder shortcut (auto-open Dashboard sau anh login):

• Path: %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\rag-boot.lnk
• Target: powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "D:\.claude-rag\scripts\boot.ps1"
• boot.ps1 S27 updated: verify service Running (KHÔNG start lại) + regen Dashboard + open browser
• Disable: Delete .lnk file (Qdrant vẫn auto-start by service)

Qdrant Native Dashboard (built-in FREE — Web UI v0.2.12)

URL: http://localhost:6333/dashboard (browse Qdrant collections, query playground, metrics)

⚠️ Yêu cầu trước: Em pioneer SOLUTION_ERP đã download Web UI static files vào D:\.claude-rag\qdrant-bin\static\ (S27 hotfix - Qdrant Windows binary zip không bundle Web UI). Nếu native dashboard 404, xem Gotcha #4 §A2 để re-download.

Khác biệt Native Qdrant vs Custom MCP Dashboard:

	Qdrant Native	Custom MCP (em pioneer build)
URL	http://localhost:6333/dashboard	file:///D:/.claude-rag/dashboard.html
Mục đích	Browse collections + query playground + metrics	Status overview RAG ecosystem
Panels	Collections, Console, Cluster, Snapshots	Qdrant+MCP+Voyage+Agent MEMORY+Logs
Auto-refresh	Yes (Qdrant native polling)	60s meta refresh
Khi dùng	Khi cần inspect collection data, run test query	Khi cần check overall health + 4 agent MEMORY sizes + Voyage token usage

Bookmark cả 2 — complementary, không thay thế nhau.

---

§13 Approach B Distributed Workflow (Em main pioneer KHÔNG làm hộ)

Responsibility split

Em main pioneer (SOLUTION_ERP):

• ✅ Build infrastructure D:\.claude-rag\ (Qdrant binary + FastMCP server + lib + scripts)
• ✅ Build 4 PS scripts (start/stop/status/dashboard) + boot.ps1
• ✅ Custom MCP Dashboard HTML generator
• ✅ $PROFILE aliases setup
• ✅ Startup folder shortcut auto-boot
• ✅ Bootstrap SOLUTION_ERP corpus (proj_solution_erp)
• ✅ Xuất guide này (file rag-onboarding-guide.md)
• ❌ KHÔNG bootstrap data cho project Y/Z khác - đó là việc của em main project đó

Em main project Y/Z (NamGroup / DH Y Dược / Ashico / Vipix / khác — khi anh pqhuy mở Claude Code project đó):

1. Đọc guide này (5 phút) - paste vào docs/guides/rag-onboarding-guide.md của project nếu chưa có
2. Tự tạo .claude/rag.json - em main project hiểu CONTEXT cụ thể (project_id, corpus paths, sensitivity flag)
3. Tự run bootstrap.py ~5 phút embed
4. Test query verify hoạt động
5. Brief 4 sub-agent của project đó qua MEMORY.md (nếu có setup multi-agent)

Pattern reusable cross-project

Setup-once, scale-distributed pattern cho bất kỳ multi-project shared infrastructure (RAG + MCP + future tools):

1. Em main project pioneer (P1 = SOLUTION_ERP) build infra + xuất onboarding MD
2. P1 KHÔNG executable cho P2/P3/.../Pn
3. Em main P2/P3/.../Pn tự đọc MD + apply khi anh pqhuy mở session project đó
4. Cumulative knowledge graph natural - mỗi em main own context, share qua shared_global collection

Anti-patterns avoided

• ❌ Em main project X bootstrap data cho project Y/Z - vi phạm Cognition boundary
• ❌ Hardcode .claude/rag.json cho project khác trong em main X - em không biết sensitivity
• ❌ Task Scheduler auto-start dù không cần (RAM cost + lose control - anh chọn manual scripts thay)
• ❌ Embed config decisions qua chat conversation - KHÔNG vào RAG, mất khi session crash

---

§A3 Context loading Hybrid pattern — em main workflow optimization ⭐ S27 NEW

Audience: Em main Opus project Y/Z (NamGroup / DH Y Dược / Ashico / Vipix / khác). Áp dụng cho mỗi session daily ops. Origin: Memory user-level feedback_rag_hybrid_pattern.md (Cách A defensive). Bài học S27 SOLUTION_ERP em pioneer.

§A3.1 — Why Hybrid (Cách A defensive vs Cách B aggressive)

Em main Opus 4.7 có 1M token context window (qua model: inherit từ parent). KHÔNG load hết tất cả MD vào blanket — wasteful + context rot.

Cách	Blanket size	RAG usage	Decision quality	UX latency	Khi dùng
Cách A defensive (CHỌN)	~120K	Supplement retrieve on-demand	90% (control flow strong)	Smooth	Project MD > 1M tokens cumulative
Cách B aggressive	Cắt 60-70%	Cascade retrieve mỗi task	75-80% (fragmented)	+1-2s mỗi state question	KHÔNG khuyến nghị
Skip RAG	Blanket all	Zero	Best decision quality	Best UX	Project MD < 200K tokens

Decision gate cho project mới:

• MD < 200K tokens → Skip RAG entirely
• MD 200K-1M → Lazy blanket sufficient, RAG nice-to-have
• MD > 1M → RAG MANDATORY (vượt context window blanket)

§A3.2 — Layer 1: Blanket auto-load (mỗi session start)

Auto-injected vào em main session khi anh mở Claude Code project:

Component	Estimate KB	Always loaded?
System prompt + tool definitions	15-20	✅ Always
CLAUDE.md (project root pointer)	1-3	✅ Always
docs/CLAUDE.md (full project context)	8-15	✅ Always
docs/STATUS.md Recently Done snapshot	30-60 (oversize warn)	✅ Always (per CLAUDE.md priority)
docs/HANDOFF.md brief 5 phút	80-90 (oversize warn)	✅ Always
User memory MEMORY.md index	3-5	✅ Always
6 skill descriptions	3	✅ Always
4 sub-agent definitions + first 200 lines MEMORY each	50-80	✅ Always (post CLI restart pickup model:inherit)
Tổng blanket estimate	~200-280 KB ≈ 50-70K tokens

KHÔNG auto-load (cần RAG retrieve hoặc Read direct):

• Session logs cũ docs/changelog/sessions/*.md (~30+ files cumulative)
• Skill SKILL.md full content (chỉ description in blanket)
• Memory user-level full content (chỉ index)
• Source code BE/FE
• Archive folders .claude/agent-memory/*/archive/*
• Migration scripts old + DbInitializer

§A3.3 — Layer 2: RAG retrieve decision tree

Em main cần thông tin → CHỌN tool:

├── Cần PATTERN proven từ session cũ / cross-project?
│     → mcp__rag-unified__search_memory("pattern X", scope="default")
│     Vd: "per-NV admin opt-in flag pattern", "FE merge synthetic audit"
│
├── Đang implement feature mới — kiểm tra đã làm ở project nào trước chưa?
│     → mcp__rag-unified__cross_project_search("feature Y")
│     Vd: "audit recovery pattern", "Workflow N-stage state machine"
│
├── Cần lookup EXACT function/class/method trong source code?
│     → mcp__rag-unified__search_code("ApproveV2Async signature")
│     BM25-heavy, exact symbol match. NOT cho semantic question.
│
├── Cần GOTCHA cụ thể đã gặp?
│     → search_memory("gotcha #48 SQLite tie-break") OR Read docs/gotchas.md direct
│     Decision: < 5 gotcha lookup/session → Read direct. > 5 → search_memory.
│
├── Cần SESSION LOG cụ thể S22-S26 history?
│     → search_memory("S23 Plan K F2 refactor") thay vì Read full session log 15-25KB
│     Saves 80-90% tokens per lookup
│
├── End-of-session phát hiện NEW pattern reusable?
│     → mcp__rag-unified__store_memory(content, tags=["pattern", "<topic>"])
│     KHÔNG đợi monthly bootstrap — instant index
│
├── Pattern proven cross-project ≥ 2× use, muốn share?
│     → mcp__rag-unified__promote_to_shared(chunk_id)
│     (v0 stub, defer v1)
│
└── Daily ops, không cần cụ thể?
      → Skip RAG, dùng blanket auto-load + Read on-demand specific files

§A3.4 — Token budget guidance per session

Target utilization Opus 4.7 1M context:

% Used	State	Action
0-30% (~0-300K)	🟢 Healthy	Continue normal work
30-50% (~300-500K)	🟢 Heavy session	OK, monitor sub-agent spawn cost
50-70% (~500-700K)	🟡 Warning	Consider end-of-session soon, save patterns via store_memory
70-85% (~700-850K)	🟠 Approach limit	End session ASAP, finalize HANDOFF, S+1 fresh
> 85% (~850K+)	🔴 Critical	Response lag + repetition. End immediately.

Em main session activity sample S27 (~5h heavy):

• Read full 4 MEMORY (180KB) + STATUS (60KB) + HANDOFF (90KB) + multiple skill files + session logs S25-S26
• Write 7 PS scripts + dashboard HTML + onboarding guide (440 lines) + 4 archive files + memory NEW
• Estimate context used: ~400-560K (40-55% utilization) — Warning state
• Pattern: Heavy session ~5-6h → end session, S+1 fresh start

Anti-pattern wasteful:

• ❌ Read entire STATUS.md (60KB) cho 1 question — use search_memory instead
• ❌ Read tất cả session log S20-S26 (~30 files ~300KB) — use search_memory specific term
• ❌ Read entire 4 sub-agent MEMORY (180KB) mỗi session — auto-injected first 200 lines, đủ; full Read only when explicit reference
• ❌ Search RAG với empty/vague query ("test", "data") — return noise
• ❌ Read full source code BE (3K LOC) cho 1 line lookup — use search_code BM25

§A3.5 — 6 MCP tools examples concrete (em main daily)

1. search_memory(query, scope, top_k, use_rerank) — Most common

# Vietnamese OK
search_memory("workflow approve V2 actor scope check")

# English OK
search_memory("multi-agent setup pitfall model inherit")

# Specific gotcha lookup (skip Read gotchas.md full)
search_memory("gotcha 48 SQLite tie-break multi Changelog")

# Cross-project default (self + shared_global)
search_memory("Per-NV admin opt-in flag pattern", scope="default")

# Self-only (project-specific narrow)
search_memory("Plan AG tree view UI", scope="self")

2. cross_project_search(query, top_k) — Khi explore broader

# "Pattern X tao đã làm ở dự án nào trước chưa?"
cross_project_search("audit recovery synthetic rows FE merge")
cross_project_search("EF migration BACKFILL reorder discipline")
cross_project_search("Custom Dashboard PowerShell HTML generator")

3. search_code(query, file_pattern, top_k) — BM25 exact match

# Exact function name
search_code("ApproveV2Async EnsureCanRejectV2Async")

# Specific TS prop
search_code("AllowApproverEditBudget per-Level slot", file_pattern="**/*.cs")

# Migration name lookup
search_code("Mig 29 RefactorAdvancedOptionsToPerLevelAndDrafterUser")

4. store_memory(content, source_path, tags) — End-of-session NEW pattern

store_memory(
    content="""
    Pattern S27 NEW: NSSM Windows Service for Qdrant auto-start.
    - 7 PS scripts (install/fix/start/stop/status/dashboard/boot)
    - Service mode auto-restart on crash + survive logout
    - Gotcha: WAL lock conflict if manual qdrant.exe running → kill first
    Reusable cross-project bất kỳ multi-project shared infrastructure.
    """,
    source_path="manual/S27-nssm-pattern",
    tags=["nssm", "windows-service", "qdrant", "pattern"]
)

5. promote_to_shared(chunk_id) — Cross-project pattern proven

# v0 stub - defer v1. For now manually duplicate-index to shared via store_memory
# (Pattern proven ≥ 2× use → manual cross-share)

6. list_projects() — Registry overview (rare daily, common monthly audit)

# Check infra health
list_projects()
# Returns: [{project_id, collection, chunk_count, last_indexed_at}, ...]

§A3.6 — Best practices em main daily workflow

Morning session start (5 phút):

rag-status                    # Check Qdrant Service + collection counts
rag-dashboard                 # Visual sanity (snapshot - mỗi sáng OK fresh)

• Spawn test sub-agent IMMEDIATELY:

Agent(subagent_type="investigator", prompt="Test reply 1 sentence")

→ Verify registry load. Nếu fail → check feedback_subagent_setup_pitfalls.md §4 diagnose.

Trong session daily ops:

• Default tool: search_memory thay vì Read MD direct (saves 80-90% tokens per lookup)
• Read direct CHỈ KHI cần edit file đó hoặc cần see full file structure
• cross_project_search khi design feature mới — check proven elsewhere
• search_code khi need exact symbol/function lookup

End of session save NEW patterns:

# 1. store_memory cho mỗi pattern proven phát hiện trong session
store_memory(content="Pattern Z chốt YYYY-MM-DD: ...", tags=[...])

# 2. Update HANDOFF.md với S+1 priority HIGH
# 3. Commit + push (nếu có code changes)

Monthly audit cadence (re-bootstrap if drift):

python D:\.claude-rag\bootstrap.py --project <project_id>          # incremental cache hit
python D:\.claude-rag\bootstrap.py --project <project_id> --force-reindex   # clean slate

Trigger re-bootstrap khi:

• +20 file MD docs mới sau session lớn
• Drastic refactor MD structure (rename folders)
• Monthly audit per rule §6.4 cadence
• Sau khi clean curate 4 sub-agent MEMORY

§A3.7 — Anti-patterns cross-project (đừng làm)

1. ❌ Solo cả session vì assume agents chưa load — VIPIX + SOLUTION_ERP S27 lesson. ALWAYS spawn test agent first.
2. ❌ Read full session log cũ (15-25KB each) — use search_memory("S## Plan X") instead, saves 80-90% tokens
3. ❌ Read full 4 MEMORY.md mỗi session — auto-injected first 200 lines blanket đủ; full Read only when explicit pattern reference
4. ❌ search_memory với query vague ("test", "data", "fix") — return noise. Specific terms: "gotcha #48 SQLite tie-break", "Plan AG tree view".
5. ❌ Skip store_memory end-of-session — pattern mất khi session crash. Save instant, không đợi monthly bootstrap.
6. ❌ Em main solo task qualify Implementer Case 1/2 — vi phạm directive S22 chốt BẮT BUỘC delegate. Spawn Implementer cho cookie-cutter mechanical (≥5 file independent + deterministic spec).
7. ❌ Heavy session > 6h không end — context rot risk. End session + S+1 fresh.

§A3.8 — Context monitoring + when to end session

Em main không có exact token counter built-in (Anthropic Claude Code CLI có thể có /context hoặc status bar — em check tùy version).

Estimate heuristics:

• Số lượng files Read full: > 10 large files (>30KB each) → likely > 40% context
• Session duration: > 5h heavy work → likely > 50% context
• Sub-agent spawn count: 4 agents × 100K each = ~400K used by sub-agent overhead alone
• Tool calls cumulative: > 100 tool calls likely > 50% context

Signs of context full (end session ASAP):

• 🚨 Response lag noticeable (longer wait)
• 🚨 Em main lặp lại logic đã reasoning
• 🚨 Em main miss reference to earlier session context
• 🚨 Sub-agent spawn returns wrong/incomplete results

End session protocol:

1. store_memory mọi NEW pattern phát hiện trong session
2. Update STATUS.md Recently Done
3. Update HANDOFF.md với S+1 priority HIGH list
4. Write docs/changelog/sessions/YYYY-MM-DD-S##-<topic>.md
5. Commit + push (per project workflow)
6. Anh restart Claude Code CLI cho S+1 fresh

---

§A2 Cấu trúc chuẩn em main pioneer (SOLUTION_ERP) đã setup

Notes integrated từ Plan A.2 (skip bootstrap hộ, but provide structure documentation for 4 em main khác self-setup).

File tree D:\.claude-rag\ (em pioneer SOLUTION_ERP build)

D:\.claude-rag\
├── bootstrap.py              (150 LOC - CLI bootstrap project corpus)
├── server.py                 (210 LOC - FastMCP entry, 6 tool handlers)
├── README.md                 (project README)
├── dashboard.html            (generated by dashboard.ps1 - DO NOT edit manually)
├── lib/
│   ├── __init__.py
│   ├── projects.py           (140 LOC - auto-detect cwd, registry tracking)
│   ├── chunking.py           (120 LOC - Markdown chunking + Anthropic Contextual Retrieval prepend)
│   ├── embed.py              (140 LOC - Voyage AI wrapper, retry exponential backoff, SHA256 cache)
│   ├── retrieval.py          (230 LOC - 3-layer pipeline: Vector + BM25 + RRF + Voyage rerank-2.5)
│   └── watcher.py            (100 LOC - Watchdog file watcher, debounce 2s — defer v1 wire)
├── scripts/
│   ├── start.ps1             (Qdrant background hidden + health check, ASCII-only)
│   ├── stop.ps1              (Graceful stop + verify, ASCII-only)
│   ├── status.ps1            (6-section full report, ASCII-only)
│   ├── dashboard.ps1         (Generate custom HTML + open browser, ASCII-only)
│   └── boot.ps1              (Auto-boot sequence: start + dashboard, used by Startup shortcut)
├── qdrant-bin/
│   ├── qdrant.exe            (88 MB v1.18.0 Windows native binary)
│   ├── qdrant-v1.18.0.zip    (download archive 28.3 MB)
│   ├── .qdrant-initialized   (marker file)
│   └── config/               (Qdrant config folder, currently empty - uses defaults)
├── data/
│   └── qdrant-storage/       (Qdrant data dir, ~85+ MB per project bootstrap)
├── logs/
│   └── qdrant-YYYYMMDD.log   (rotated daily)
└── __pycache__/              (Python bytecode cache)

8-step Bootstrap checklist cho em main project mới

[ ] 1. Verify infra global ready: rag-status → 3 OK (Qdrant + MCP + Voyage)
[ ] 2. Decide project_id (lowercase + underscore, UNIQUE cross 5 project)
[ ] 3. Decide sensitivity: share_to_global=true/false (client confidential check)
[ ] 4. Identify corpus_paths (default 3 + extra docs folders project-specific)
[ ] 5. Identify exclude_paths (binary, node_modules, archive, secrets)
[ ] 6. Identify extra_corpus (memory user-level path cho project Claude Code folder)
[ ] 7. Write .claude/rag.json from template §4
[ ] 8. Run: python D:\.claude-rag\bootstrap.py --project <project_id>
[ ] 9. Verify: rag-status (see new project in [Collections] section)
[ ] 10. Test query in Claude Code session: search_memory("test")

Files em pioneer ĐÃ build (KHÔNG edit cross-project)

File	Content	Owner
D:\.claude-rag\server.py	FastMCP entry + 6 tool handlers	Em pioneer SOLUTION_ERP (do NOT modify per-project)
D:\.claude-rag\lib\*.py	Shared library	Em pioneer (modify only via PR to em pioneer project)
D:\.claude-rag\bootstrap.py	CLI bootstrap script	Em pioneer
D:\.claude-rag\scripts\*.ps1	5 PowerShell scripts	Em pioneer (em main project mới có thể customize project-specific aliases per §12)
D:\.claude-rag\qdrant-bin\	Qdrant binary	Shared (Windows native v1.18.0, no Docker)
D:\.claude-rag\data\	Qdrant storage	Shared (all collections live here)
<project>\.claude\rag.json	Per-project config	Em main project đó (own this file fully)
dashboard.html	Auto-generated	dashboard.ps1 generates, DO NOT edit manually

Cấu trúc stack chốt

Component	Tool/Version	Note
Embedding	Voyage-4-large (1024-dim)	200M tokens/month free tier
Reranker	Voyage rerank-2.5	$0.05/1K query, 20× cheaper than Cohere
Vector DB	Qdrant v1.18.0 Windows native binary	No Docker, 28.3 MB binary
BM25	SQLite FTS5 (unicode61 + remove_diacritics 2)	Built-in to SQLite, no Postgres
Fusion	RRF k=60 (Reciprocal Rank Fusion)	Industry standard
MCP framework	FastMCP 3.3.1 stdio	Anthropic official SDK
Contextual Retrieval	"From <doc_title> > <heading_path>:" prepend	Anthropic blog Sept 2024 pattern
Distribution	User-level Global MCP (Approach A — 1 dev N project localhost)	NO team VPS pattern

4 Gotcha discoveries S26-S27 (cho project khác tránh)

1. Qdrant Windows binary chính thức tồn tại - GitHub release qdrant-x86_64-pc-windows-msvc.zip 28.3 MB. No Docker overhead.
2. claude mcp add cần -- separator terminate variadic -e flag: claude mcp add -s user -e "VOYAGE_API_KEY=$VK" -- rag-unified python "D:\.claude-rag\server.py". Em pioneer trial 5 lần fail trước khi tìm ra fix.
3. Qdrant batch upsert WinError 10053 với batch > 64 chunks → fix bằng UPSERT_BATCH = 64 trong lib/retrieval.py.
4. Qdrant Windows binary KHÔNG bundled Web UI static files (S27 discovery 2026-05-22) — qdrant.exe log warn Static content folder for Web UI './static' does not exist + http://localhost:6333/dashboard returns 404. Fix: Download separate dist-qdrant.zip từ https://github.com/qdrant/qdrant-web-ui/releases/latest (6.59 MB v0.2.12) + extract vào D:\.claude-rag\qdrant-bin\static\ (flatten dist/ subfolder up to static/ root level so index.html ở static\index.html). Restart Qdrant → native dashboard work HTTP 200 "UI | Qdrant".

   $url = "https://github.com/qdrant/qdrant-web-ui/releases/download/v0.2.12/dist-qdrant.zip"
   Invoke-WebRequest -Uri $url -OutFile "D:\.claude-rag\qdrant-bin\dist-qdrant.zip"
   Expand-Archive -Path "D:\.claude-rag\qdrant-bin\dist-qdrant.zip" -DestinationPath "D:\.claude-rag\qdrant-bin\static" -Force
   # Flatten dist/ up to static/ root:
   Get-ChildItem "D:\.claude-rag\qdrant-bin\static\dist" | Move-Item -Destination "D:\.claude-rag\qdrant-bin\static" -Force
   Remove-Item "D:\.claude-rag\qdrant-bin\static\dist" -Force
   rag-restart
   

PowerShell gotcha (per memory feedback_node_cicd.md cousin)

• ASCII-only trong .ps1 source - PowerShell 5.1 fragile với UTF-8 BOM. Em pioneer trial fail 2x với ✓ → âœ" mangling. Replace ALL unicode trong code source bằng ASCII ([OK], [FAIL], ->, *, !). HTML output unicode OK (file save UTF-8 + browser charset declare).
• Bash shell KHÔNG inherit User-scope env var từ PowerShell parent - workaround: VK=$(powershell -NoProfile -Command "...") mỗi Bash command + export VOYAGE_API_KEY="$VK"

---

Cross-ref

• feedback_rag_distributed_ownership.md (memory user-level) - Decision Approach B + Option 4a rationale full
• feedback_rag_hybrid_pattern.md (memory user-level) - Stack architecture chốt S26 + 7 gotcha discoveries
• feedback_multi_agent_setup.md (memory user-level) - 4 sub-agent decision gate
• feedback_md_compact_narrative.md (memory user-level) - §6.5 KEEP narrative rule cho bootstrap chunking strategy
• .claude/agents/README.md (SOLUTION_ERP) - master coordination guide template cho project mới adopt
• Anthropic Contextual Retrieval - https://www.anthropic.com/news/contextual-retrieval
• FastMCP docs - https://fastmcp.com
• Qdrant Windows release - https://github.com/qdrant/qdrant/releases

---

Changelog

• 2026-05-22 v1.0 chốt S27 em main SOLUTION_ERP + bro pqhuy. Initial release. 13 sections + §A2 cấu trúc chuẩn em pioneer (replace Plan A.2 skip bootstrap hộ).
• Future versions update khi 4 em main project khác feedback usage real.