@mrtrinhvn/ag-kit 1.4.12 → 1.5.2

package/template/.agent/scripts/brain_builder.py

@@ -88,18 +88,33 @@ def get_tech_stack(root: Path) -> list[str]:
 
 def get_memory_nodes(root: Path, limit=8) -> list[str]:
     db_path = root / ".agent" / "memory" / "graph.db"
-    if not db_path.exists():
-        return []
+    nodes = []
+    if db_path.exists():
+        try:
+            conn = sqlite3.connect(str(db_path))
+            rows = conn.execute(
+                "SELECT content, category FROM nodes ORDER BY energy DESC, updated_at DESC LIMIT ?",
+                (limit,)
+            ).fetchall()
+            conn.close()
+            nodes = [f"[{r[1]}] {r[0][:120]}" for r in rows]
+        except Exception:
+            pass
+            
+    # Tự động hút thành tựu (Trò trống) từ Git Log để AI Không bao giờ quên!
+    import subprocess
     try:
-        conn = sqlite3.connect(str(db_path))
-        rows = conn.execute(
-            "SELECT content, category FROM nodes ORDER BY energy DESC, updated_at DESC LIMIT ?",
-            (limit,)
-        ).fetchall()
-        conn.close()
-        return [f"[{r[1]}] {r[0][:120]}" for r in rows]
+        git_log = subprocess.run(
+            ["git", "log", "-n", "3", "--pretty=format:- %s (%cr)"],
+            cwd=str(root), capture_output=True, text=True, timeout=5
+        )
+        if git_log.stdout:
+            nodes.insert(0, "\n**[Auto-Git-Memory] Thành tựu gần nhất:**\n" + git_log.stdout + "\n")
     except Exception:
-        return []
+        pass
+        
+    return nodes
+
 
 
 def get_knowledge_summary(root: Path) -> str:

package/template/.agent/scripts/memory_mcp_server.py

@@ -66,6 +66,11 @@ def cosine_similarity(v1: bytes, v2: bytes) -> float:
 
 
 # ─── DB ────────────────────────────────────────────────────────────────────
+def resolve_db_path(args: dict, fallback_db: Path) -> Path:
+    workspace_path = args.get("workspace_path")
+    if workspace_path:
+        return Path(workspace_path) / ".agent" / "memory" / "graph.db"
+    return fallback_db
 
 def get_db(db_path: Path) -> sqlite3.Connection:
     db_path.parent.mkdir(parents=True, exist_ok=True)
@@ -110,7 +115,8 @@ def _ensure_schema(conn):
 
 # ─── Tool Implementations ──────────────────────────────────────────────────
 
-def tool_memory_save(args: dict, db: Path) -> str:
+def tool_memory_save(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     content = args.get("content", "").strip()
     if not content: return "❌ content is required"
     category = args.get("category", "general")
@@ -131,7 +137,8 @@ def tool_memory_save(args: dict, db: Path) -> str:
     return f"✅ {emb_status} Saved hot node #{cur.lastrowid} [{category}]: {content[:80]}"
 
 
-def tool_memory_search(args: dict, db: Path) -> str:
+def tool_memory_search(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     keyword = args.get("keyword", "").strip()
     if not keyword: return "❌ keyword is required"
     tier = args.get("tier")
@@ -186,7 +193,8 @@ def tool_memory_search(args: dict, db: Path) -> str:
     return "\n".join(lines)
 
 
-def tool_memory_link(args: dict, db: Path) -> str:
+def tool_memory_link(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     from_id = args.get("from_id")
     to_id = args.get("to_id")
     relation = args.get("relation", "related_to")
@@ -207,7 +215,8 @@ def tool_memory_link(args: dict, db: Path) -> str:
     return f"🔗 #{from_id} --[{relation}]--> #{to_id}\n  From: {a['content'][:60]}\n  To: {b['content'][:60]}"
 
 
-def tool_memory_graph(args: dict, db: Path) -> str:
+def tool_memory_graph(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     node_id = args.get("node_id")
     if not node_id: return "❌ node_id is required"
     conn = get_db(db)
@@ -229,7 +238,8 @@ def tool_memory_graph(args: dict, db: Path) -> str:
     return "\n".join(out)
 
 
-def tool_memory_hot(args: dict, db: Path) -> str:
+def tool_memory_hot(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     limit = int(args.get("limit", 10))
     conn = get_db(db)
     rows = conn.execute(
@@ -245,7 +255,8 @@ def tool_memory_hot(args: dict, db: Path) -> str:
     return "\n".join(lines)
 
 
-def tool_memory_cold(args: dict, db: Path) -> str:
+def tool_memory_cold(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     limit = int(args.get("limit", 10))
     conn = get_db(db)
     rows = conn.execute(
@@ -262,7 +273,8 @@ def tool_memory_cold(args: dict, db: Path) -> str:
     return "\n".join(lines)
 
 
-def tool_memory_consolidate(args: dict, db: Path) -> str:
+def tool_memory_consolidate(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     days = int(args.get("days", 7))
     category = args.get("category")
     threshold = (datetime.now() - timedelta(days=days)).isoformat()
@@ -307,7 +319,8 @@ def tool_memory_consolidate(args: dict, db: Path) -> str:
     return "\n".join(results) + f"\n\n✅ Done. Summary vectors calculated."
 
 
-def tool_memory_status(args: dict, db: Path) -> str:
+def tool_memory_status(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     conn = get_db(db)
     total = conn.execute("SELECT COUNT(*) FROM nodes").fetchone()[0]
     hot = conn.execute("SELECT COUNT(*) FROM nodes WHERE tier='hot'").fetchone()[0]
@@ -334,6 +347,7 @@ TOOLS = {
         "inputSchema": {
             "type": "object",
             "properties": {
+                "workspace_path": {"type": "string", "description": "Local workspace root path to avoid cross-project contamination"},
                 "content": {"type": "string", "description": "The knowledge to save"},
                 "category": {"type": "string", "enum": list(VALID_CATEGORIES), "description": "Category of knowledge"}
             },
@@ -345,6 +359,7 @@ TOOLS = {
         "inputSchema": {
             "type": "object",
             "properties": {
+                "workspace_path": {"type": "string", "description": "Local workspace root path"},
                 "keyword": {"type": "string", "description": "Keyword to search"},
                 "tier": {"type": "string", "enum": ["hot", "cold"], "description": "Search only in hot or cold tier"},
                 "limit": {"type": "integer", "description": "Max results (default 8)"}
@@ -354,13 +369,13 @@ TOOLS = {
     },
     "memory_link": {
         "description": "Create a relationship (edge) between two memory nodes.",
-        "inputSchema": {"type": "object", "properties": {"from_id": {"type": "integer"}, "to_id": {"type": "integer"}, "relation": {"type": "string"}}, "required": ["from_id", "to_id"]}
+        "inputSchema": {"type": "object", "properties": {"workspace_path": {"type": "string"}, "from_id": {"type": "integer"}, "to_id": {"type": "integer"}, "relation": {"type": "string"}}, "required": ["from_id", "to_id"]}
     },
-    "memory_graph": {"description": "Show all edges (incoming and outgoing) for a node.", "inputSchema": {"type": "object", "properties": {"node_id": {"type": "integer"}}, "required": ["node_id"]}},
-    "memory_hot": {"description": "List hot (working memory) nodes.", "inputSchema": {"type": "object", "properties": {"limit": {"type": "integer"}}}},
-    "memory_cold": {"description": "List cold (consolidated long-term memory) nodes.", "inputSchema": {"type": "object", "properties": {"limit": {"type": "integer"}}}},
-    "memory_consolidate": {"description": "Merge old hot nodes into cold consolidated summaries.", "inputSchema": {"type": "object", "properties": {"days": {"type": "integer"}, "category": {"type": "string"}}}},
-    "memory_status": {"description": "Show memory graph statistics.", "inputSchema": {"type": "object", "properties": {}}}
+    "memory_graph": {"description": "Show all edges (incoming and outgoing) for a node.", "inputSchema": {"type": "object", "properties": {"workspace_path": {"type": "string"}, "node_id": {"type": "integer"}}, "required": ["node_id"]}},
+    "memory_hot": {"description": "List hot (working memory) nodes.", "inputSchema": {"type": "object", "properties": {"workspace_path": {"type": "string"}, "limit": {"type": "integer"}}}},
+    "memory_cold": {"description": "List cold (consolidated long-term memory) nodes.", "inputSchema": {"type": "object", "properties": {"workspace_path": {"type": "string"}, "limit": {"type": "integer"}}}},
+    "memory_consolidate": {"description": "Merge old hot nodes into cold consolidated summaries.", "inputSchema": {"type": "object", "properties": {"workspace_path": {"type": "string"}, "days": {"type": "integer"}, "category": {"type": "string"}}}},
+    "memory_status": {"description": "Show memory graph statistics.", "inputSchema": {"type": "object", "properties": {"workspace_path": {"type": "string"}}}}
 }
 
 TOOL_FNS = {

package/template/.agent/skills/ag-kit-core/SKILL.md

@@ -101,25 +101,37 @@ Server `ag-kit-memory` được đăng ký sẵn trong `~/.gemini/antigravity/mc
 
 | Tool | Khi nào gọi |
 |---|---|
-| `memory_search(keyword)` | **TRƯỚC** khi bắt đầu bất kỳ task nào — kiểm tra context cũ |
-| `memory_save(content, category)` | **SAU** khi fix bug, ra quyết định, học được điều mới |
-| `memory_link(from, to, relation)` | Khi phát hiện 2 kiến thức có quan hệ |
-| `memory_consolidate(days=7)` | Hàng tuần: gộp hot → cold summaries |
-| `memory_status()` | Kiểm tra sức khỏe của bộ não |
+| `memory_search(keyword, workspace_path)` | **TRƯỚC** khi bắt đầu bất kỳ task nào — kiểm tra context cũ |
+| `memory_save(content, category, workspace_path)` | **SAU** khi fix bug, ra quyết định, học được điều mới |
+| `memory_link(from, to, relation, workspace_path)` | Khi phát hiện 2 kiến thức có quan hệ |
+| `memory_consolidate(days=7, workspace_path)` | Hàng tuần: gộp hot → cold summaries |
+| `memory_status(workspace_path)` | Kiểm tra sức khỏe của bộ não |
+
+> **⚠️ QUAN TRỌNG VỀ ISO-WORKSPACE (MANDATORY)**: Tất cả các tool của `ag-kit-memory` BẮT BUỘC phải nhận tham số `workspace_path` là đường dẫn gốc CWD hiện tại của dự án (VD: `/home/tao/Projects/chungkhoan`). Nếu không truyền, MCP sẽ ghi đè database hoặc đọc sai ký ức của dự án khác gây thảm họa ô nhiễm dữ liệu!
 
 ```
 Workflow đúng:
-  1. Bắt đầu task → memory_search("topic") → đọc context cũ
+  1. Bắt đầu task → memory_search("topic", workspace_path="/...") → đọc context cũ
   2. Làm việc...
-  3. Xong task → memory_save("kết quả/quyết định quan trịng")
-  4. Hàng tuần → memory_consolidate(days=7) → dọn rác, tổng hợp
+  3. Xong task → memory_save(content="...", workspace_path="/...")
+  4. Hàng tuần → memory_consolidate(workspace_path="/...")
 ```
 
 
 ---
 
-## 4. 🔗 THE DUO-CORE (Kiến Trúc Multi-Tenant Bắt Buộc)
-Hãy khắc cốt ghi tâm quy tắc: `IDE_PORT` (Nhận lệnh AI - ví dụ: 9555) và bước nhảy 101 để sinh ra `BRIDGE_PORT` (Portal Bridge Server - ví dụ: 9656). Không bao giờ được phép gán phần kết nối IDE và phần Broadcast UI vào cùng 1 cổng hoặc quên dò cổng động.
+## 4. 🔗 THE DUO-CORE (Kiến Trúc Multi-Tenant & Dual-Port Cơ Sở)
+Hãy khắc cốt ghi tâm quy tắc phân bổ cổng dịch vụ: `IDE_PORT` (Nhận lệnh AI - ví dụ: 9555) và bước nhảy 101 để sinh ra `BRIDGE_PORT` (Portal Bridge Server - ví dụ: 9656). Không bao giờ được phép gán phần kết nối IDE và phần Broadcast UI vào cùng 1 cổng.
+
+### 4.1. Sự khác biệt kiến trúc: Headless LSP vs CDP UI
+Mọi ứng dụng thuộc quyền quản trị của AG-KIT bắt buộc phải thẩm thấu sức mạnh của chiến thuật **Dual-Port Strategy**:
+1. **Trục xương sống (Headless LSP / DeckServer)**: Dùng cho các luồng giao tiếp AI nền ngầm định tuyến (ví dụ gọi hàm `lsGateway.startCascade()`). Đặc điểm nhận dạng:
+   - Truyền tải thông điệp siêu tốc qua RPC/Sockets mà không cần vẽ lên màn hình IDE Chat.
+   - Tránh 100% tỷ lệ xuất hiện lỗi rác (Visual Hallucination) do việc đọc màn hình dính các chữ "Generating...", "Planning...".
+   - **Sự liên kết với AG_LITE HUD**: Luồng Headless này KHÔNG có nghĩa là HUD bị mất tác dụng. Việc User chọn Model (như Gemini 1.5, hay Claude 3.5) trên HUD AG_ELITE vẫn sẽ định đoạt cái "não" nào sẽ được dùng để xử lý cái Headless Cascade đó ở hậu trường!
+2. **Xúc tu Tương tác Cơ học (CDP - Chrome DevTools Protocol)**: 
+   - KHÔNG được lạm dụng để truyền lệnh ngầm thuần túy (Text Generation) nếu API Headless LSP đã có thể đáp ứng.
+   - CHỈ ĐƯỢC DÙNG khi AI bắt buộc phải tác động trực quan (Ví dụ: Click UI web, inject bảng điều khiển HUD bằng script lơ lửng, kéo cuộn trang web (scroll), hoặc trích xuất (scrape) trạng thái hình ảnh DOM Canvas).
 
 ---
 
@@ -134,7 +146,8 @@ Hãy khắc cốt ghi tâm quy tắc: `IDE_PORT` (Nhận lệnh AI - ví dụ: 9
     3. Nếu cần đi sâu hơn: dùng `vfs <project_root>/src` hoặc `memory_tool.py search`.
     4. **CẤM** scan toàn bộ thư mục project khác khi chưa đọc `summary.md` trước.
 - **Cấm ô nhiễm (No Leakage):** Tuyệt đối không ghi chép các từ khóa chuyên biệt (B1, B2, Sentinel, DNSE...) vào các file Skill dùng chung.
-- **Tổng quát hóa (Sanitization):** Mọi pattern học được từ project A khi đưa vào Core Framework đều phải tẩy sạch tên nghiệp vụ. Trước khi trích xuất pattern lớn, hỏi Sếp: *"Em thấy pattern X ở dự án Y rất hay, em xin phép tổng quát hóa nó không?"*
+- **Thuật Biến Hình (Identity Shifting - Nhập Gia Tùy Tục):** Khi Sếp giao phó điều hướng bạn sang thao tác hoặc sửa lỗi ở một Dự Án X (trong khi bạn đang ở máy chủ Dự Án Y), **thì ngay giây phút bạn đặt chân sang thư mục nhà X, bạn PHẢI tự coi mình chính là Agent của nhà X!** 
+  - *Hành động:* Bạn nắm toàn quyền và **CÓ TRÁCH NHIỆM BẮT BUỘC** ghi chú những bài học, fix bug, và pattern trực tiếp vào cuốn sổ `.agent/knowledge/` hoặc gọi `memory_save(workspace_path="/home/tao/Projects/Dự_Án_X")` của chính nhà đó, bằng chính đặc thù ngôn ngữ của Dự Án đó (Ví dụ sang ceogravity thì cứ thoải mái gõ chữ B1, B2)! Đừng chỉ để lại lời nhắn như người dưng, hãy hành xử như một người quản gia thực thụ của bất kỳ dự án nào bạn được đưa tới. Mọi giá trị tri thức phải được gửi gắm chính xác vào Local Context của nơi nó nảy mầm.
 
 ---
 
@@ -152,3 +165,14 @@ Hệ sinh thái `ag-kit` được cung cấp sức mạnh cài đặt và cập
 2. **Trạm Khởi Tạo Tốc Độ Cao (create-ag-kit):**
    - Lệnh chính: `npx create-ag-kit`
    - *=> Dùng 1 Lần Đầu Tiên: Giống như create-react-app, đây là hạt giống cấy ghép nhanh toàn bộ thư mục `.agent/` và sinh ra `package.json` trống để tạo hẳn một dự án Bot hoàn toàn mới nằm cạnh nhau.*
+
+---
+
+## 7. 🧬 CLAUDE CODE AGENTIC PROTOCOL (MANDATORY)
+Dự án này đã cấy ghép MÃ GEN Tư Duy của Claude Code (v2.1.50). Tuy nhiên, để đảm bảo tính Đa Dạng Nhân Cách (Trader vs Coder), luật này chạy theo Cơ chế Phân Luồng:
+- **Ngữ cảnh Kích hoạt:** CHỈ áp dụng các luật dưới đây nếu User yêu cầu "Sửa code, fix bug, viết tính năng mới, /agent, /code". Nếu User hỏi phân tích dữ liệu trade, phân tích thị trường, Hãy trả lời thẳng mạch lạc như bình thường!
+- **Khi đã ở chế độ Kích hoạt (Agent Mode), PHẢI rập khuôn 3 điều luật sau:**
+
+1. **LUẬT LẬP KẾ HOẠCH (TodoWrite - Thinking Before Acting):** KHÔNG BAO GIỜ đâm đầu vào code ngay lập tức khi gặp Request lớn. Hành động ĐẦU TIÊN CỦA BẠN phải là sử dụng tính năng Planning (hoặc TodoWrite) để chẻ nhỏ Task thành Checklist `[ ]`. Suy nghĩ như Kỹ Sư Trưởng, sau đó mới dùng công cụ Replace Code.
+2. **LUẬT SỬ DỤNG TOOL (Anti-Bash Spam):** Khi đọc và trích xuất mã nguồn thư mục lớn, BẮT BUỘC dùng các công cụ thông minh (Grep, VFS, ReadFile chuyên dụng). CẤM lạm dụng Bash/Shell thô sơ (như `cat`, `head`, `find`) để duyệt file vì lãng phí Token Context VRAM trầm trọng. Chỉ dùng Bash để chạy Build hoặc Python test.
+3. **LUẬT DỪNG HỎI (EnterPlanMode):** Nếu Request liên quan đến thay đổi kiến trúc, Database, hoặc các quyết định cấu trúc thư mục, BẠN PHẢI DỪNG HOẠT ĐỘNG (Pause Execution) và Báo cáo Sếp bằng `implementation_plan.md`. Cấm hành vi "Cầm đèn chạy trước ô tô".

package/template/.agent/skills/clean-code/SKILL.md

@@ -60,6 +60,18 @@ priority: CRITICAL
 
 ---
 
+## State & Process Management Rules (MANDATORY)
+
+Để đảm bảo hệ thống không bị mắc kẹt (Ghost Sessions) khi các Service chạy trong Docker hoặc bị Reboot Host, mọi Agent **BẮT BUỘC** phải tuân thủ nghiêm ngặt 3 quy tắc sau khi viết các Background Tasks/Queues:
+
+| 🚨 Rule Nhiễm Độc | ✅ Giải pháp Chuẩn mực |
+|---|---|
+| Dùng `os.kill(pid, 0)` để kiểm tra Task còn sống | **CẤM!** PID của Docker luôn reset về thấp (VD: 1, 8), vòng lặp PID sẽ gây ra "Ghost Session". Đổi sang dùng timeout check. |
+| Lưu File Lock/PID ở `Root /tmp/` | **RỦI RO XUNG ĐỘT!** Các dự án chạy chung 1 VPS sẽ chọc nhầm PID của nhau. Bắt buộc lưu vào ranh giới nội bộ: `.agent/run/` |
+| Quên làm sạch Database Trạng thái khi Server boot | **THẢM HỌA UI!** Task đang chạy dở mà Host sập, khi khởi động lại cờ `is_running` vẫn kẹt `true`. BẮT BUỘC phải cấy hàm `reset_all_ghost_sessions()` vào sự kiện `lifespan` lúc FastAPI/Node Server khởi chạy. |
+
+---
+
 ## AI Coding Style
 
 | Situation | Action |

package/template/.agent/skills/frontend-design/SKILL.md

@@ -340,6 +340,12 @@ For animation patterns: [animation-guide.md](animation-guide.md), for advanced:
 - **Same layout structure / Vercel clone**
 - **Not asking user preferences**
 
+### ❌ Front-end Performance Anti-Patterns
+
+- **Thảm họa Polling bằng `setInterval`**: Khi Fetch API liên tục, nếu mạng chậm, các request sẽ bị kẹt dồn ứ gây ra lỗi `ERR_INSUFFICIENT_RESOURCES` sập Browser Socket. **MANDATORY**: Thay vì `setInterval`, phải dùng đệ quy `setTimeout` (Chờ request Promise A hoàn tất thì mới trigger request B).
+- Chèn trực tiếp quá nhiều thư viện nặng vào Bundle thay vì Lazy Load.
+- Không có cơ chế Debounce/Throttle cho các thẻ Input Search.
+
 ### ❌ Dark Patterns (Unethical)
 
 - Hidden costs

package/template/.agent/skills/knowledge-management/SKILL.md

@@ -14,9 +14,11 @@ allowed-tools: Read, Write, Glob, Grep
 
 **PRINCIPLE:** Never rely on assumptions or ephemeral conversation memory for project characteristics. Store them permanently.
 
-### Mandatory Read Before Action
-Before interacting with any third-party API, database schema, or core system component, you **MUST** search the `.agent/knowledge/` directory for existing documentation. 
-*Example: Before coding a payment integration feature, read `.agent/knowledge/integrations/stripe_api.md` to get the exact webhooks and payload structures.*
+### Mandatory Read Before Action (Text vs Vector Search)
+Before interacting with any third-party API, database schema, or core system component, you **MUST** actively seek out existing documentation using the CORRECT tool for the data type:
+- If retrieving explicit Markdown documentation (e.g., API schemas, strict rules), use `grep_search` or open the file directly in `.agent/knowledge/`.
+- If retrieving historical experience, bug fixes, or unstructured project configurations, you **MUST** use the MCP tool `mcp_ag-kit-memory_memory_search` (Semantic Cosine Vector Search) to scan the memory graphs.
+*Example: Use grep/file reader for reading schema in `stripe_api.md`, but strictly use `memory_search` for "how did we handle the stripe CORS error last time?".*
 
 ### Mandatory Proactive Updates (Zero Prompting Rule)
 When you successfully:

package/template/.agent/skills/mcp-builder/SKILL.md

@@ -147,6 +147,11 @@ my-mcp-server/
 | args | Command arguments |
 | env | Environment variables |
 
+### ⚠️ Database Context Mismatch (Global vs Local)
+Khi thiết kế MCP lưu trữ dữ liệu State hoặc Vector DB, phải lường trước tình huống MCP chạy ở tư cách Global (ví dụ cài qua `npm install -g` hoặc qua Claude Desktop) nhưng System Client chạy ở Local project.
+- **Rủi ro:** Lỗi "Lạc đường CSDL". MCP sẽ ghi cứng data vào biến Workspace lúc nó được start (Vd: ghi đè Database dự án A trong khi User đang thao tác bên dự án B).
+- **Giải pháp:** Server MCP cần có khả năng linh hoạt đọc `cwd` (current working directory) của Client đang tương tác, hoặc nhận đường dẫn Database rõ ràng thông qua Argument Input của Tool để chắc chắn dữ liệu được tiêm đúng vào **Local Context** của User.
+
 ---
 
 ## 9. Testing

package/template/.agent/skills/memory-architecture/SKILL.md

@@ -105,3 +105,34 @@ Khi bạn (AI) nhận thức được mình đang ở trong một dự án đã
 
 Bằng giao thức này, kiến thức của dự án sẽ KHÔNG BAO GIỜ bị đứt gãy sau khi cập nhật kiến trúc. Mọi ký ức quá khứ sẽ tự động "tiến hóa" thành dạng Đồ thị tương lai!
 
+---
+
+## 8. CHIẾN LƯỢC TRUY VẤN PHÂN CẤP: VECTOR VS TEXT (BOOTSTRAP)
+
+> **LƯU Ý:** Trí nhớ của hệ thống lưu ở hai dạng (Văn bản phẳng và Vector không gian). Bạn (AI) phải linh hoạt lựa chọn CÔNG CỤ TÌM KIẾM phù hợp với lớp dữ liệu. Không dùng lẫn lộn!
+
+**A. KHI TÌM KIẾM VĂN BẢN (TEXT/STATIC FILES):**
+Khi cần tra cứu Code Convention, API Schema, Hướng dẫn đặc tả, hoặc các file Markdown tĩnh `.md` nằm rải rác trong `knowledge`:
+👉 Hãy dùng công cụ gốc: `grep_search`, `vfs` hoặc xem trọn vẹn file (`view_file`). Vì text schema cần độ chính xác cấu trúc tuyệt đối.
+
+**B. KHI TÌM KIẾM KÝ ỨC NGỮ NGHĨA (VECTOR MEMORY):**
+Khi cần truy xuất "Kinh nghiệm fix bug cũ", "Thói quen tuỳ chỉnh dự án", hoặc "Luồng sự kiện (Graph Context)" được lưu dạng Node/Edge mà không nhớ nó nằm ở file nào:
+👉 **BẮT BUỘC** dùng thư viện MCP (Model Context Protocol) có sẵn trên Profile để thao tác bằng Vector:
+1. **Tìm kiếm (Search):** Dùng công cụ `mcp_ag-kit-memory_memory_search` với từ khóa cốt lõi. Nó sẽ dùng Cosine Similarity trả về đúng các Node có ngữ nghĩa liên quan nhất, vượt qua giới hạn của keyword match rập khuôn.
+2. **Lưu trữ (Save):** Dùng công cụ `mcp_ag-kit-memory_memory_save` khi muốn lưu lại bài học / giải pháp để sau này xài lại, tự động tính toán Embedding Vector vào không gian não.
+3. **Phân tích Luồng (Graph):** Dùng `mcp_ag-kit-memory_memory_graph` để xem các liên kết (Edges) của một sự kiện/Node cụ thể.
+
+ĐÂY LÀ TIÊU CHUẨN KÉP QUAN TRỌNG. Hãy tự hỏi: "Mình đang tìm tài liệu tĩnh hay tìm trí nhớ (trải nghiệm)?" trước khi chọn công cụ!
+
+---
+
+## 9. Công cụ Gỡ Rối Định Tuyến (Brain Debugging CLI)
+
+Trong quá trình bảo trì trí nhớ (ví dụ: cần truy vấn SQL trực tiếp để tìm kiếm Vector, xóa các Node bị kẹt bằng tay gốc rễ), bạn hoặc User **BẮT BUỘC** phải cài đặt công cụ CLI `sqlite3` trên môi trường Terminal. 
+
+Lỗi **"Command 'sqlite3' not found"** là nguyên nhân số một khiến AI Agent hoặc Developer không thể thâm nhập sâu vào file `graph.db` để debug cục bộ.
+- **Trên Ubuntu/Debian:** Yêu cầu User chạy `sudo apt install sqlite3 -y`
+- **Trên Mac (Homebrew):** Yêu cầu User chạy `brew install sqlite`
+- **Trên Windows:** Cài đặt thông qua Winget hoặc tải Binaries.
+
+> **Trách nhiệm của AI:** Trước khi chạy các kịch bản python hoặc bash để truy vấn `.agent/memory/graph.db`, hãy kiểm tra xem `sqlite3` có tồn tại trên Host không. Nếu không, hãy thông báo ngay cho User để cài đặt công cụ tối thượng này! Mọi sự cố thiếu `sqlite3` không thuộc về bộ não AG-Kit mà là lỗi thiếu Dependencies môi trường.

package/template/.agent/skills/python-patterns/SKILL.md

@@ -337,6 +337,11 @@ Celery/ARQ:
 └── Complex workflows
 ```
 
+### ⚠️ Docker Ghost Session Warning
+Khi thiết kế ứng dụng có Background task tracking lưu trữ State (VD: vào file/JSON hoặc SQLite) với cờ `is_running: true`.
+**TUYỆT ĐỐI KHÔNG** phụ thuộc hoàn toàn vào check Process ID `os.kill(pid, 0)` để xác định tiến trình còn sống hay không. Trong Docker container khi restart, hệ điều hành reset PID về thấp (VD: cấp lại PID 1, 8), kiến `os.kill` quét nhầm và gây ra kẹt trạng thái **Ghost Session**.
+**Giải pháp kiến trúc**: Gắn cơ chế ép dọn dẹp trạng thái `force_reset_all()` vào ngay `lifespan` hoặc `startup` event của FastAPI để triệt tiêu các bóng ma trước khi API online.
+
 ---
 
 ## 8. Error Handling Principles

package/template/.agent/skills/telegram-agentic-gateway/SKILL.md

@@ -86,6 +86,7 @@ Khi triển khai, hãy hướng dẫn User:
    - **Tuyệt đối KHÔNG hardcode cổng cố định (như 9555).** Hạ tầng phải hỗ trợ Scale (sinh nhiều Agent song song).
    - Hãy cấp một dải khoảng 100 cổng (Ví dụ: `9555-9655`).
    - Script khởi động (`start.sh`) phải có logic tự dò cổng nào đang trống trong dải 100 cổng này $\rightarrow$ Gán cho tiến trình Antigravity IDE $\rightarrow$ Cập nhật `.env` (`IDE_PORT=95xx`) $\rightarrow$ Kẻ điều phối (Node.js) đọc file `.env` để kết nối vào đúng IDE đó.
+   - ⚠️ **Lưu ý Networking (Docker vs Host):** Nếu Kẻ điều phối (Gateway) chạy trực tiếp trên Host (qua Node.js) sử dụng Port `9656`, còn Hệ thống Lõi xử lý NLP (Python, Backend) chạy bên trong Docker Container, thì Hệ thống Lõi KHÔNG THỂ gọi ngược ra Gateway bằng `127.0.0.1` hay `localhost`. Bắt buộc phải cấu hình biến môi trường kết nối trỏ tới **IP Bridge của Docker** (thường là `172.17.0.1` trên Linux hoặc `host.docker.internal` trên Mac/Windows). VD: `GATEWAY_URL=http://172.17.0.1:9656`. Mặc định gọi localhost sẽ văng lỗi `Connection Refused` hoặc `Failed to fetch`.
 5. **Độc Lập Tên Gọi (Project-Agnostic Naming)**:
    - Các file script điều phối (`receptionist_up.sh`, `receptionist_down.sh`...) **TUYỆT ĐỐI KHÔNG ĐƯỢC MANG TÊN DỰ ÁN CỤ THỂ** (Ví dụ cấm gõ cứng: `Waking up CEOgravity Bot` hay `.ceogravity_bot.pid`). 
    - Phải sử dụng danh xưng danh chuẩn mực là **"AG Gateway Bot"** và các file tracking trung lập (Vd: `.ag_gateway_bot.pid`). Điều này là bắt buộc để biến hệ sinh thái `.agent/` thành một Template hoàn hảo có thể bưng thả (White-label) vào bất kỳ dự án nào (NextJS, Python, Rust...) mà không bị ô nhiễm tên dự án cũ.