@relipa/ai-flow-kit 0.1.7 → 0.1.8

package/docs/common/Memory-Architecture-v1.0.md

@@ -0,0 +1,664 @@
+# [AI Flow Kit] Memory Architecture — v1.0
+
+> **Đối tượng:** AI Testing Team · TechLead · PM · mọi role liên quan (đọc được, không cần biết kỹ thuật)
+> **Trạng thái:** Draft v1.1 — đã review & chốt quyết định ngày 2026-07-16 (mem-id theo folder functionId, scorer chấm trên tags, hit count qua telemetry local, pending dùng được trên máy người tạo, recall theo workflow, offline fallback)
+> **Ngày:** 2026-07-09 · Cập nhật: 2026-07-16
+
+---
+
+## 1. Mục Tiêu
+
+Triển khai memory cho các dự án dùng AI Flow Kit, sao cho:
+
+- Trong quá trình làm task, AI **tích lũy tri thức qua hội thoại** giữa AI và con người.
+- AI **tự tổng hợp** và ngày càng hiểu dự án hơn, **không lặp lại lỗi cũ**.
+- Các task về sau **kế thừa** những điểm hay từ lịch sử task trước — con người không phải mô tả lại từ đầu mỗi lần làm task mới.
+- Memory được **đồng bộ giữa các role**: AI, DEV, BA, QA, PM, TL (và Comtor nếu dự án có).
+
+---
+
+## 2. Đánh Giá Hiện Trạng
+
+Kết quả rà soát toàn bộ repo (kit chính, `custom/`, `upstream/`, `everything-claude-code/`, `scripts/`, hooks): kit hiện có 3 tầng "memory" khác nhau, nhưng **không tầng nào là học tập tích lũy đúng nghĩa**.
+
+### 2.1 Những gì đang HOẠT ĐỘNG trong project được deploy (`ak init`)
+
+| Cơ chế | Vị trí | Bản chất |
+|---|---|---|
+| Ticket context carryover | `.aiflow/context/current.json` → inject bởi `scripts/hooks/session-start.js` | Nhớ **ticket đang làm**, không phải tri thức |
+| Task/Gate resumption | `.aiflow/tasks/<id>/task-state.json` | Nhớ **đang ở Gate mấy** để resume, không học được gì |
+| Token checkpoints + telemetry | `.aiflow/tasks/<id>/checkpoints.json`, session-stop hook | Analytics, không phải knowledge |
+
+### 2.2 Những gì CÓ CODE nhưng đang "chết"
+
+- **`aiflow memory save/get/search`** (`scripts/memory.js`) — kho JSON tại `.aiflow/memory/`, hoàn toàn thủ công. Quan trọng hơn: hàm `loadRelevantMemories` / `auto-load` (`memory.js:135`) là **dead code — không có hook nào gọi**. Kể cả team có save memory, AI cũng không bao giờ tự đọc lại.
+- **AK-Docs** — lưu tài liệu output từng Gate rất tốt (traceability), nhưng là *document storage*: AI không tự tổng hợp thành tri thức và không tự recall khi làm task mới.
+
+### 2.3 Những gì CÓ SẴN trong repo nhưng CHƯA được cài vào project
+
+Toàn bộ phần "học tập" thực sự nằm trong thư mục vendor `everything-claude-code/` (ECC) và **không được `ak init` copy vào project nào**:
+
+| Tài sản ECC | Chức năng |
+|---|---|
+| `skills/continuous-learning-v2/` | Học "instinct" có confidence score (0.3–0.9), observe qua PreToolUse/PostToolUse hooks |
+| `hooks/memory-persistence/` | Auto-save trước khi compact (PreCompact), auto-load khi SessionStart |
+| `skills/knowledge-ops/` | Kiến trúc knowledge base nhiều tầng |
+| `/learn`, `/learn-eval`, `/evolve` commands | Extract pattern giữa session, quality gate, cluster instinct thành skill |
+
+> Khớp với đánh giá trong `upgrade-plan/everything-claude-code-analysis.md`: 2 nhóm "Quản lý memory" và "Learn experience" đã được flag **CRITICAL** nhưng chưa triển khai.
+
+### 2.4 Đối chiếu với mục tiêu
+
+| Mục tiêu | Hiện trạng |
+|---|---|
+| AI tích lũy tri thức qua hội thoại người–AI | ❌ Không có cơ chế extract tri thức từ conversation |
+| AI tự tổng hợp, ngày càng hiểu dự án hơn | ❌ Không có consolidation/synthesis |
+| Không lặp lại lỗi cũ | ❌ Không có lessons-learned capture + recall |
+| Task sau kế thừa task trước | ⚠️ Chỉ ở mức tài liệu AK-Docs (AI phải được bảo mới đọc) và resume gate của *cùng một* task |
+| Đồng bộ memory giữa các role | ❌ Chưa có; `.aiflow/memory/` nằm local trong repo source của Dev — BA/QA/PM không thấy |
+
+**Kết luận:** Kit hiện nhớ được *"đang làm gì, đến đâu"* nhưng không nhớ được *"đã học được gì"*.
+
+---
+
+## 3. Kiến Trúc Tổng Quan: "Project Brain" trên AK-Docs
+
+### 3.1 Nguyên tắc thiết kế
+
+1. **Git-based, markdown, human-readable** — không cần vector DB/server ở giai đoạn đầu. Hạ tầng PILOT đã là GitLab + AK-Docs (được `ak init`/`ak update` tự `git pull` — xem `scripts/docs-repo.js`), nên **cross-role sync có sẵn miễn phí qua git**. Memory dạng markdown thì con người review được — khớp triết lý *"AI làm draft — người review & approve"*.
+2. **Memory cũng phải qua Gate** — AI đề xuất, con người approve. Memory sai còn nguy hiểm hơn không có memory (AI sẽ tự tin lặp lại điều sai).
+3. **Kế thừa ý tưởng, không kế thừa code** — `99.Memory/` là hệ **mới, độc lập hoàn toàn** với kho `aiflow memory` cũ (`.aiflow/memory/`, JSON — sẽ khai tử). Scorer trong `scripts/memory.js` chỉ kế thừa về ý tưởng (viết mới cho markdown + frontmatter); khái niệm instinct/confidence port từ ECC `continuous-learning-v2`, đổi nơi lưu từ `~/.local/share` (per-machine) sang AK-Docs (per-project, cả team dùng chung).
+4. **Index-first, load chọn lọc** — không bao giờ load toàn bộ memory vào context (chi tiết Luồng LOAD, mục 4.3).
+
+### 3.2 Cấu trúc lưu trữ: `99.Memory/` trong AK-Docs
+
+```
+AK-Docs/
+├── 00.Project-Overview/ ... 04.Coding/     ← như hiện tại
+└── 99.Memory/                               ← MỚI: Project Brain
+    ├── MEMORY.md                            ← Index: 1 dòng/memory (luôn inject vào context)
+    ├── 00.Shared/                           ← Tri thức chung mọi role
+    │   ├── architecture/                    (facts về hệ thống — chia folder theo functionId)
+    │   │   ├── F-003_Payment/…  và  _global/…
+    │   ├── domain/                          (business rules đã confirm — chia theo functionId)
+    │   ├── glossary/                        (thuật ngữ JP↔VN↔EN — flat, hầu hết global — Comtor chủ trì)
+    │   └── decisions/                       (ADR: quyết định + lý do, link ticket — flat)
+    ├── 01.Lessons/                          ← "Không lặp lỗi cũ", chia theo role
+    │   ├── dev/  ├── qa/  ├── ba/  └── pm/      (trong mỗi role chia folder theo functionId + _global/)
+    ├── 02.Instincts/                        ← Pattern AI tự đề xuất, có confidence
+    │   └── approved/   (đã duyệt — được recall; chia theo functionId + _global/)
+    ├── 03.Retro/                            ← Raw: tóm tắt học được sau mỗi task (⚠ vòng đời
+    │   │                                       commit hay local — xem "Vấn đề mở" dưới mục 3.2)
+    │   └── TICKET-123.md
+    ├── _deprecated/                         ← Memory đã gỡ (soft-remove) — giữ để tra cứu lịch sử
+    └── _pending/                            ← Nháp LOCAL-ONLY (gitignore, không bao giờ push) — hàng đợi
+                                               duyệt thật là các MR label `memory` trên GitLab
+```
+
+> **Quy ước trạng thái & vòng đời:** memory mới sinh ra (bởi AI hoặc người) nằm ở `_pending/` với `status: pending` — thư mục này là **local-only (gitignore), không bao giờ được push**; nó tồn tại để draft tích lũy trong lúc làm task, để người tạo gom/tự đọc lại trước khi gửi, và để chính họ recall được ngay. Khi `ak memory submit`, file được **move khỏi `_pending/` sang thư mục đích ngay trên branch của MR** — hàng đợi duyệt thực sự là danh sách MR label `memory` trên GitLab, không phải một folder trên `main`. PM **merge** → memory chính thức luôn (CI đã flip `status: approved` + ghi vào `MEMORY.md` trên branch, không cần move lần hai). PM **reject** (close MR kèm lý do) → không gì lọt vào `main`, lý do trace được ngay trong MR đã đóng; CLI trả file về `_pending/` local để sửa gửi lại, hoặc xóa hẳn nếu người đề xuất bỏ. **Memory đã approve được recall trên mọi máy; memory `pending` chỉ được recall trên máy của chính người tạo** (kèm nhãn ⚠ chưa duyệt, điểm ưu tiên thấp hơn) — approve là cổng để tri thức lan sang các thành viên khác. Memory bị gỡ chuyển vào `_deprecated/`, rời khỏi index nhưng không xóa (trace được về sau).
+
+> ### ⚠️ Vấn đề mở — nguy cơ mất tri thức khi user không submit (chưa chốt, xử lý sau)
+>
+> **Rủi ro:** `_pending/` giờ là local-only (gitignore). Nếu AI tự đúc kết memory cuối Gate/cuối session nhưng user không chủ động chạy `ak memory submit` — vì quên, vì bận, hoặc vì thấy chưa đáng gửi — thì tri thức đó **không bao giờ đến được với team**, và có thể mất hẳn nếu đổi máy/cài lại môi trường. Đây là đánh đổi trực tiếp của quyết định "PM duyệt qua MR, _pending chỉ là nháp local": an toàn cho chất lượng memory chính thức, nhưng không có lưới đỡ cho phần chưa submit.
+>
+> **Hướng đã cân nhắc, chưa chốt:**
+> 1. **`03.Retro/TICKET-xxx.md` luôn auto-commit vào AK-Docs** (giống các doc Gate khác, không qua `_pending`, không cần duyệt) — làm lưới an toàn tối thiểu: dù memory cụ thể không được submit, tri thức thô vẫn nằm trong git, cả team đọc được, và `ak memory consolidate` có thể quét lại các Retro chưa được khai thác thành memory để nhắc lại.
+> 2. **Checkpoint bắt buộc** ở cuối Gate (đặc biệt Gate 5 trước khi tạo PR): AI liệt kê số draft đang nằm trong `_pending/` và buộc user ra quyết định rõ ràng (submit ngay / cố tình bỏ qua / xóa) — biến "dễ quên" thành "bị nhắc chủ động", không tự ý auto-submit để tránh spam MR chất lượng thấp.
+> 3. Kết hợp cả hai: Retro là lưới an toàn thụ động, checkpoint là nhắc chủ động.
+>
+> **Cần quyết định:** vòng đời chính xác của `03.Retro/` (auto-commit hay cũng local-only như phương án ban đầu), và có áp dụng checkpoint bắt buộc ở Gate nào hay không. Ghi chú lại đây để xử lý ở vòng review sau.
+
+---
+
+## 4. Bốn Luồng Vận Hành Chính
+
+Toàn bộ việc quản lý memory gói trong **4 luồng**. Mỗi luồng có thể được **kích hoạt bởi nhiều cách khác nhau** (AI tự động, hoặc con người chủ động) nhưng luôn đi qua đúng một cổng xử lý và một cổng duyệt — không có đường tắt.
+
+| Luồng | Trả lời câu hỏi | Ai luôn là người duyệt cuối |
+|---|---|---|
+| **1. Khởi tạo** | Bắt đầu "bộ nhớ" cho dự án như thế nào? | (không cần duyệt riêng — dùng chung cổng duyệt của Luồng Lưu trữ) |
+| **2. Lưu trữ** | Điều gì đáng nhớ trở thành memory chính thức như thế nào? | **PM** |
+| **3. Nạp/Sử dụng** | Khi làm task, AI lấy đúng memory nào, bao nhiêu là đủ? | (tự động theo quy tắc, không cần người duyệt mỗi lần) |
+| **4. Gỡ bỏ** | Memory sai/cũ/dư thừa được loại ra khỏi hệ thống thế nào? | **PM** (đôi khi hỏi ý TL nếu là kỹ thuật) |
+
+---
+
+### Luồng 1 — KHỞI TẠO (Init): tạo "bộ nhớ" cho dự án
+
+**Hiểu đơn giản:** giống như mở một cuốn sổ tay chung cho cả team — cần có sổ trước khi ai ghi được gì vào đó. `ak init` chỉ mở sổ trống, **không tự đọc gì cả** (AI đọc tài liệu/code sẽ tốn token, nên phải để người dùng tự quyết định có làm hay không, và làm lúc nào). Muốn soạn sẵn vài trang đầu từ tài liệu có sẵn thì phải chủ động chạy thêm lệnh `ak memory sync` — và nội dung soạn ra vẫn luôn đi qua Luồng 2 (Lưu trữ) để được duyệt, không tự công bố.
+
+**Các cách kích hoạt (trigger):**
+- **`ak init` — luôn tự động, không tốn token:** chỉ tạo khung sổ trống (nếu chưa có bộ nhớ) hoặc đồng bộ về máy (nếu đã có) — **không đọc tài liệu/code**, không sinh ghi nhớ nào.
+- **`ak memory sync` — chủ động, do người dùng tự quyết định lúc nào chạy (vì bước này tốn token AI để đọc tài liệu/code):**
+  - **Lần đầu chạy** cho dự án → AI đọc TOÀN BỘ tài liệu/code hiện có → soạn hàng loạt ghi nhớ nháp, đỡ phải chờ tích lũy từ con số 0.
+  - **Các lần chạy sau** → AI chỉ đọc phần tài liệu/code **THAY ĐỔI** kể từ lần sync gần nhất — tránh đọc lại từ đầu (tốn token) và tránh ghi đè lên ghi nhớ cũ đã duyệt.
+
+```
+Dự án bắt đầu dùng AI Flow Kit
+      │
+      ▼
+Chạy `ak init`
+      │
+      ▼
+Đã có "bộ nhớ dự án" chưa?
+      │ ĐÃ CÓ RỒI → chỉ đồng bộ về máy, không tạo lại (đi thẳng xuống "Sẵn sàng nhận ghi nhớ mới")
+      ▼ CHƯA CÓ
+Tự động tạo khung sổ trống (không đọc gì, không tốn token)
+      │
+      ▼
+Sẵn sàng nhận ghi nhớ mới — tích lũy dần từ 0 cũng được,
+không bắt buộc phải làm gì thêm
+      │
+      ▼  (chỉ khi người dùng CHỦ ĐỘNG muốn có sẵn vài ghi nhớ ban đầu)
+Người dùng tự chạy `ak memory sync`
+      │
+      ▼
+Đã từng chạy `ak memory sync` cho dự án này chưa?
+      │ CHƯA TỪNG (lần đầu) → AI đọc TOÀN BỘ tài liệu/code hiện có
+      ▼ ĐÃ TỪNG RỒI → AI chỉ đọc phần THAY ĐỔI kể từ lần sync gần nhất
+AI soạn ghi nhớ NHÁP cho phần vừa đọc
+(kiến trúc hệ thống, thuật ngữ, quy tắc nghiệp vụ đã thấy trong tài liệu)
+      │
+      ▼
+Chuyển sang LUỒNG LƯU TRỮ để PM duyệt hàng loạt
+      │
+      ▼
+Trở về "Sẵn sàng nhận ghi nhớ mới" — lần `ak memory sync` kế tiếp
+(bất kỳ lúc nào, do người dùng chủ động) sẽ lại đi qua bước
+"Đã từng chạy... chưa?" ở trên, nhưng lúc đó luôn rơi vào nhánh incremental
+```
+
+**Ai làm gì:**
+- Hệ thống (`ak init`): tự tạo khung thư mục trống hoặc đồng bộ — không đọc tài liệu/code, không cần ai duyệt bước này (chưa có nội dung nào để duyệt, cũng không tốn token AI).
+- Con người: **quyết định có chạy `ak memory sync` hay không và chạy lúc nào** — vì đây là bước duy nhất tốn token AI trong cả luồng này. Có thể bỏ qua hoàn toàn và để memory tích lũy dần qua Luồng 2 trong lúc làm task, không bắt buộc phải sync.
+- AI: chỉ đọc tài liệu/code khi `ak memory sync` được người dùng chủ động chạy — lần đầu đọc toàn bộ, các lần sau chỉ đọc phần thay đổi để tiết kiệm token và tránh ghi đè ghi nhớ cũ quan trọng. AI **không tự công bố**, toàn bộ nháp phải đi qua Luồng 2 để người duyệt (thường là một buổi duyệt tập trung vì số lượng nháp nhiều hơn ngày thường, đặc biệt ở lần full scan đầu tiên).
+
+**Hoàn thành khi:** bộ nhớ dự án đã tồn tại và được chia sẻ cho cả team (qua GitLab) — có thể chỉ là khung trống (nếu chưa ai chạy `ak memory sync`), hoặc có thêm vài ghi nhớ chính thức đầu tiên nếu đã chạy.
+
+---
+
+### Luồng 2 — LƯU TRỮ (Store): biến điều đáng nhớ thành memory chính thức
+
+**Hiểu đơn giản:** ai cũng có thể "đề xuất" một điều đáng nhớ, nhưng chỉ khi PM đồng ý thì nó mới trở thành memory thật mà cả team dùng được. Giống như một bài viết nội bộ: ai cũng viết được, nhưng phải qua biên tập duyệt bài trước khi đăng. Trong lúc chờ duyệt, bản nháp vẫn được **chính người tạo dùng ngay trên máy của họ** (Luồng 3 nạp kèm nhãn "chưa duyệt") — duyệt là để *người khác* cũng kế thừa được.
+
+**Các cách kích hoạt (nhiều nguồn, đều hội tụ về một chỗ):**
+
+```
+Rất nhiều cách một ghi nhớ có thể được tạo ra (bất kỳ nguồn nào dưới đây):
+  • [AI tự động] Cuối mỗi bước công việc (Gate), AI tự đúc kết bài học vừa gặp
+  • [AI tự động] Hết giờ làm nhưng task chưa xong — AI ghi tạm lại, không bỏ sót
+  • [AI tự động] Trước khi hội thoại quá dài bị rút gọn — AI lưu lại trước khi "quên"
+  • [Con người chủ động] Gõ lệnh "ghi nhớ" ngay khi nghĩ ra điều quan trọng
+  • [Từ Luồng KHỞI TẠO] Lô ghi nhớ từ `ak memory sync` — full scan nếu là lần đầu, incremental nếu các lần sau
+      │
+      ▼
+Tạo bản NHÁP vào `_pending/` (người tạo dùng được ngay trên máy mình; người khác chưa thấy)
+      │
+      ▼
+Có trùng với ghi nhớ đã có sẵn không?
+      │ TRÙNG → đề xuất CẬP NHẬT bản cũ thay vì tạo bản mới (rồi tiếp tục như dưới)
+      ▼ MỚI HOÀN TOÀN
+Gửi đề xuất lên GitLab (giống gửi một "đơn xin duyệt")
+      │
+      ▼
+Hệ thống tự mời đúng người góp ý theo loại nội dung
+(TL cho kỹ thuật, BA cho nghiệp vụ...)
+      │
+      ▼
+PM xem xét toàn bộ
+      │ CẦN SỬA LẠI → quay lại "Tạo bản NHÁP" ở trên
+      │ TỪ CHỐI → Dừng — lý do được ghi lại công khai
+      ▼ ĐỒNG Ý
+PM DUYỆT → trở thành memory CHÍNH THỨC
+      │
+      ▼
+Đồng bộ tới máy của mọi thành viên
+```
+
+**Ai làm gì (bước xử lý):**
+
+1. **Capture (bất kỳ role nào, hoặc AI):** phát hiện điều đáng nhớ → tạo bản nháp. AI làm việc này tự động (cuối Gate, cuối session, trước khi context bị rút gọn); con người làm việc này bằng một lệnh ghi nhớ nhanh bất cứ lúc nào trong lúc làm việc.
+2. **Chống trùng lặp:** trước khi tạo mới, hệ thống/AI kiểm tra xem tri thức này đã có chưa — nếu có thì đề xuất sửa bản cũ, tránh phình kho nhớ với nhiều bản gần giống nhau.
+3. **Gửi duyệt:** người đề xuất (hoặc AI thay mặt, nhưng vẫn cần một người "đứng tên" gửi) đóng gói đề xuất thành một "đơn xin duyệt" trên GitLab.
+4. **Góp ý chuyên môn (không phải quyết định):** hệ thống tự mời TL/BA/QA góp ý nếu nội dung thuộc chuyên môn của họ (ví dụ: ghi nhớ về kỹ thuật thì mời TL, về thuật ngữ thì mời BA/Comtor). Đây là **tham vấn**, không phải phê duyệt.
+5. **PM xem xét & quyết định:** đây là bước duyệt duy nhất. PM có 3 lựa chọn — yêu cầu sửa (quay lại bước 1), từ chối (dừng, có ghi lý do để tra cứu sau), hoặc đồng ý.
+6. **Công bố chính thức:** khi PM đồng ý, ghi nhớ chuyển trạng thái "chính thức", được đưa vào danh mục dùng chung, và đồng bộ tới máy của mọi thành viên trong lần làm việc kế tiếp.
+
+**Ai duyệt:** **PM — và chỉ PM.** Không role nào khác (kể cả AI, kể cả TL) có quyền tự công bố một ghi nhớ thành chính thức. TL/BA/QA chỉ góp ý.
+
+> Chi tiết kỹ thuật của luồng này (quy trình trên GitLab — nhánh nào, ai được gắn vào đề xuất theo loại nội dung, cấu hình bắt buộc) nằm ở mục 5.1.
+
+---
+
+### Luồng 3 — NẠP/SỬ DỤNG (Load): AI dùng memory khi làm task
+
+**Hiểu đơn giản:** không phải lúc nào AI cũng cần đọc hết cả cuốn sổ tay — chỉ cần đọc đúng phần liên quan tới việc đang làm. Nạp quá ít thì AI thiếu thông tin, nạp quá nhiều thì AI bị "ngộp" và chậm. Đây là luồng **tự động hoàn toàn**, không có bước con người duyệt (vì chỉ là đọc lại thông tin đã được duyệt sẵn ở Luồng 2).
+
+```
+AI bắt đầu làm 1 công việc mới
+      │
+      ▼
+BƯỚC 1 — Luôn đọc: danh mục tóm tắt toàn bộ ghi nhớ
+(giống mục lục sách, rất ngắn)
+      │
+      ▼
+Xác định: đang chạy WORKFLOW nào (coding / create-spec / create-testcase...),
+đang làm ticket/functionId nào
+      │
+      ▼
+BƯỚC 2 — Chọn lọc: lấy khoảng 10 ghi nhớ liên quan nhất
+và đọc đầy đủ nội dung (gồm cả ghi nhớ pending do chính mình tạo
+trên máy này — gắn nhãn "chưa duyệt")
+      │
+      ▼
+Ghi nhớ này còn đúng với code/tài liệu hiện tại không?
+      │ CÓ THỂ ĐÃ CŨ → vẫn dùng nhưng kèm cảnh báo "nên kiểm tra lại trước khi tin"
+      ▼ CÒN MỚI, CHẮC CHẮN
+Dùng bình thường
+      │
+      ▼
+Trong lúc làm, có chạm tới phần chưa được đọc trước không?
+      │ CÓ → BƯỚC 3: đọc thêm đúng lúc cần, không đọc trước cho dư thừa
+      ▼ KHÔNG CẦN
+Hoàn thành công việc —
+ghi nhận ghi nhớ nào đã hữu ích, ghi nhớ nào chưa ai dùng tới
+```
+
+**Ai làm gì:**
+- **AI:** tự thực hiện toàn bộ 3 bước mỗi khi bắt đầu một công việc — không cần ai yêu cầu.
+- **Con người:** không tham gia trực tiếp vào luồng này, nhưng là người *hưởng lợi* (AI làm việc thông minh hơn mà không cần được nhắc lại) và là người quyết định các "công thức chọn lọc" (bao nhiêu ghi nhớ là đủ, ưu tiên loại nào cho vai trò nào) thông qua cấu hình dự án.
+- **Không có bước duyệt** — vì nội dung đã được duyệt từ Luồng 2, ở đây chỉ là *đọc lại* đúng thứ cần.
+
+**Nguyên tắc quan trọng — không nạp toàn bộ, không nạp cố định:**
+- Nạp **theo workflow đang chạy** (không phân biệt role người dùng — ai cũng chạy được mọi workflow): workflow coding cần lessons dev và kiến trúc kỹ thuật; create-spec cần thuật ngữ và quy tắc nghiệp vụ; create-testcase cần các lỗi từng gặp khi test — mỗi workflow có "gu đọc" riêng, tránh nạp thứ không liên quan gây nhiễu.
+- Nạp **theo mức độ phức tạp của việc đang làm**: việc nhỏ/sửa lỗi nhanh thì đọc ít hơn nhưng ưu tiên tuyệt đối các bài học liên quan trực tiếp; việc lớn động tới nhiều phần thì đọc rộng hơn.
+- Có **giới hạn cứng** về dung lượng được nạp — dù kho ghi nhớ có phình to theo thời gian, phần đọc vào mỗi lần vẫn được giữ ở mức nhỏ và ổn định.
+
+> Chi tiết kỹ thuật (công thức chấm điểm để chọn ghi nhớ, cách chỉnh số lượng theo từng vai trò, cơ chế chống phình khi kho nhớ lớn dần) nằm ở mục 5.2.
+
+---
+
+### Luồng 4 — GỠ BỎ (Remove): giữ kho memory sạch, không cũ, không sai
+
+**Hiểu đơn giản:** một cuốn sổ tay chỉ hữu ích nếu thông tin trong đó còn đúng. Luồng này lo việc "xé bỏ" hoặc "gạch bỏ" những ghi nhớ đã lỗi thời, đã sai, hoặc dư thừa — nhưng làm rất cẩn trọng, gần giống hệt Luồng Lưu trữ (cùng cơ chế đề xuất → duyệt), chỉ khác chiều: đây là đề xuất **rút** thay vì **thêm**.
+
+**Các cách kích hoạt (trigger):**
+
+```
+Các lý do một ghi nhớ bị đưa ra xem xét gỡ (bất kỳ nguồn nào dưới đây):
+  • [Tự động] Dọn dẹp định kỳ phát hiện: ghi nhớ lâu không ai dùng tới
+  • [Tự động] Code/tài liệu nền đã thay đổi, không ai xác nhận lại là còn đúng nữa
+  • [Tự động] Ghi nhớ đã "lên chức" thành quy tắc chung áp dụng cho mọi dự án —
+    không cần giữ bản riêng lẻ nữa
+  • [Con người chủ động] Ai đó phát hiện một ghi nhớ đang sai hoặc không còn phù hợp
+      │
+      ▼
+Đề xuất GỠ (dùng đúng cơ chế gửi đề xuất như Luồng LƯU TRỮ)
+      │
+      ▼
+PM xem xét (hỏi ý TL nếu là ghi nhớ kỹ thuật)
+      │ KHÔNG ĐỒNG Ý → Giữ nguyên — lý do được ghi lại
+      ▼ ĐỒNG Ý GỠ
+Gỡ theo kiểu nào?
+      │ BÌNH THƯỜNG (đa số trường hợp)
+      ▼
+ẨN khỏi danh mục sử dụng
+(vẫn lưu lại để tra cứu lịch sử, AI không dùng tới nữa)
+      │
+      │ ĐẶC BIỆT: sai nghiêm trọng hoặc chứa thông tin nhạy cảm
+      │ → XÓA HẲN khỏi kho lưu trữ (thay cho bước ẨN ở trên)
+      ▼
+Đồng bộ: mọi thành viên không còn thấy ghi nhớ này
+```
+
+**Ai làm gì:**
+
+1. **Phát hiện (nhiều nguồn):**
+   - AI/hệ thống tự động phát hiện qua dọn dẹp định kỳ: ghi nhớ lâu ngày không ai dùng tới, hoặc code/tài liệu liên quan đã đổi mà không ai xác nhận lại.
+   - AI/hệ thống tự động phát hiện khi một ghi nhớ đã được TL "chắt lọc" thành quy tắc chung cho mọi dự án (xem mục 6) — bản gốc trong dự án không cần giữ song song nữa để tránh trùng lặp.
+   - Con người chủ động phát hiện: bất kỳ ai trong lúc làm việc nhận ra một ghi nhớ đang sai hoặc lỗi thời có thể đề xuất gỡ ngay.
+2. **Đề xuất:** đóng gói giống một "đơn xin duyệt" (đúng cơ chế của Luồng 2), nêu rõ lý do gỡ.
+3. **PM xem xét & quyết định:** giống Luồng 2 — PM là người duyệt cuối; nếu ghi nhớ thuộc phạm vi kỹ thuật, PM tham vấn TL trước khi quyết.
+4. **Cách gỡ (2 mức, PM chọn):**
+   - **Gỡ mềm (mặc định, gần như mọi trường hợp):** ghi nhớ được ẩn khỏi danh mục — AI không còn đọc/dùng nó nữa — nhưng dữ liệu vẫn được giữ lại đâu đó để sau này có thể tra cứu "vì sao trước đây từng nghĩ vậy". An toàn, có thể khôi phục nếu cần.
+   - **Gỡ hẳn (hiếm, chỉ khi có lý do đặc biệt):** xóa hoàn toàn khỏi kho lưu trữ — chỉ dùng khi ghi nhớ chứa thông tin sai nghiêm trọng có thể gây hại nếu còn tồn tại (ví dụ dữ liệu nhạy cảm bị lưu nhầm), vì đây là hành động khó đảo ngược.
+5. **Đồng bộ:** sau khi PM xử lý xong, mọi máy trong team cập nhật lại — từ session làm việc kế tiếp, ghi nhớ đã gỡ sẽ không còn xuất hiện.
+
+**Ai duyệt:** **PM** (giống Luồng Lưu trữ) — tham vấn TL khi cần cho nội dung kỹ thuật.
+
+---
+
+## 5. Chi Tiết Kỹ Thuật Bổ Sung (dành cho người triển khai)
+
+Phần này đi sâu vào cách thực hiện 4 luồng trên bằng công cụ cụ thể (GitLab, CLI, file, cấu hình) — dành cho AI Testing Team/TechLead khi implement, không cần thiết cho người chỉ muốn hiểu "memory hoạt động ra sao".
+
+### 5.1 Vai trò & Quy trình GitLab chi tiết (hỗ trợ Luồng LƯU TRỮ và GỠ BỎ)
+
+#### 5.1.1 Bảng vai trò quản lý memory (AI · DEV · BA · QA · PM · TL)
+
+Nguyên tắc phân quyền: **mọi role đều được tổng hợp memory và gửi thành đề xuất; PM là người duy nhất review & approve (cả thêm mới và gỡ bỏ); TL định kỳ chắt lọc memory dùng chung để tổng hợp thành skills/rules cấp kit cho mọi dự án.**
+
+| Role | Capture / đề xuất thêm | Đề xuất gỡ | Review & Approve | Chắt lọc dùng chung (promotion) | Recall / sử dụng |
+|---|---|---|---|---|---|
+| **AI** | ⭐ Nguồn chính: tự tổng hợp từ hội thoại, bootstrap | ✅ Tự phát hiện memory stale/không ai dùng | ❌ **Không bao giờ tự approve.** Chỉ hỗ trợ PM: tóm tắt đề xuất, check trùng lặp, check template, cảnh báo mâu thuẫn `.rules/` | Sinh danh sách candidates cho TL | ✅ Recall 3 lớp (Luồng 3) |
+| **DEV** | ✅ Lessons dev, architecture facts | ✅ | Comment góp ý (không quyết) | — | ✅ |
+| **BA** | ✅ Domain facts, glossary, distill từ QnA khách | ✅ | **Consult** cho `domain/`, `glossary/` khi PM tag | — | ✅ |
+| **QA** | ✅ Lessons qa, bẫy test môi trường | ✅ | Comment góp ý | — | ✅ |
+| **PM** | ✅ Decisions, lessons pm | ✅ | ⭐ **Approver duy nhất** — duyệt cả thêm mới và gỡ bỏ; phân xử khi mâu thuẫn | Xác nhận danh sách candidates trước khi chuyển TL | ✅ |
+| **TL** | ✅ Architecture facts, technical decisions | ✅ | **Consult** bắt buộc khi PM duyệt nội dung kỹ thuật/instinct | ⭐ **Chắt lọc memory dùng chung → skills/rules của kit** (Flow B dưới) | ✅ |
+
+> ⭐ = vai trò chủ trì · ✅ = được làm/tham gia · Consult = PM tag vào để góp ý chuyên môn, quyền quyết vẫn ở PM.
+
+**Checklist PM khi duyệt đề xuất (thêm hoặc gỡ):** (1) đúng sự thật và còn hiệu lực? (2) trace được nguồn gốc? (3) 1 nội dung ngắn gọn, đúng khuôn mẫu? (4) có hành động cụ thể áp dụng được? (5) phạm vi áp dụng hẹp nhất có thể? (6) không mâu thuẫn `.rules/`? (7) đã tham vấn đúng người cho nội dung nhạy cảm chưa?
+
+#### 5.1.2 Mô hình nhánh Git (`main` là nhánh chính)
+
+```
+Repo AK-Docs (GitLab) — kho memory của DỰ ÁN
+main ────●─────────●─────────●──────────→   main = memory chính thức (protected)
+          \         \        ↑ merge (PM approve)
+           \         memory/TICKET-124        ← QA đề xuất từ task test
+            memory/TICKET-123                 ← DEV/AI đề xuất từ task coding
+            memory/sync-init                   ← `ak memory sync` lần đầu, full scan (Luồng 1)
+            memory/sync-2026-07                ← `ak memory sync` các lần sau, incremental (Luồng 1)
+            memory/remove-mem-042              ← đề xuất gỡ 1 memory cụ thể
+
+Repo ai-flow-kit (GitLab) — kho skills/rules DÙNG CHUNG mọi dự án
+main ────●───────────────●──────────→
+          \               ↑ merge (AI Testing Team approve)
+           promotion/sprint-12                ← TL chắt lọc mỗi sprint
+```
+
+**Cấu hình GitLab (làm 1 lần khi setup dự án):**
+
+| Hạng mục | Cấu hình |
+|---|---|
+| Protected branch | `main` của AK-Docs: không push trực tiếp, chỉ merge qua Merge Request (MR) |
+| Approval rule | MR có label `memory` bắt buộc ≥1 approval từ **PM** |
+| CODEOWNERS | `99.Memory/00.Shared/architecture/ @TL` · `00.Shared/domain/ @BA` · `00.Shared/glossary/ @BA` (hoặc @Comtor) · `02.Instincts/ @TL` → GitLab tự gợi ý consult reviewer theo diff |
+| MR template `memory.md` | Nhúng checklist PM (mục 5.1.1) + trường: ticket nguồn, danh sách mem-id, loại (thêm/gỡ) |
+| CI pipeline (Phase 2) | Job `memory-lint`: validate frontmatter đủ trường, ≤150 từ, 1 fact/file, id không trùng, id khớp đường dẫn file, **quét secret/PII pattern** (chặn TRƯỚC khi merge — gỡ khỏi lịch sử git về sau rất đắt) · Job `memory-finalize` (khi MR đủ approval): flip `status`, điền `reviewed_by`, rebuild `MEMORY.md` |
+
+**Flow A — Đề xuất thêm/sửa memory (Luồng LƯU TRỮ, chi tiết trên GitLab):**
+
+| Step | Ai | Hành động trên GitLab |
+|---|---|---|
+| A1 | AI / bất kỳ role nào | Tạo memory draft vào `_pending/` local |
+| A2 | Người đề xuất | `ak memory submit` → CLI tạo branch `memory/<ticket-id>` từ `main`, move file về thư mục đích, cập nhật nháp `MEMORY.md`, push, mở MR: label `memory`, assignee `@PM`, title `memory(TICKET-123): +2 lesson/dev, +1 fact/domain` |
+| A3 | GitLab | CODEOWNERS tự thêm consult reviewer theo thư mục bị đụng; CI chạy `memory-lint` |
+| A4 | Consult (TL/BA/QA) | Comment/suggestion trên diff (nếu được tag) — không có quyền merge |
+| A5 | PM | Review theo checklist → yêu cầu sửa (quay lại A2) / close MR kèm lý do (= reject) / **Approve** |
+| A6 | CI (`memory-finalize`) | Flip `status: approved`, điền `reviewed_by: PM`, rebuild `MEMORY.md` — commit lên branch |
+| A7 | PM | **Merge vào `main`** (squash, message `memory: TICKET-123 (+3)`) → xóa branch |
+| A8 | Mọi máy | Session-start / `ak use` pull `main` → mọi role có memory mới từ session kế tiếp. Pull có timeout ngắn; lỗi mạng/VPN → **warning kèm nội dung lỗi + tiếp tục dùng bản local hiện có** (mục 5.2 bước 0) |
+
+**Flow A' — Đề xuất gỡ memory (Luồng GỠ BỎ, chi tiết trên GitLab):** giống Flow A nhưng branch tên `memory/remove-<mem-id>`, MR mô tả lý do gỡ + kiểu gỡ (soft/hard); `memory-finalize` với soft-remove sẽ move file sang `_deprecated/` và xóa dòng khỏi `MEMORY.md`; với hard-remove sẽ `git rm` file (PM cần xác nhận rõ trong MR vì khó đảo ngược). **Lưu ý:** `git rm` chỉ xóa khỏi bản hiện tại, KHÔNG xóa khỏi lịch sử git — muốn xóa triệt để (dữ liệu nhạy cảm) phải rewrite history bằng `git filter-repo` trên repo dùng chung, rất tốn kém. Vì vậy tuyến phòng thủ chính là job `memory-lint` quét secret/PII chặn từ trước khi merge.
+
+**Flow B — TL chắt lọc memory dùng chung thành skills/rules (định kỳ mỗi sprint):**
+
+| Step | Ai | Hành động |
+|---|---|---|
+| B1 | TL | Chạy `ak memory consolidate --candidates` trên AK-Docs `main` → danh sách memory có hit cao / lặp ≥2 ticket / xuất hiện ở ≥2 dự án |
+| B2 | TL (+ PM xác nhận) | Phân loại từng candidate: (a) đặc thù dự án → giữ nguyên ở `99.Memory/` · (b) đúng cho mọi dự án cùng stack → **rule/skill của kit** · (c) tri thức tham khảo chung → **Shared-Docs** |
+| B3 | TL | Tạo branch `promotion/<sprint>` trên repo **ai-flow-kit**: viết rule vào `custom/rules/` hoặc skill vào `custom/skills/`; mở MR, mô tả link về các mem-id nguồn (trace 2 chiều) |
+| B4 | AI Testing Team | Review MR trên repo kit (chuẩn chung ảnh hưởng MỌI dự án nên cổng duyệt cao hơn PM dự án) → merge `main` của kit |
+| B5 | Kit release | Các dự án chạy `ak update` → `.rules/` được wipe & copy lại (init.js:189-191) → rule mới tự lan ra mọi dự án |
+| B6 | TL | Quay lại AK-Docs: mở MR **đề xuất gỡ** (Luồng 4, R3) memory đã promote → PM duyệt → chuyển `_deprecated/`, note `→ custom/rules/xyz.md` |
+
+> Vì sao 2 cổng duyệt khác nhau: memory là tri thức **một dự án** → PM dự án quyết; rule/skill là chuẩn **mọi dự án** → phải qua AI Testing Team trên repo kit.
+
+### 5.2 Cơ chế tải & tối ưu memory (hỗ trợ Luồng NẠP/SỬ DỤNG)
+
+**Mô hình 3 lớp** (không bao giờ load toàn bộ):
+
+| Lớp | Load khi nào | Nội dung | Kích thước |
+|---|---|---|---|
+| **Lớp 1 — Index** | Luôn luôn, mỗi session | `MEMORY.md` (1 dòng/memory: id, type, scope, hook 1 câu) + quy tắc ưu tiên (`.rules` > memory) | ~1–3 KB |
+| **Lớp 2 — Relevant set** | Session start, theo ticket | Top-N memory match workflow + functionId + tags (mặc định N=10) — **nội dung đầy đủ**; cộng thêm memory `_pending/` của chính user trên máy này (nhãn ⚠ chưa duyệt) | ≤ `injectBudget` (mặc định ~2000 tokens) |
+| **Lớp 3 — On-demand** | Giữa task, khi cần | AI tự `Read` file memory cụ thể khi thấy dòng index liên quan đến việc đang làm | Theo nhu cầu |
+
+**Step by step tại session start (`session-start.js` mở rộng):**
+
+0. Pull AK-Docs với timeout ngắn. Pull lỗi (mạng/VPN/conflict) → **in warning kèm nội dung lỗi** cho user biết và **tiếp tục dùng bản local hiện có** — không bao giờ chặn session vì thiếu mạng.
+1. Đọc `.aiflow/context/current.json` → lấy `taskId`, `functionId`, title, description, keywords; xác định **workflow đang chạy** (coding / create-spec / create-testcase / gen-doc) — không phân biệt role người dùng.
+2. Quét `99.Memory/` (file `status: approved` + file trong `_pending/` do chính user này tạo), parse frontmatter.
+3. **Chấm điểm** từng memory (scorer viết mới — kế thừa ý tưởng từ `loadRelevantMemories` trong `scripts/memory.js` cũ, không tái dùng code):
+
+```
+score = 3 × match(memory nằm trong folder functionId của ticket)
+      + 2 × match(workflows chứa workflow đang chạy)
+      + 2 × số phần tử trùng giữa `tags:` của memory và keywords của ticket
+        (CHỈ so khớp trên frontmatter `tags:` đã chuẩn hóa ascii-lowercase —
+         KHÔNG so trên title/body: tiếng Nhật không tách từ bằng khoảng trắng,
+         tiếng Việt vướng dấu — keyword match trên body sẽ gãy)
+      + 1 × confidence
+      − 1 × (tuổi memory > 90 ngày và hit count == 0)
+      − 0.5 × (status == pending — bản local chưa duyệt của chính user)
+      ; type == lesson được +1 khi workflow là gate coding/review
+```
+
+4. Inject **Lớp 1**: toàn bộ `MEMORY.md` + chỉ dẫn ưu tiên `.rules/` khi mâu thuẫn.
+5. Inject **Lớp 2**: lấy memory theo điểm giảm dần, dừng khi đủ N hoặc chạm `injectBudget` tokens.
+6. Ghi telemetry: số memory inject, tổng tokens.
+7. Trong task, **Lớp 3**: CLAUDE.md Gate 1 quy định bắt buộc search `99.Memory/` theo functionId/tên module trước khi phân tích hoặc sửa module chưa có trong context.
+
+**Profile theo workflow (mặc định, override được)** — gắn với *workflow đang chạy*, không gắn với role của người dùng (ai cũng có thể chạy mọi workflow):
+
+| Workflow đang chạy | Memory được ưu tiên load (Lớp 2) |
+|---|---|
+| coding — Gate 1–5 | `architecture` functionId liên quan + `lessons/dev` + `instincts` + `decisions` technical |
+| create-spec | `domain` + `glossary` + `lessons/ba` + `decisions` business liên quan |
+| create-testcase / execute-test | `lessons/qa` + `domain` + `glossary` |
+| gen-doc / không xác định (mặc định) | `decisions` + `03.Retro` gần nhất + `architecture` functionId liên quan |
+
+**Điều chỉnh lượng theo độ phức tạp task:** ticket chạm nhiều module/mô tả dài → tăng N (10→15); hotfix nhỏ → giảm N (10→5) nhưng ưu tiên tuyệt đối lessons của đúng module; bug fix → bơm thêm toàn bộ lessons trong folder functionId liên quan (`01.Lessons/*/<functionId>/`) kể cả vượt N.
+
+**Cơ chế chống phình khi kho nhớ lớn dần:**
+
+- **Hard budget:** `injectBudget` (config `.aiflow/state.json`) là trần cứng cho Lớp 2 — vượt trần thì cắt theo điểm số, không bao giờ tràn.
+- **Giới hạn kích thước từng memory:** template enforce body ≤150 từ, 1 file = 1 fact.
+- **Consolidate định kỳ:** `ak memory consolidate` (tay hoặc CI weekly) — dedup/merge memory trùng, rebuild `MEMORY.md`.
+- **Confidence + decay:** memory được trích dẫn → hit count **ghi local vào telemetry** (`.aiflow/`) — KHÔNG commit lên `main` mỗi lần recall (main là protected branch, không thể mở MR cho từng lần +1); `ak memory consolidate` định kỳ tổng hợp telemetry từ các máy và cập nhật `hits` trong frontmatter qua **một MR duy nhất**. Cũ >90 ngày và hit=0 → hạ confidence → dưới ngưỡng thì chuyển sang đề xuất gỡ (Luồng 4, trigger R1).
+- **Scope hẹp mặc định:** ưu tiên gán `scope: <functionId>` thay vì `global` khi tạo memory.
+- **Giám sát:** telemetry cho báo cáo tokens memory/session, tỷ lệ memory được dùng; cảnh báo khi Lớp 1+2 > 5% context.
+- **Override per-project:** `.aiflow/state.json` cho phép chỉnh `memory.topN`, `memory.injectBudget`, `memory.profiles.<role>`.
+
+### 5.3 Templates & cấu trúc file Memory
+
+#### Danh mục file trong `99.Memory/`
+
+| File/Thư mục | Loại nội dung | Ví dụ | Ai tạo |
+|---|---|---|---|
+| `MEMORY.md` | Index — 1 dòng/memory đã approve | `- [mem-F002-order-retention](00.Shared/domain/F-002_Order/order-retention.md) — Đơn hủy giữ record 5 năm (fact, F-002)` | CLI tự sinh khi approve — **không sửa tay** |
+| `00.Shared/architecture/<functionId>/*.md` | Fact kỹ thuật về hệ thống | "Auth dùng JWT, refresh 7 ngày, revoke qua Redis blacklist" | AI đề xuất / Dev lưu |
+| `00.Shared/domain/<functionId>/*.md` | Business rule khách đã confirm | "Đơn hàng hủy vẫn giữ record 5 năm (luật kế toán JP)" | BA / AI từ QnA |
+| `00.Shared/glossary/*.md` | Thuật ngữ JP↔VN↔EN | "受注 = đơn nhận (sales order) — KHÔNG dịch là 発注 (purchase order)" | Comtor |
+| `00.Shared/decisions/*.md` | ADR: quyết định + lý do + link ticket | "Chọn soft-delete toàn bộ bảng — lý do..., TICKET-45" | AI đề xuất tại gate / TL, PM |
+| `01.Lessons/{dev,qa,ba,pm}/<functionId>/*.md` | Bài học từ lỗi đã gặp | "Đừng dùng `@Data` trên Entity — gây bug lazy loading, TICKET-45" | AI Retrospect / thành viên role |
+| `02.Instincts/approved/<functionId>/*.md` | Pattern hành vi cho AI, có confidence | "Khi requirement nhắc 'duplicate email' → check `existsByEmail` trước khi save" | AI đề xuất |
+| `03.Retro/TICKET-xxx.md` | Raw retrospect mỗi task — không cần duyệt, không recall trực tiếp | Tóm tắt học được, signals, memory đã đề xuất | AI |
+| `_pending/` | Nháp local-only (gitignore) chờ submit — hàng đợi duyệt thật là MR label `memory` trên GitLab; reject → CLI trả file về đây hoặc xóa | — | AI / user |
+| `_deprecated/` | Memory đã gỡ (soft-remove) — giữ để tra cứu lịch sử | — | CLI khi PM duyệt gỡ |
+
+#### Template file memory (`custom/templates/memory/memory-item.md`)
+
+```markdown
+---
+id: mem-F003-prevent-429-error   # CLI tự sinh từ vị trí file: mem-<functionId>-<slug>
+                                 # slug do AI đặt — ngắn, đọc là hiểu memory lưu gì
+                                 # (vd: basic-payment-flow, refund-flow, prevent-429-error).
+                                 # KHÔNG có timestamp: trùng slug trong cùng folder chính là
+                                 # tín hiệu chống trùng lặp — CLI hỏi "memory tương tự đã có,
+                                 # cập nhật bản cũ thay vì tạo mới?" (Luồng 2, bước 2)
+type: lesson | fact | decision | glossary | instinct
+workflows: [coding, create-testcase]  # workflow nào cần recall; [all] nếu mọi workflow
+tags: [payment, refund, http-429]     # ascii-lowercase, AI tự sinh khi tạo draft —
+                                      # scorer CHỈ so khớp trên trường này (không so body — JP/VN)
+scope: F-003_Payment | global    # trùng với folder chứa file; global → file đặt trong _global/
+confidence: 0.6                  # AI tự chấm 0.3–0.7; reviewer chỉnh khi duyệt
+source: TICKET-123 / Gate 4      # trace: học được từ đâu
+status: pending                  # pending | approved | deprecated
+hits: 0                          # consolidate cập nhật từ telemetry local — không sửa tay, không commit mỗi lần recall
+created: 2026-07-09
+reviewed_by:                     # điền khi approve
+refs: []                         # (tùy chọn) file/dir code hoặc docs mà memory phụ thuộc — xem mục 5.4
+verified_commit:                 # commit đã verify refs lần cuối (CLI tự điền)
+stale: false                     # hook tự set true khi refs thay đổi sau verified_commit
+---
+<Nội dung: TỐI ĐA 150 từ, 1 file = 1 fact duy nhất.>
+
+**Áp dụng:** <hành động cụ thể AI/người cần làm khi gặp tình huống này.>
+```
+
+**Quy tắc đặt file & id:** các loại gắn với chức năng (`architecture/`, `domain/`, `01.Lessons/*`, `02.Instincts/approved/`) chia folder theo functionId — `.../F-003_Payment/<slug>.md`; memory không thuộc chức năng nào đặt trong `_global/`. `glossary/` và `decisions/` giữ flat (hầu hết là global). id suy ra từ đường dẫn (`mem-<functionId>-<slug>`) nên không cần bộ đếm tập trung — không đụng độ khi nhiều máy tạo draft phân tán; đổi scope = move file (git giữ lịch sử). Recall theo functionId của Lớp 2 nhờ vậy chỉ là liệt kê thư mục, không phải quét toàn kho.
+
+**Dòng index trong `MEMORY.md`:** `- [mem-id](đường/dẫn/file.md) — <hook 1 câu, ≤15 từ> (type, scope, workflows)`
+
+**Template Retro** (`03.Retro/TICKET-xxx.md`): 4 mục — Học được gì mới / Lỗi đã gặp & cách xử lý / Người đã sửa AI ở đâu / Memory đã đề xuất (id + trạng thái).
+
+### 5.4 Memory về code & cơ chế chống lỗi thời (hỗ trợ Luồng NẠP và Luồng GỠ BỎ)
+
+**Câu hỏi gốc:** memory có hỗ trợ việc đọc code không — đã đọc code một lần thì lần sau không cần đọc lại?
+
+**Trả lời: CÓ, nhưng tách 2 tầng** vì "hiểu biết về code" có 2 loại với vòng đời khác nhau:
+
+| Tầng | Nội dung | Sinh bởi | Cần người duyệt? | Chống lỗi thời |
+|---|---|---|---|---|
+| **Codemap** (derived — máy suy ra được) | Bản đồ cấu trúc: module nào làm gì, entrypoint, data flow, dependency | Máy/AI tự sinh từ code — kit **đã có GitNexus** index (`.aiflow/gitnexus-status.json`) | ❌ Không — tái sinh được, sai thì regenerate | Tái sinh incremental theo git diff sau mỗi merge |
+| **Architecture facts** (curated — kết luận đắt giá) | "Vì sao thiết kế như vậy", bẫy, invariant ngầm | AI đề xuất → lưu `00.Shared/architecture/` qua Luồng LƯU TRỮ | ✅ PM (consult TL) | Anchor vào git qua `refs` + staleness check (dưới) |
+
+> **Nguyên tắc cốt lõi: memory KHÔNG lưu code, chỉ lưu KẾT LUẬN về code.** Source of truth luôn là code.
+
+**Cơ chế sync khi code/tài liệu thay đổi:**
+
+1. Khi tạo memory phụ thuộc code/docs, khai `refs: [đường dẫn file/dir]` + `verified_commit` (CLI tự điền commit hiện tại).
+2. Hook (session-start hoặc post-merge) chạy `git diff --name-only <verified_commit>..HEAD` giao với `refs` → có giao thì set `stale: true` (không xóa, không rời index).
+3. Khi recall (Luồng NẠP), memory stale vẫn được dùng nhưng kèm cảnh báo verify lại.
+4. AI dùng memory stale trong task → verify nhanh bằng cách đọc lại `refs`: đúng thì cập nhật `verified_commit`/`stale: false`; sai thì đề xuất bản sửa (qua Luồng LƯU TRỮ).
+5. `ak memory consolidate` định kỳ: memory stale lâu không được verify → hạ confidence → đề xuất gỡ (Luồng GỠ BỎ, trigger R2).
+6. Tài liệu nghiệp vụ dùng cơ chế y hệt — `refs` trỏ tới file spec/QnA trong AK-Docs.
+7. Codemap: regenerate incremental sau merge, tự động, không cần duyệt.
+
+Đây là bài toán cache invalidation kinh điển, giải bằng cách anchor memory vào git commit — rẻ, chính xác ở mức file, tận dụng hạ tầng git sẵn có.
+
+---
+
+## 6. Quan Hệ Giữa `.rules/` Và `99.Memory/`
+
+**Vẫn cần `.rules/`, và không merge** — nối bằng đường "promotion" (Flow B, mục 5.1.2).
+
+| | `.rules/` | `99.Memory/` |
+|---|---|---|
+| Bản chất | **Quy định** (prescriptive) — chuẩn phải tuân theo | **Kinh nghiệm** (learned) — điều dự án rút ra được |
+| Nguồn | Top-down: AI Testing Team soạn trong `custom/rules/` của kit, phân phối qua `ak init` | Bottom-up: sinh từ hội thoại/task, PM approve qua Luồng LƯU TRỮ |
+| Phạm vi | Chung theo stack (java/javascript/php) | Đặc thù từng dự án |
+| Cách nạp | **Luôn luôn load**, tuân thủ 100% | **Recall chọn lọc** (Luồng NẠP) |
+| Tính ổn định | Ổn định, kiểm soát tập trung | Sống, tăng dần, có confidence/decay, có thể bị gỡ |
+
+**Lý do kỹ thuật quyết định không merge:** `scripts/init.js:189-191` mỗi lần `ak init`/`ak update` chạy `fs.emptyDir(rulesDir)` rồi copy đè từ kit — `.rules/` bị xóa trắng và ghi lại từ trung tâm mỗi lần update. Merge memory vào `.rules/` sẽ khiến tri thức dự án tích lũy bị wipe ở lần update kế tiếp.
+
+**Quy tắc ưu tiên khi recall:** nếu memory mâu thuẫn với `.rules/`, `.rules/` thắng — báo mâu thuẫn để người xử lý.
+
+```
+Hội thoại/task → Luồng LƯU TRỮ (PM approve)
+                        │
+        pattern lặp lại ≥2 ticket, mang tính quy chuẩn?
+                        │
+     ┌──────────────────┴────────────────────────┐
+     ▼                                            ▼
+Chỉ đúng cho dự án này               Đúng cho mọi dự án cùng stack
+→ giữ ở 99.Memory/00.Shared/          → TL chắt lọc (Flow B) → MR vào
+                                        custom/rules|skills của kit,
+                                        AI Testing Team duyệt → ak update
+                                        lan ra mọi dự án; bản gốc được
+                                        đưa vào Luồng GỠ BỎ
+```
+
+**`99.Memory` là vườn ươm, `.rules` là nơi luật đã trưởng thành.**
+
+---
+
+## 7. Kế Thừa Từ Memory Của Các AI Tools Hiện Có
+
+### 7.1 Claude Memory — kế thừa FORMAT, không kế thừa NƠI LƯU
+
+Claude Code có 2 tầng memory native: **CLAUDE.md** (curated context, load mỗi session) và **Auto Memory** (`~/.claude/projects/<hash>/memory/`: `MEMORY.md` index + mỗi fact 1 file markdown có frontmatter, Claude tự đọc/ghi qua session).
+
+| Khía cạnh | Claude Auto Memory | Yêu cầu của ta | Kết luận |
+|---|---|---|---|
+| Format (index + 1 fact/file markdown + frontmatter) | ✅ | ✅ | **Kế thừa nguyên** — `99.Memory/` (mục 3.2) chính là pattern này |
+| Nơi lưu | `~/.claude/` — per-machine, per-user | Team-shared, cross-role, git-sync | ❌ Không kế thừa |
+| Kiểm duyệt | Không có | Bắt buộc (Luồng LƯU TRỮ) | ❌ Không kế thừa |
+| Trace nguồn gốc | Không | Bắt buộc (`source`) | ❌ Không kế thừa |
+
+**Cách chung sống:** Claude Auto Memory tiếp tục chạy cho tri thức *cá nhân*; tri thức *dự án* bắt buộc đi qua Luồng LƯU TRỮ vào `99.Memory/`. CLAUDE.md chỉ dẫn rõ điều này để tránh tri thức dự án rơi vào silo per-user.
+
+### 7.2 Các AI tools khác
+
+| Tool | Cơ chế memory | Đặc điểm | Dùng được gì cho ta |
+|---|---|---|---|
+| **Cursor** | `.cursor/rules` + Memories (tự sinh từ chat) | Memories per-user, không review; Rules git-sync được | Rules ≈ `.rules/` của kit |
+| **Gemini CLI** | `GEMINI.md` + `/memory add` | Chỉ context file tĩnh, không learned memory + duyệt | Kit đã sinh `GEMINI.md` — trỏ thêm về `99.Memory/` |
+| **Windsurf** | Rules + Memories | Per-user, giống Cursor | — |
+| **Cline** | "Memory Bank" — file markdown trong repo | Git-based — gần thiết kế của ta nhất, nhưng không có pending/review/role/confidence | Xác nhận hướng markdown-in-git là đúng |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | Instruction tĩnh | — |
+| **mem0 / Letta / Zep / MCP memory server** | Vector/graph, semantic search | Mạnh recall ngữ nghĩa, cần infra, khó review/trace | Ứng viên Phase 3 khi memory >200 file — chỉ làm lớp index phụ |
+
+**Kết luận:** ngành hội tụ về 2 pattern — instruction file tĩnh (git-sync, không tự học) và auto-learned memory (tự học nhưng per-user, không duyệt). **Chưa tool nào ship sẵn "team-shared memory có review"** — đúng phần ta cần tự xây. Vì `99.Memory/` là markdown thuần trong git nên **tool-agnostic**: cùng một kho phục vụ được mọi assistant mà kit hỗ trợ (Claude, Cursor, Gemini...).
+
+---
+
+## 8. Lộ Trình Triển Khai
+
+### Phase 1 — Quick wins (~1 tuần)
+
+1. Template `99.Memory/` (mục 3.2, 5.3); `ak init` tạo skeleton + config + entry `.gitignore` cho `_pending/` (local-only, không bao giờ push) (Luồng KHỞI TẠO).
+2. Viết module memory-load **mới** cho `99.Memory/` (markdown + frontmatter) và wire vào `session-start.js` với 3 lớp load (Luồng NẠP, mục 5.2). Kho JSON cũ `.aiflow/memory/` và các lệnh `aiflow memory save/get/search` **khai tử** — chỉ kế thừa ý tưởng scorer từ `scripts/memory.js`, không tái dùng code.
+3. Thêm bước "Retrospect + đề xuất memory" vào Gate cuối của cả 4 workflow (Luồng LƯU TRỮ); lệnh `ak memory submit` tạo branch + MR; setup GitLab: protected `main`, approval rule PM, CODEOWNERS, MR template (mục 5.1).
+
+> **Rollout:** hook `session-start.js` được copy vào từng project khi `ak init`/`ak update` (`scripts/init.js`) — logic memory mới chỉ có hiệu lực sau khi mọi project trong PILOT chạy `ak update`. Đưa bước này vào checklist triển khai PILOT.
+
+### Phase 2 — Tự động hóa capture (~2-3 tuần)
+
+4. Lệnh `ak memory sync` (chủ động, người dùng tự chạy khi muốn) — full scan nếu là lần đầu, incremental nếu các lần sau (Luồng KHỞI TẠO).
+5. Port `PreCompact`/`SessionEnd` hook từ ECC `hooks/memory-persistence/` (Luồng LƯU TRỮ, trigger tự động).
+6. Lệnh ghi nhớ nhanh (`/remember`); scorer đầy đủ + profiles theo role (Luồng NẠP).
+7. Staleness check cho memory có `refs` (mục 5.4): hook so `git diff` với `verified_commit`, flag `stale`, cảnh báo khi recall.
+8. CI pipeline cho AK-Docs (mục 5.1): job `memory-lint` + job `memory-finalize`.
+9. `ak memory` lệnh đề xuất gỡ (Luồng GỠ BỎ) + soft/hard remove trên GitLab.
+
+### Phase 3 — Học tập nâng cao
+
+10. Port `continuous-learning-v2` scope hẹp (chỉ observe Gate 3-4 của Dev), instinct vào `_pending/`.
+11. `ak memory consolidate`: dedup, hit count, confidence/decay; sinh candidate cho cả Luồng GỠ BỎ và Flow B (promotion cho TL); promote pattern ≥2 dự án lên Shared-Docs.
+12. Khi memory > ~200 file: cân nhắc search ngữ nghĩa (embedding local hoặc MCP memory server) — storage gốc vẫn markdown/git.
+
+### Metric đo trong PILOT
+
+- Số lần AI trích dẫn memory trong Gate 1 / tổng số task.
+- Số memory approve mỗi sprint; tỷ lệ approve/reject (chất lượng đề xuất).
+- Số memory bị gỡ và lý do (đo chất lượng dọn dẹp, không phải thất bại).
+- Số lần lesson ngăn được lỗi lặp lại (reference trong Gate review doc).
+- Tokens memory inject/session (giữ < 5% context).
+- Tuổi trung bình hàng đợi `_pending/` và thời gian từ draft → approve (đo nghẽn duyệt của PM — rủi ro vận hành lớn nhất của thiết kế này).
+- Tỷ lệ memory `stale` được verify lại (đo cơ chế chống lỗi thời mục 5.4 có thực sự chạy).
+
+---
+
+## Phụ Lục — File/Đường Dẫn Liên Quan
+
+| Thành phần | Đường dẫn |
+|---|---|
+| Memory CLI cũ (legacy — khai tử, không liên quan `99.Memory/`; chỉ kế thừa ý tưởng scorer) | `scripts/memory.js` |
+| Session hooks đang cài vào project | `scripts/hooks/session-start.js`, `scripts/hooks/session-stop.js` |
+| Cơ chế sync AK-Docs / Shared-Docs | `scripts/docs-repo.js`, `scripts/init.js` |
+| Logic wipe `.rules/` khi update | `scripts/init.js:189-191` |
+| Rules nguồn của kit | `custom/rules/` (common + java/javascript/php) |
+| ECC continuous-learning-v2 | `everything-claude-code/skills/continuous-learning-v2/` |
+| ECC memory-persistence hooks | `everything-claude-code/hooks/memory-persistence/` |
+| ECC knowledge-ops | `everything-claude-code/skills/knowledge-ops/SKILL.md` |
+| Phân tích adoption ECC | `upgrade-plan/everything-claude-code-analysis.md` |
+
+---
+
+*Tài liệu này tổng hợp kết quả khảo sát hiện trạng memory của AI Flow Kit và thiết kế 4 luồng vận hành chính: Khởi tạo, Lưu trữ, Nạp/Sử dụng, Gỡ bỏ. Mọi thắc mắc liên hệ AI Testing Team.*