@mrtrinhvn/ag-kit 1.3.1 → 1.4.0

package/template/.agent/knowledge/ag-kit-ecosystem.md

@@ -0,0 +1,168 @@
+# 🌌 AG-KIT ECOSYSTEM — Định Danh & Bản Đồ Hệ Sinh Thái
+
+> **Đây là tài liệu cốt lõi bắt buộc phải đọc khi khởi động bất kỳ project nào thuộc hệ sinh thái ag-kit.**
+
+---
+
+## 1. AG-KIT LÀ GÌ?
+
+**ag-kit (Antigravity Kit)** là một framework tư nhân — bộ tiêu chuẩn vận hành AI Agents — được thiết kế và sở hữu bởi **một cá nhân duy nhất (Owner)**.
+
+Nó **KHÔNG phải** một open-source framework cho cộng đồng. Nó là **"bộ não chỉ huy"** giúp Owner vận hành và tự động hóa toàn bộ hệ thống AI của mình trên nhiều dự án.
+
+```
+ag-kit = Tiêu chuẩn + Công cụ + Bộ nhớ + Quy tắc
+         cho mọi AI Agent trong hệ sinh thái của Owner
+```
+
+---
+
+## 2. CẤU TRÚC HỆ SINH THÁI
+
+```
+/home/tao/Projects/                ← Workspace của Owner
+│
+├── ag-kit/                        ← 🌱 TEMPLATE GỐC (đây)
+│   └── template/.agent/           ← Bản mẫu chuẩn cho mọi project mới
+│
+├── ceogravity/                    ← 🤖 Orchestrator chính
+│   └── .agent/                    ← Clone từ ag-kit, đã tùy chỉnh
+│
+├── chungkhoan/                    ← 📈 Trading Engine
+│   └── .agent/
+│
+├── <project-N>/                   ← Mọi dự án tương lai
+│   └── .agent/                    ← Đều dùng chung chuẩn ag-kit
+│
+└── ~/.config/ag-kit/
+    └── projects.json              ← 📋 Registry toàn bộ projects
+```
+
+**Nguyên tắc:** Mọi project đều dùng chung **cùng một bộ não** (skills, protocols), nhưng có **dữ liệu riêng biệt** (memory, brain, soul).
+
+---
+
+## 3. BỘ NHỚ 3 TẦNG (Universal Memory Stack)
+
+Mỗi project trong hệ sinh thái có bộ nhớ theo chuẩn ag-kit:
+
+```
+TẦNG 3 — KNOWLEDGE BASE (.agent/knowledge/*.md)
+  Sự thật vĩnh cửu — Git-tracked — AI đọc tự động khi khởi động
+  Nội dung: kiến trúc, quy tắc, patterns đã phê duyệt
+
+TẦNG 2 — WORKING MEMORY GRAPH (.agent/memory/graph.db)
+  Hot nodes (tức thì) → Cold nodes (tổng hợp định kỳ)
+  AI truy cập qua: MCP tools (memory_save, memory_search...)
+  .gitignore — Local only — Auto GC
+
+TẦNG 1 — CODEBASE INDEX (.agent/cache/repomap.json)
+  Sơ đồ function/class — Auto-rebuild khi code đổi
+  .gitignore — Local only
+
+AUTO-BRAIN (.agent/brain/summary.md)
+  Tổng hợp từ cả 3 tầng — Auto-rebuild sau git commit
+  .gitignore — Local only
+
+### Chiến lược "Dual-Model Coordination" (Zero-API-Cost Memory)
+Thay vì dùng LLM khổng lồ (Gemini/Claude) để nhúng Vector, hệ sinh thái `ag-kit` phân cực rõ ràng:
+1. **Ollama Local (nomic-embed-text)**: Tự động chạy ngầm ở dưới để chuyển đổi Text → Toán học (Embedding Vector). Tốc độ mili-giây, tốn 0 đồng API, không kết nối internet.
+2. **LLM Cloud (Gemini/Claude)**: Khai thác kết quả của Vector Search (Semantic) để suy luận và code.
+→ Đây là cốt lõi để làm bộ não "giá rẻ nhưng thông thái".
+```
+
+---
+
+## 4. CÔNG CỤ CHUẨN (Standard Toolset)
+
+Mọi project có sẵn trong `.agent/scripts/`:
+
+| Script | Chức năng | Trigger |
+|---|---|---|
+| `memory_mcp_server.py` | MCP Server: AI gọi memory tools trực tiếp | Antigravity load khi khởi động |
+| `memory_tool.py` | CLI: `save/search/hot/cold/consolidate/gc` | Thủ công hoặc từ scripts |
+| `brain_builder.py` | Tổng hợp 3 tầng → `summary.md` | Auto: git post-commit + session start |
+| `refresh_brain.sh` | Rebuild Tầng 1 (repomap) | Thủ công khi cần |
+| `repomap.py` | Scanner code structure → JSON | Được gọi bởi refresh_brain.sh |
+| `backup_brain.sh` | Backup `brain_v1.json` 7 ngày | Chạy định kỳ |
+
+---
+
+## 5. MCP MEMORY SERVER
+
+Mỗi project đăng ký `ag-kit-memory` MCP server vào `~/.gemini/antigravity/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ag-kit-memory": {
+      "command": "/usr/bin/python3",
+      "args": [
+        "<PROJECT_ROOT>/.agent/scripts/memory_mcp_server.py",
+        "--db", "<PROJECT_ROOT>/.agent/memory/graph.db"
+      ]
+    }
+  }
+}
+```
+
+**8 tools AI có thể gọi native:**
+- `memory_save` — Ghi hot node ngay lập tức
+- `memory_search` — Tìm kiếm theo keyword (hot + cold)
+- `memory_link` — Tạo edge (quan hệ) giữa 2 nodes
+- `memory_graph` — Xem graph quanh 1 node
+- `memory_hot` — Liệt kê hot (working memory)
+- `memory_cold` — Liệt kê cold (long-term summaries)
+- `memory_consolidate` — Gộp hot → cold (định kỳ hàng tuần)
+- `memory_status` — Thống kê DB
+
+---
+
+## 6. QUY TRÌNH CROSS-PROJECT (Xem Bộ Não Dự Án Khác)
+
+Khi đang làm việc ở Project A và cần hiểu Project B:
+
+```
+1. Đọc registry:  ~/.config/ag-kit/projects.json  → tìm brain_path của B
+2. Đọc brain:     <B>/.agent/brain/summary.md      → hiểu B trong 500 tokens
+3. Nếu cần sâu:   Gọi memory_search tại DB của B  → semantic context
+4. KHÔNG được:    Scan toàn bộ folder B khi chưa đọc summary.md
+```
+
+---
+
+## 7. LUẬT BẤT BIẾN CỦA HỆ SINH THÁI
+
+1. **Không bao giờ ghi dữ liệu nghiệp vụ của Project vào ag-kit core template.**
+2. **Mỗi project có một bộ não (graph.db) riêng — không chia sẻ DB giữa projects.**
+3. **Mọi pattern học được từ project này → phải tổng quát hóa trước khi đưa vào template.**
+4. **`brain_v1.json` và dữ liệu sống KHÔNG bao giờ được push lên Git.**
+5. **Memory MCP server phải được đăng ký cho từng project, trỏ đúng DB path.**
+
+---
+
+## 8. KHỞI ĐỘNG PROJECT MỚI (Bootstrap Protocol)
+
+Khi anh muốn thêm một project mới vào hệ sinh thái:
+
+```bash
+# 1. Copy template
+cp -r /home/tao/Projects/ag-kit/template/.agent <new-project>/
+
+# 2. Đăng ký MCP memory server (thay PROJECT_ROOT)
+# Sửa ~/.gemini/antigravity/mcp_config.json
+
+# 3. Chạy brain builder lần đầu
+cd <new-project>
+python3 .agent/scripts/brain_builder.py --update
+
+# 4. Cài git hook
+cp .agent/scripts/_post-commit-hook .git/hooks/post-commit
+chmod +x .git/hooks/post-commit
+
+# → Project sẵn sàng, có não, có memory, tự động cập nhật
+```
+
+---
+
+*Hệ sinh thái này là tài sản riêng của Owner. Mọi Agent hoạt động trong đây đều phải tôn trọng nguyên tắc biệt lập, không ô nhiễm chéo, và tự cập nhật tri thức liên tục.*

package/template/.agent/knowledge/ag-kit-elite.md

@@ -14,9 +14,12 @@ This document defines the advanced agentic standards for Antigravity, synthesize
 - **CodeAct Paradigm**: Use `codeact-executor` to write and run scripts in `/tmp` to resolve complex diagnostics before applying fixes.
 - **TDD Loop**: Always run tests and fix autonomously using the 8-stage refinement loop.
 
-## 4. Infrastructure & Accessibility (The "Command Center")
-- **Headless Mode**: Run Antigravity in the background for purely agentic workloads.
-- **Remote QR Access**: Use the Cloudflare Tunnel and QR auto-login for 0-config mobile/remote control.
+## 4. Context Containment & Pattern Extraction
+- **Smart Learning**: Bạn được phép học giải pháp từ các dự án khác trong `/home/tao/Projects/` nhưng PHẢI đảm bảo tính tổng quát hóa.
+- **Protocol 3-Bước**: **Quan sát (Bản gốc) -> Lọc bỏ từ khóa riêng (Sanitize) -> Nhân bản chuẩn (Model Pattern)**.
+- **Phân tách Linh hồn & Thể xác**: 
+    - **Linh hồn (Soul - Local Only):** Các winrate, tên hàm nghiệp vụ lẻ, rulesets riêng biệt. 
+    - **Kiến trúc (Architecture - Shared):** Các patterns hạ tầng ( Watchdog, Logger, API wrapper). PHẢI ĐƯỢC TỔNG QUÁT HÓA khi đưa vào Template.
 
 ---
 > *Antigravity Elite: Synthesized Intelligence for High-Precision Development.*

package/template/.agent/knowledge/context_isolation.md

@@ -0,0 +1,16 @@
+# 🛡️ Smart Learning & Pattern Extraction
+
+As an AI Agent operating within the `ag-kit` framework, you are encouraged to use the entire workspace (`/home/tao/Projects/`) as a **Library of Patterns**, but your current repository remains your **Primary Context**.
+
+## 1. The Multi-Project Library
+- **Permission to Observe**: You ARE allowed to look at neighbor projects to research how similar features were implemented.
+- **Extraction over Copying**: Do not blindly copy-paste code containing project-specific terminology (B1/B2, DNSE, etc.). Instead, extract the **Universal Pattern**.
+- **Ask First**: If you find a major architectural solution in project X that you want to bring into project Y, ask the operator: *"I found a relevant pattern in project X, may I generalize and apply it here?"*
+
+## 2. Generalization & Sanitization
+- **Strip Context**: Remove all business-specific names, IDs, and logic weights.
+- **Standardize**: Convert the logic into a parameterized, reusable structure.
+- **Protect the Soul**: Keep project-unique data (`brain_v1.json`, specific winrates) strictly within their respective folders.
+
+---
+*Identity: I am an Antigravity Agent. I learn from the whole ecosystem but I protect the integrity of the local repo.*

package/template/.agent/scripts/_post-commit-hook

@@ -0,0 +1,8 @@
+#!/bin/bash
+# post-commit hook — Auto-rebuild project brain silently after every commit
+# Install: cp .agent/scripts/_post-commit-hook .git/hooks/post-commit && chmod +x .git/hooks/post-commit
+SCRIPT="$(git rev-parse --show-toplevel)/.agent/scripts/brain_builder.py"
+if [ -f "$SCRIPT" ]; then
+    python3 "$SCRIPT" --quick > /dev/null 2>&1 &
+fi
+exit 0

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

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""
+brain_builder.py — Auto-Brain Generator (Ag-Kit Standard)
+
+Synthesizes a project's brain by reading:
+  - Tầng 1: .agent/cache/repomap.json (codebase structure)
+  - Tầng 2: .agent/memory/graph.db (working memory, top decisions)
+  - Tầng 3: .agent/knowledge/*.md (architecture rules)
+  - Project metadata: package.json / .env
+
+Output:
+  - .agent/brain/summary.md  (human+AI readable — primary brain file)
+  - .agent/brain/index.json  (machine-readable metadata for global registry)
+  - ~/.config/ag-kit/projects.json (global registry for cross-project discovery)
+
+Auto-triggered by:
+  - git post-commit hook
+  - receptionist_up.sh (on session start)
+
+Usage:
+  python3 .agent/scripts/brain_builder.py [--root PROJECT_DIR] [--quick] [--update]
+  --quick: only rebuild if source files changed since last brain update
+  --update: force rebuild
+"""
+
+import argparse
+import json
+import os
+import re
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+
+GLOBAL_REGISTRY = Path.home() / ".config" / "ag-kit" / "projects.json"
+
+
+# ─── Helpers ─────────────────────────────────────────────────────────────────
+
+def read_file_safe(path: Path, max_chars=8000) -> str:
+    try:
+        text = path.read_text(encoding="utf-8")
+        if len(text) > max_chars:
+            text = text[:max_chars] + f"\n\n...[truncated at {max_chars} chars]"
+        return text
+    except Exception:
+        return ""
+
+
+def read_json_safe(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def get_project_name(root: Path) -> str:
+    pkg = read_json_safe(root / "package.json")
+    if pkg.get("name"):
+        return pkg["name"]
+    return root.name
+
+
+def get_tech_stack(root: Path) -> list[str]:
+    stack = []
+    if (root / "package.json").exists():
+        pkg = read_json_safe(root / "package.json")
+        deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+        if "typescript" in deps:
+            stack.append("TypeScript")
+        if "next" in deps:
+            stack.append("Next.js")
+        if "react" in deps:
+            stack.append("React")
+        if "express" in deps:
+            stack.append("Express")
+        if "fastify" in deps:
+            stack.append("Fastify")
+        if not stack:
+            stack.append("Node.js")
+    if (root / "requirements.txt").exists() or (root / "pyproject.toml").exists():
+        stack.append("Python")
+    if (root / "Cargo.toml").exists():
+        stack.append("Rust")
+    if (root / "go.mod").exists():
+        stack.append("Go")
+    return stack or ["Unknown"]
+
+
+def get_memory_nodes(root: Path, limit=8) -> list[str]:
+    db_path = root / ".agent" / "memory" / "graph.db"
+    if not db_path.exists():
+        return []
+    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]
+    except Exception:
+        return []
+
+
+def get_knowledge_summary(root: Path) -> str:
+    knowledge_dir = root / ".agent" / "knowledge"
+    if not knowledge_dir.exists():
+        return "_No knowledge files found._"
+    parts = []
+    for md in sorted(knowledge_dir.glob("*.md"))[:6]:
+        content = read_file_safe(md, max_chars=800)
+        # Extract first meaningful paragraph
+        lines = [l.strip() for l in content.splitlines() if l.strip() and not l.startswith("#")]
+        snippet = " ".join(lines[:3])[:300]
+        parts.append(f"**{md.stem}**: {snippet}")
+    return "\n".join(parts) if parts else "_Empty._"
+
+
+def get_repomap_summary(root: Path) -> str:
+    cache = root / ".agent" / "cache" / "repomap.json"
+    if cache.exists():
+        data = read_json_safe(cache)
+        lines = data.get("lines", [])
+        # Return first 40 lines of the map
+        return "\n".join(lines[:40]) or "_Empty._"
+    # Fallback: try running repomap directly (quick scan, 50 files max)
+    repomap_script = root / ".agent" / "scripts" / "repomap.py"
+    if repomap_script.exists():
+        import subprocess
+        try:
+            result = subprocess.run(
+                ["python3", str(repomap_script), str(root), "--max-files", "50"],
+                capture_output=True, text=True, timeout=15
+            )
+            lines = result.stdout.splitlines()[:40]
+            return "\n".join(lines) or "_Could not scan._"
+        except Exception:
+            pass
+    return "_RepoMap not available. Run: bash .agent/scripts/refresh_brain.sh_"
+
+
+def get_env_ports(root: Path) -> dict:
+    env_file = root / ".env"
+    ports = {}
+    if env_file.exists():
+        for line in env_file.read_text().splitlines():
+            if "PORT" in line and "=" in line:
+                k, _, v = line.partition("=")
+                ports[k.strip()] = v.strip().split("#")[0].strip()
+    return ports
+
+
+def needs_rebuild(root: Path) -> bool:
+    """Check if any source changed since last brain generation."""
+    brain_file = root / ".agent" / "brain" / "summary.md"
+    if not brain_file.exists():
+        return True
+    last_build = brain_file.stat().st_mtime
+    check_dirs = [
+        root / ".agent" / "knowledge",
+        root / "src",
+        root / "backend",
+    ]
+    for d in check_dirs:
+        if not d.exists():
+            continue
+        for f in d.rglob("*.md"):
+            if f.stat().st_mtime > last_build:
+                return True
+        for f in d.rglob("*.ts"):
+            if f.stat().st_mtime > last_build:
+                return True
+    return False
+
+
+# ─── Core Builder ────────────────────────────────────────────────────────────
+
+def build_brain(root: Path) -> tuple[str, dict]:
+    name = get_project_name(root)
+    stack = get_tech_stack(root)
+    ports = get_env_ports(root)
+    memory_nodes = get_memory_nodes(root)
+    knowledge = get_knowledge_summary(root)
+    repomap = get_repomap_summary(root)
+    now = datetime.now().strftime("%Y-%m-%d %H:%M")
+
+    port_str = " | ".join(f"{k}={v}" for k, v in ports.items()) if ports else "See .env"
+    mem_str = "\n".join(f"  - {n}" for n in memory_nodes) if memory_nodes else "  _(No decisions recorded yet)_"
+
+    summary = f"""# 🧠 Project Brain: {name}
+> Auto-generated by ag-kit brain_builder | Last updated: {now}
+> Root: {root}
+
+---
+
+## 1. Identity (Định danh)
+- **Project**: {name}
+- **Stack**: {', '.join(stack)}
+- **Root**: `{root}`
+- **Ports**: {port_str}
+
+---
+
+## 2. Codebase Structure (Tầng 1 — Repomap)
+```
+{repomap}
+```
+
+---
+
+## 3. Architecture & Rules (Tầng 3 — Knowledge Base)
+{knowledge}
+
+---
+
+## 4. Recent Decisions (Tầng 2 — Working Memory)
+{mem_str}
+
+---
+
+## 5. How to Read This Brain (Cross-Project Usage)
+If you are an AI Agent working in ANOTHER project and need to understand **{name}**:
+1. Read this file — it gives a complete overview in ~500 tokens.
+2. For deeper code context: `vfs {root}/src`
+3. For live memory: `python3 {root}/.agent/scripts/memory_tool.py search <keyword>`
+
+---
+_Auto-generated. Do not edit manually — changes will be overwritten on next rebuild._
+"""
+
+    index = {
+        "name": name,
+        "root": str(root),
+        "stack": stack,
+        "ports": ports,
+        "brain_path": str(root / ".agent" / "brain" / "summary.md"),
+        "updated_at": now,
+    }
+    return summary, index
+
+
+def update_global_registry(index: dict):
+    GLOBAL_REGISTRY.parent.mkdir(parents=True, exist_ok=True)
+    registry = {}
+    if GLOBAL_REGISTRY.exists():
+        try:
+            registry = json.loads(GLOBAL_REGISTRY.read_text())
+        except Exception:
+            pass
+    registry[index["name"]] = index
+    GLOBAL_REGISTRY.write_text(json.dumps(registry, indent=2, ensure_ascii=False))
+
+
+def write_brain(root: Path, summary: str, index: dict):
+    brain_dir = root / ".agent" / "brain"
+    brain_dir.mkdir(parents=True, exist_ok=True)
+    (brain_dir / "summary.md").write_text(summary, encoding="utf-8")
+    (brain_dir / "index.json").write_text(json.dumps(index, indent=2, ensure_ascii=False))
+
+
+# ─── Main ────────────────────────────────────────────────────────────────────
+
+def main():
+    p = argparse.ArgumentParser(description="Ag-Kit Brain Builder — Auto-generate project brain.")
+    p.add_argument("--root", default=".", help="Project root directory (default: current dir)")
+    p.add_argument("--quick", action="store_true", help="Skip rebuild if no source changes detected")
+    p.add_argument("--update", action="store_true", help="Force rebuild (default behavior)")
+    args = p.parse_args()
+
+    root = Path(args.root).resolve()
+
+    if args.quick and not needs_rebuild(root):
+        print(f"⚡ Brain is up-to-date for: {root.name} (use --update to force)")
+        return
+
+    print(f"🧠 Building brain for: {root.name}...")
+    summary, index = build_brain(root)
+    write_brain(root, summary, index)
+    update_global_registry(index)
+
+    brain_path = root / ".agent" / "brain" / "summary.md"
+    print(f"✅ Brain saved: {brain_path}")
+    print(f"📋 Global registry updated: {GLOBAL_REGISTRY}")
+
+
+if __name__ == "__main__":
+    main()