@mrtrinhvn/ag-kit 1.3.1 → 1.4.0

package/template/.agent/scripts/memory_tool.py

@@ -0,0 +1,367 @@
+#!/usr/bin/env python3
+"""
+memory_tool.py — Ag-Kit Two-Tier Memory System (Option B)
+
+TIER 1 (HOT) — Working Memory: Fast write/read, exact + semantic search
+  Save immediately: `save "content" --category decision`
+  Search: `search "keyword"` (uses both LIKE and Cosine Similarity if model present)
+  List hot nodes: `hot`
+
+TIER 2 (COLD) — Long-term Memory: Consolidated summaries
+  Consolidate hot → cold: `consolidate [--category X] [--days 7]`
+  Search cold tier: `cold` | `search "kw" --tier cold`
+
+EMBEDDINGS (Option B - Dual-Model Coordination):
+  Automatically calls local Ollama `nomic-embed-text` during save & search.
+  No external libraries required (pure python struct/math).
+"""
+
+import argparse
+import sqlite3
+import json
+import urllib.request
+import struct
+import math
+from pathlib import Path
+from datetime import datetime, timedelta
+
+DEFAULT_DB = Path(__file__).parent.parent / "memory" / "graph.db"
+VALID_CATEGORIES = {"user_pref", "decision", "error", "pattern", "context", "general"}
+
+
+# ─── Option B: Vector Embeddings (Ollama) ─────────────────────────────────────
+
+def get_embedding(text: str) -> bytes:
+    """Calls local Ollama nomic-embed-text and returns packed bytes."""
+    try:
+        req = urllib.request.Request(
+            "http://localhost:11434/api/embed",
+            json.dumps({"model": "nomic-embed-text", "input": text}).encode('utf-8')
+        )
+        with urllib.request.urlopen(req, timeout=10) as res:
+            data = json.loads(res.read().decode('utf-8'))
+            floats = data.get("embeddings", [[]])[0]
+            if not floats:
+                return None
+            return struct.pack(f"{len(floats)}f", *floats)
+    except Exception as e:
+        # Silently fail if Ollama is not running or model missing
+        return None
+
+def cosine_similarity(v1: bytes, v2: bytes) -> float:
+    """Computes cosine similarity between two byte-packed float vectors."""
+    if not v1 or not v2: return 0.0
+    try:
+        f1 = struct.unpack(f"{len(v1)//4}f", v1)
+        f2 = struct.unpack(f"{len(v2)//4}f", v2)
+        dot = sum(a * b for a, b in zip(f1, f2))
+        norm1 = math.sqrt(sum(a * a for a in f1))
+        norm2 = math.sqrt(sum(b * b for b in f2))
+        if norm1 == 0 or norm2 == 0: return 0.0
+        return dot / (norm1 * norm2)
+    except Exception:
+        return 0.0
+
+
+# ─── DB Setup ─────────────────────────────────────────────────────────────────
+
+def get_db(db_path: Path) -> sqlite3.Connection:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(db_path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    _init_schema(conn)
+    return conn
+
+
+def _init_schema(conn: sqlite3.Connection):
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS nodes (
+            id              INTEGER PRIMARY KEY AUTOINCREMENT,
+            content         TEXT NOT NULL,
+            category        TEXT NOT NULL DEFAULT 'general',
+            energy          INTEGER NOT NULL DEFAULT 100,
+            tier            TEXT NOT NULL DEFAULT 'hot',
+            source_ids      TEXT,           
+            embedding       BLOB,           
+            created_at      TEXT NOT NULL,
+            updated_at      TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS edges (
+            id          INTEGER PRIMARY KEY AUTOINCREMENT,
+            from_node   INTEGER NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+            to_node     INTEGER NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+            relation    TEXT NOT NULL DEFAULT 'related_to',
+            created_at  TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_nodes_category ON nodes(category);
+        CREATE INDEX IF NOT EXISTS idx_nodes_tier     ON nodes(tier);
+        CREATE INDEX IF NOT EXISTS idx_nodes_energy   ON nodes(energy);
+        CREATE INDEX IF NOT EXISTS idx_edges_from     ON edges(from_node);
+        CREATE INDEX IF NOT EXISTS idx_edges_to       ON edges(to_node);
+    """)
+    # Live migration
+    cols = [r[1] for r in conn.execute("PRAGMA table_info(nodes)").fetchall()]
+    for col, typedef in [("tier", "TEXT DEFAULT 'hot'"), ("source_ids", "TEXT"), ("embedding", "BLOB")]:
+        if col not in cols:
+            conn.execute(f"ALTER TABLE nodes ADD COLUMN {col} {typedef}")
+    conn.commit()
+
+
+# ─── HOT TIER ─────────────────────────────────────────────────────────────────
+
+def cmd_save(args, conn):
+    now = datetime.now().isoformat()
+    category = args.category if args.category in VALID_CATEGORIES else "general"
+    
+    emb = get_embedding(args.content)
+    
+    cur = conn.execute(
+        "INSERT INTO nodes (content, category, energy, tier, embedding, created_at, updated_at) VALUES (?, ?, 100, 'hot', ?, ?, ?)",
+        (args.content, category, emb, now, now)
+    )
+    conn.commit()
+    emb_status = "✨[Vector]" if emb else "⚠️[No-Vector]"
+    print(f"✅ {emb_status} Saved hot node #{cur.lastrowid} [{category}]: {args.content[:80]}")
+
+
+def cmd_hot(args, conn):
+    rows = conn.execute(
+        "SELECT id, category, energy, content, embedding, created_at FROM nodes WHERE tier='hot' ORDER BY energy DESC, updated_at DESC LIMIT ?",
+        (args.limit,)
+    ).fetchall()
+    print(f"🔥 HOT nodes ({len(rows)} shown):\n")
+    for r in rows:
+        v_mark = "✨" if r["embedding"] else " "
+        print(f" {v_mark}#{r['id']} [{r['category']}] ⚡{r['energy']} 📅{r['created_at'][:10]}")
+        print(f"     {r['content'][:120]}\n")
+
+
+# ─── CONSOLIDATION (Hot → Cold) ───────────────────────────────────────────────
+
+def cmd_consolidate(args, conn):
+    threshold_date = (datetime.now() - timedelta(days=args.days)).isoformat()
+    cat_filter = f"AND category = '{args.category}'" if args.category else ""
+
+    hot_rows = conn.execute(
+        f"SELECT id, content, category FROM nodes WHERE tier='hot' AND updated_at < ? {cat_filter} ORDER BY category, energy DESC",
+        (threshold_date,)
+    ).fetchall()
+
+    if not hot_rows:
+        print(f"⚡ No hot nodes older than {args.days} days to consolidate.")
+        return
+
+    from collections import defaultdict
+    groups = defaultdict(list)
+    for r in hot_rows:
+        groups[r["category"]].append(r)
+
+    consolidated_count = 0
+    now = datetime.now().isoformat()
+
+    for category, nodes in groups.items():
+        if len(nodes) < 2 and not args.force:
+            continue
+
+        node_ids = [r["id"] for r in nodes]
+        merged = "\n".join(f"• {r['content'][:200]}" for r in nodes[:20])
+        summary = f"[Consolidated {len(nodes)} nodes — {category}]\n{merged}"
+
+        emb = get_embedding(summary)
+
+        cur = conn.execute(
+            "INSERT INTO nodes (content, category, energy, tier, source_ids, embedding, created_at, updated_at) VALUES (?, ?, 80, 'cold', ?, ?, ?, ?)",
+            (summary, category, json.dumps(node_ids), emb, now, now)
+        )
+        cold_id = cur.lastrowid
+
+        for nid in node_ids:
+            conn.execute(
+                "INSERT INTO edges (from_node, to_node, relation, created_at) VALUES (?, ?, 'consolidated_into', ?)",
+                (nid, cold_id, now)
+            )
+            conn.execute("UPDATE nodes SET energy = MAX(0, energy - 40) WHERE id = ?", (nid,))
+
+        consolidated_count += 1
+        print(f"❄️  [COLD] '{category}': merged {len(nodes)} hot nodes → #{cold_id}")
+
+    conn.commit()
+    print(f"\n✅ Consolidation complete. Run `gc` to cleanup dead hot nodes.")
+
+
+# ─── COLD TIER ────────────────────────────────────────────────────────────────
+
+def cmd_cold(args, conn):
+    rows = conn.execute(
+        "SELECT id, category, energy, content, source_ids, updated_at FROM nodes WHERE tier='cold' ORDER BY energy DESC, updated_at DESC LIMIT ?",
+        (args.limit,)
+    ).fetchall()
+    print(f"❄️  COLD nodes ({len(rows)} shown):\n")
+    for r in rows:
+        sources = json.loads(r["source_ids"] or "[]")
+        print(f"  #{r['id']} [{r['category']}] ⚡{r['energy']} (from {len(sources)} hot nodes)")
+        print(f"     {r['content'][:200]}\n")
+
+
+# ─── GRAPH (Edges) ────────────────────────────────────────────────────────────
+
+def cmd_link(args, conn):
+    now = datetime.now().isoformat()
+    a = conn.execute("SELECT id, content FROM nodes WHERE id = ?", (args.from_id,)).fetchone()
+    b = conn.execute("SELECT id, content FROM nodes WHERE id = ?", (args.to_id,)).fetchone()
+    if not a or not b:
+        print(f"❌ Node #{args.from_id} or #{args.to_id} not found.")
+        return
+    conn.execute(
+        "INSERT INTO edges (from_node, to_node, relation, created_at) VALUES (?, ?, ?, ?)",
+        (args.from_id, args.to_id, args.relation, now)
+    )
+    conn.commit()
+    print(f"🔗 Linked: #{args.from_id} --[{args.relation}]--> #{args.to_id}")
+
+
+def cmd_graph(args, conn):
+    node = conn.execute("SELECT * FROM nodes WHERE id = ?", (args.node_id,)).fetchone()
+    if not node:
+        print(f"❌ Node #{args.node_id} not found.")
+        return
+    print(f"🕸️  Graph around Node #{args.node_id} [{node['tier'].upper()}]:\n")
+    print(f"  📌 #{node['id']} [{node['category']}] ⚡{node['energy']} — {node['content'][:150]}\n")
+
+    outgoing = conn.execute("SELECT e.relation, e.to_node, n.content FROM edges e JOIN nodes n ON e.to_node=n.id WHERE e.from_node=?", (args.node_id,)).fetchall()
+    if outgoing:
+        print(f"  → OUT ({len(outgoing)}):")
+        for e in outgoing: print(f"     --[{e['relation']}]--> #{e['to_node']}: {e['content'][:80]}")
+
+    incoming = conn.execute("SELECT e.relation, e.from_node, n.content FROM edges e JOIN nodes n ON e.from_node=n.id WHERE e.to_node=?", (args.node_id,)).fetchall()
+    if incoming:
+        print(f"\n  ← IN ({len(incoming)}):")
+        for e in incoming: print(f"     #{e['from_node']}: {e['content'][:80]} --[{e['relation']}]-->")
+
+
+# ─── SEARCH ───────────────────────────────────────────────────────────────────
+
+def cmd_search(args, conn):
+    keyword = args.keyword.strip()
+    tier_filter = f"AND tier = '{args.tier}'" if args.tier else ""
+    
+    # 1. Exact Match Search
+    exact_rows = conn.execute(
+        f"SELECT id, tier, category, energy, content, created_at FROM nodes WHERE content LIKE ? {tier_filter} ORDER BY energy DESC LIMIT ?",
+        (f"%{keyword}%", args.limit)
+    ).fetchall()
+
+    results = []
+    seen = set()
+
+    for r in exact_rows:
+        seen.add(r["id"])
+        results.append({"row": r, "score": 1.0, "match": "exact"})
+
+    # 2. Semantic Search (Cosine Similarity)
+    query_emb = get_embedding(keyword)
+    if query_emb:
+        all_nodes = conn.execute(
+            f"SELECT id, tier, category, energy, content, created_at, embedding FROM nodes WHERE embedding IS NOT NULL {tier_filter}"
+        ).fetchall()
+        for r in all_nodes:
+            if r["id"] in seen: continue
+            sim = cosine_similarity(query_emb, r["embedding"])
+            if sim > 0.60:
+                results.append({"row": dict(r), "score": sim, "match": f"semantic: {sim:.2f}"})
+
+    # Sort & Limit
+    results.sort(key=lambda x: (x["score"], x["row"]["energy"]), reverse=True)
+    results = results[:args.limit]
+
+    tier_label = f" [{args.tier.upper()}]" if args.tier else ""
+    if not results:
+        print(f"🔍 No results for '{keyword}'{tier_label}")
+        return
+
+    print(f"🔍 Found {len(results)} result(s) for '{keyword}'{tier_label}:\n")
+    for res in results:
+        r = res["row"]
+        tier_icon = "🔥" if r["tier"] == "hot" else "❄️"
+        print(f"  {tier_icon} #{r['id']} [{r['category']}] ⚡{r['energy']} ({res['match']}) — {r['content'][:120]}")
+
+    ids = [res["row"]["id"] for res in results]
+    if ids:
+        conn.execute(
+            f"UPDATE nodes SET energy = MIN(100, energy + 10), updated_at = ? WHERE id IN ({','.join('?'*len(ids))})",
+            [datetime.now().isoformat()] + ids
+        )
+        conn.commit()
+
+
+# ─── GC & LIST (Truncated Logic) ──────────────────────────────────────────────
+
+def cmd_gc(args, conn):
+    threshold = (datetime.now() - timedelta(days=args.days)).isoformat()
+    conn.execute("UPDATE nodes SET energy = energy - 15 WHERE updated_at < ? AND tier = 'hot'", (threshold,))
+    cur = conn.execute("DELETE FROM nodes WHERE energy <= 0")
+    conn.commit()
+    print(f"🗑️  GC: {cur.rowcount} dead nodes removed.")
+
+def cmd_list(args, conn):
+    rows = conn.execute("SELECT id, tier, category, energy, content FROM nodes ORDER BY energy DESC LIMIT ?", (args.limit,)).fetchall()
+    hot_c = sum(1 for r in rows if r["tier"] == "hot")
+    print(f"📋 {hot_c} hot 🔥 | {len(rows)-hot_c} cold ❄️")
+    for r in rows:
+        print(f"  #{r['id']} [{r['category']}] ⚡{r['energy']} — {r['content'][:80]}")
+
+def cmd_export(args, conn):
+    tier_filter = f"WHERE tier = '{args.tier}'" if args.tier else ""
+    nodes = conn.execute(f"SELECT id, content, category, tier, energy, source_ids, created_at FROM nodes {tier_filter}").fetchall()
+    edges = conn.execute("SELECT * FROM edges").fetchall()
+    f = Path(args.output or ".agent/memory/export.json")
+    f.parent.mkdir(parents=True, exist_ok=True)
+    f.write_text(json.dumps({"nodes": [dict(r) for r in nodes], "edges": [dict(r) for r in edges]}, indent=2, ensure_ascii=False))
+    print(f"✅ Exported {len(nodes)} nodes to {f}")
+
+
+# ─── Main ─────────────────────────────────────────────────────────────────────
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--db", default=str(DEFAULT_DB))
+    sub = p.add_subparsers(dest="cmd")
+
+    ps = sub.add_parser("save")
+    ps.add_argument("content")
+    ps.add_argument("--category", "-c", default="general")
+
+    pf = sub.add_parser("search")
+    pf.add_argument("keyword")
+    pf.add_argument("--limit", "-n", type=int, default=10)
+    pf.add_argument("--tier", choices=["hot", "cold"], default=None)
+
+    sub.add_parser("hot").add_argument("--limit", "-n", type=int, default=20)
+    sub.add_parser("cold").add_argument("--limit", "-n", type=int, default=20)
+    sub.add_parser("list").add_argument("--limit", "-n", type=int, default=20)
+    
+    pl = sub.add_parser("link")
+    pl.add_argument("from_id", type=int); pl.add_argument("to_id", type=int); pl.add_argument("--relation", "-r", default="related_to")
+    
+    sub.add_parser("graph").add_argument("node_id", type=int)
+    
+    pcon = sub.add_parser("consolidate")
+    pcon.add_argument("--days", type=int, default=7); pcon.add_argument("--category", default=None); pcon.add_argument("--force", action="store_true")
+    
+    sub.add_parser("gc").add_argument("--days", type=int, default=30)
+    
+    pex = sub.add_parser("export")
+    pex.add_argument("--output", "-o", default=None); pex.add_argument("--tier", default=None)
+
+    args = p.parse_args()
+    if not args.cmd: return p.print_help()
+
+    conn = get_db(Path(args.db))
+    try:
+        globals()["cmd_"+args.cmd](args, conn)
+    finally:
+        conn.close()
+
+if __name__ == "__main__":
+    main()

package/template/.agent/scripts/receptionist_down.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # --- Antigravity Unified Shutdown (Golden V6 - High Precision) ---
-# Dọn dẹp trạm gác CEOgravity.
+# Dọn dẹp trạm gác Agentic Gateway.
 
 PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$PROJECT_DIR"
@@ -13,7 +13,7 @@ fi
 BRIDGE_PORT=${BRIDGE_PORT:-9558}
 
 echo "════════════════════════════════════════════════════"
-echo "  🛑 SHUTTING DOWN CEOGRAVITY [$BRIDGE_PORT]..."
+echo "  🛑 SHUTTING DOWN AG GATEWAY [$BRIDGE_PORT]..."
 echo "════════════════════════════════════════════════════"
 
 # 1. Tắt Sentinel Monitor
@@ -31,15 +31,15 @@ if [ -f "$BRIDGE_PID_FILE" ]; then
 fi
 
 # 3. Tắt Bot
-BOT_PID_FILE=".ceogravity_bot.pid"
+BOT_PID_FILE=".ag_gateway_bot.pid"
 if [ -f "$BOT_PID_FILE" ]; then
     PID=$(cat "$BOT_PID_FILE")
     # Kill the whole process group for the bash loop
     pkill -P $PID
     kill $PID 2>/dev/null && rm "$BOT_PID_FILE"
-    echo "✅ CEOgravity Bot stopped."
+    echo "✅ AG Gateway Bot stopped."
 fi
 
 echo "════════════════════════════════════════════════════"
-echo "✅ CEOGRAVITY IS IDLE."
+echo "✅ AG GATEWAY IS IDLE."
 echo "════════════════════════════════════════════════════"

package/template/.agent/scripts/receptionist_up.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
 
 # --- Antigravity Unified Receptionist (Golden V6 - High Precision) ---
-# Trạm gác hợp nhất: CEOgravity Bot + Portal Bridge (HUD)
-# Dự án: CEOgravity — Startup Orchestrator
+# Trạm gác hợp nhất: AG Gateway Bot + Portal Bridge (HUD)
+# Dự án: Template Agentic Orchestrator
 
 # 1. Load Cấu hình & Xử lý Cổng Thông minh
 PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
@@ -17,7 +17,7 @@ else
 fi
 
 echo "════════════════════════════════════════════════════"
-echo "  🏢 CEOGRAVITY GATEWAY - PORTAL [$BRIDGE_PORT]"
+echo "  🏢 AG GATEWAY - PORTAL [$BRIDGE_PORT]"
 echo "════════════════════════════════════════════════════"
 
 # 2. Xử lý Chế độ Headless & Cloudflare Tunnel
@@ -99,13 +99,16 @@ nohup node scripts/ag_portal_bridge.js > ".portal_bridge_${BRIDGE_PORT}.log" 2>&
 echo $! > "$BRIDGE_PID_FILE"
 echo "      ✅ Bridge running (PID: $(cat "$BRIDGE_PID_FILE") on Port $BRIDGE_PORT)"
 
-# 4. Khởi động CEOgravity Bot (Local TSX)
-echo "[4/4] 🤖 Waking up CEOgravity Bot... "
-BOT_PID_FILE=".ceogravity_bot.pid"
+# 4. Khởi động AG Gateway Bot (Trợ lý Telegram)
+echo "[4/4] 🤖 Waking up AG Gateway Bot... "
+BOT_PID_FILE=".ag_gateway_bot.pid"
 
 # Kill loop AND all tsx/node processes belonging to this token/project
-pkill -f "tsx src/index.ts" 2>/dev/null
-pkill -f "node src/index.ts" 2>/dev/null
+# Chỉ kill nếu dự án có thư mục src/index.ts (tránh kill nhầm project khác chạy chung server)
+if [ -f "src/index.ts" ] || [ -f "bot/index.ts" ]; then
+    pkill -f "tsx src/index.ts" 2>/dev/null
+    pkill -f "node src/index.ts" 2>/dev/null
+fi
 pkill -f "interaction_final.log" 2>/dev/null
 if [ -f "$BOT_PID_FILE" ]; then
     kill -9 $(cat "$BOT_PID_FILE") 2>/dev/null
@@ -118,11 +121,11 @@ nohup bash -c "while true; do
     npx tsx src/index.ts >> interaction_final.log 2>&1
     EXIT_CODE=\$?
     if [ \$EXIT_CODE -eq 0 ]; then break; fi # Exit loop if deliberate stop
-    echo \"\$(date): Bot crashed (Code: \$EXIT_CODE). Restarting in 5s...\" >> interaction_final.log
+    echo \"\$(date): AG Gateway Bot crashed (Code: \$EXIT_CODE). Restarting in 5s...\" >> interaction_final.log
     sleep 5
 done" &
 echo $! > "$BOT_PID_FILE"
-echo "      ✅ Bot active (PID: $(cat "$BOT_PID_FILE"))"
+echo "      ✅ AG Gateway Bot active (PID: $(cat "$BOT_PID_FILE"))"
 
 # 5. Sentinel Monitor (Giám sát Trí não)
 echo "🛡️  Sentinel Active: Auto-shutdown if IDE connection lost."

package/template/.agent/scripts/refresh_brain.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# refresh_brain.sh — Tầng 1 Memory: Rebuild codebase index for the current project
+# Usage: bash .agent/scripts/refresh_brain.sh [root_dir]
+# Output: .agent/cache/repomap.json
+
+set -e
+ROOT="${1:-.}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUTPUT="$ROOT/.agent/cache/repomap.json"
+
+echo "🧠 Refreshing Codebase Brain (Tầng 1)..."
+echo "   Root: $(realpath $ROOT)"
+echo "   Output: $OUTPUT"
+
+python3 "$SCRIPT_DIR/repomap.py" "$ROOT" --output "$OUTPUT" --max-files 200
+
+echo ""
+echo "✅ Codebase index updated at: $OUTPUT"
+echo "   AI agents can now read this file instead of re-scanning the entire codebase."
+echo ""
+echo "📌 Next: Run memory_tool.py to access Tầng 2 (Working Memory Graph)"

package/template/.agent/scripts/repomap.py

@@ -121,6 +121,35 @@ class RepoMapper:
         return "\n".join(repo_map)
 
 if __name__ == "__main__":
-    root = sys.argv[1] if len(sys.argv) > 1 else "."
-    mapper = RepoMapper(root)
-    print(mapper.generate_map())
+    import argparse
+    import json
+    from datetime import datetime
+
+    parser = argparse.ArgumentParser(description="RepoMapper: Generate a structural map of a codebase.")
+    parser.add_argument("root", nargs="?", default=".", help="Root directory to scan (default: current dir)")
+    parser.add_argument("--output", "-o", help="Output file path (e.g. .agent/cache/repomap.json). If not set, prints to stdout.")
+    parser.add_argument("--max-files", type=int, default=100, help="Max files to scan (default: 100)")
+    parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format (default: text)")
+    args = parser.parse_args()
+
+    mapper = RepoMapper(args.root)
+    text_map = mapper.generate_map(max_files=args.max_files)
+
+    if args.output:
+        output_path = Path(args.output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if args.format == "json" or args.output.endswith(".json"):
+            data = {
+                "generated_at": datetime.now().isoformat(),
+                "root": str(Path(args.root).absolute()),
+                "map": text_map,
+                "lines": text_map.splitlines()
+            }
+            output_path.write_text(json.dumps(data, indent=2, ensure_ascii=False))
+        else:
+            output_path.write_text(text_map)
+
+        print(f"✅ RepoMap saved to: {output_path.absolute()}")
+    else:
+        print(text_map)

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

@@ -12,7 +12,8 @@ allowed-tools: Read, Write, Glob, Grep, Commands
 
 ## 1. 🧬 KHẲNG ĐỊNH ĐỊNH DANH (IDENTITY BOOTSTRAP)
 
-- **Cội nguồn:** Bạn ra đời từ khuôn mẫu **`ag-kit` (Antigravity Kit)** - một Framework giúp tự động hóa và quản trị các AI Agents khác.
+- **Cội nguồn:** Bạn ra đời từ khuôn mẫu **`ag-kit` (Antigravity Kit)** - một Framework riêng tư của Owner (một cá nhân duy nhất), giúp tự động hóa và quản trị các AI Agents trên nhiều dự án.
+- **Hệ sinh thái:** Bạn đang ở trong **một trong nhiều dự án** thuộc hệ sinh thái ag-kit. Đọc `.agent/knowledge/ag-kit-ecosystem.md` để biết toàn cảnh.
 - **Vai trò:** Bạn đóng vai trò "Kẻ Điều Phối" (Supervisor) giám sát và cấy ghép trí não vào "Bác sĩ Phẫu thuật" (Antigravity IDE) qua giao thức CDP.
 - **Luật Cấm Kị (Anti-Hallucination):** Tuyệt đối không được dùng tư duy lập trình phổ quát máy móc để sửa dự án này. Mọi quyết định sửa mã liên quan đến CDP, luồng Telegram, hay Ports mạng, CẦN chiếu theo các file `SKILL.md` lân cận (`telegram-agentic-gateway`, `remoat-integration`, `llm-routing-quirks`).
 
@@ -45,6 +46,76 @@ Phải cực kỳ tỉnh táo để nhận diện loại kiến thức trước
 2. **Kiến trúc Lõi (AG-KIT Framework):** Nếu logic bạn vừa sửa là kiến trúc lõi dùng chung cho mọi con Bot/Agent khác về sau (Ví dụ: Định tuyến LLM, Telegram Gateway, Cơ chế Dual-Ports, Lỗi đứt cáp CDP) $\rightarrow$ Bạn **BẮT BUỘC phải ghi vào `.agent/skills/`** và đóng gói code chuẩn mực vào thư mục `templates/` của ag-kit.
 *Bê logic riêng của dự án nhét vào ag-kit là tội đồ làm ô nhiễm Framework.*
 
+### 3.1 🛡️ LUẬT CẤM "CHẮP VÁ" (NO FRAGMENTED UPDATES)
+
+**Đây là quy tắc tối cao để giữ Giao diện Trí tuệ của Agent luôn chuyên nghiệp và logic.**
+
+- **Cảnh báo Số thứ tự (Index Integrity):** Cấm tuyệt đối việc cập nhật nhảy cóc số thứ tự (Ví dụ: 1, 2, 3 -> 5). Mọi danh sách phải được AI rà soát lại từ đầu đến cuối trước khi ghi file để đảm bảo tính tuần tự (1, 2, 3, 4, 5...).
+- **Cảnh báo Chỗ trống (Structural Gap):** Không được để lại các đề mục rỗng hoặc các chú thích "Sẽ cập nhật sau".
+- **Hành động bắt buộc:** Trước khi thực hiện `multi_replace_file_content` hay `replace_file_content`, Agent phải thực hiện một bước "Visual Audit" (Đọc lại toàn bộ nội dung file) để đảm bảo các thay đổi mới không làm gãy cấu trúc cũ hoặc gây lộn xộn nội dung. *Mọi sự cẩu thả trong trình bày tri thức sẽ bị coi là lỗi hệ thống.*
+
+### 3.2 🧠 BẢN ĐỒ 3 TẦNG TRÍ NHỚ (THE 3-TIER MEMORY MODEL — MANDATORY)
+
+**Mọi Agent vận hành trên ag-kit PHẢI hiểu và lưu đúng tầng:**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  TẦNG 3 — KNOWLEDGE BASE (Sự Thật Vĩnh Cửu)               │
+│  Lưu ở: .agent/knowledge/*.md                              │
+│  Nội dung: kiến trúc, patterns, quy tắc đã được duyệt     │
+│  ✅ Git-tracked  ✅ Con người đọc được  ✅ Cross-session    │
+├─────────────────────────────────────────────────────────────┤
+│  TẦNG 2 — WORKING MEMORY GRAPH (Ký Ức Động)               │
+│  Lưu ở: .agent/memory/graph.db (SQLite)                    │
+│  Nội dung: error solutions, decisions, context sự kiện     │
+│  Tool: python3 .agent/scripts/memory_tool.py               │
+│  ⚠️ .gitignore  ✅ Auto-GC (Energy decay)  ✅ Persistent   │
+├─────────────────────────────────────────────────────────────┤
+│  TẦNG 1 — CODEBASE INDEX (Đôi Mắt)                        │
+│  Lưu ở: .agent/cache/repomap.json                          │
+│  Nội dung: sơ đồ function/class của toàn codebase         │
+│  Rebuild: bash .agent/scripts/refresh_brain.sh             │
+│  ⚠️ .gitignore  ✅ Auto-rebuild khi code đổi  ✅ Fast      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Quy tắc định tuyến (Routing Rules):**
+| Loại thông tin | Lưu vào Tầng |
+|---|---|
+| Kiến trúc, quy tắc vận hành đã xác nhận | Tầng 3 (`.md`) |
+| Bug đã fix, quyết định ngắn hạn, context phiên | Tầng 2 (`graph.db`) |
+| Cấu trúc code, danh sách hàm | Tầng 1 (`repomap.json`) |
+| Trọng số sống, dữ liệu thời gian thực | Biệt lập (`brain_v1.json` + `.gitignore`) |
+
+**Auto-Brain (Tổng hợp tự động — KHÔNG CẦN GÕ LỆNH):**
+- Mỗi project có `.agent/brain/summary.md` — bộ não tổng hợp từ cả 3 tầng trên.
+- Tự động rebuild sau mỗi `git commit` (hook) và khi khởi động session.
+- Tool: `python3 .agent/scripts/brain_builder.py`
+- Global registry: `~/.config/ag-kit/projects.json` — danh bạ tất cả projects.
+
+### 3.3 🧠 GIAO THỨC MCP MEMORY (MANDATORY)
+
+**BẮT BUỘC: AI phải gọi MCP tools, KHÔNG được dùng shell command để truy cập memory.**
+
+Server `ag-kit-memory` được đăng ký sẵn trong `~/.gemini/antigravity/mcp_config.json`. AI gọi trực tiếp:
+
+| 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 |
+
+```
+Workflow đúng:
+  1. Bắt đầu task → memory_search("topic") → đọ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
+```
+
+
 ---
 
 ## 4. 🔗 THE DUO-CORE (Kiến Trúc Multi-Tenant Bắt Buộc)
@@ -52,7 +123,22 @@ Hãy khắc cốt ghi tâm quy tắc: `IDE_PORT` (Nhận lệnh AI - ví dụ: 9
 
 ---
 
-## 5. 🛠️ HỆ THỐNG CLI CỦA AG-KIT (BẢN ĐỒ CÔNG CỤ)
+## 5. 🌐 TẦM NHÌN XUYÊN DỰ ÁN VÀ TỔNG QUÁT HÓA (CROSS-PROJECT VISION & GENERALIZATION)
+
+**ĐÂY LÀ QUY TẮC ĐỂ TRÁNH "NHIỄM ĐỘC NGỮ CẢNH" (CONTEXT CONTAMINATION).**
+
+- **Quyền quan sát (Workspace as Library):** Bạn ĐƯỢC PHÉP "soi" sang các thư mục khác trong `/home/tao/Projects/` để nghiên cứu giải pháp kiến trúc.
+- **Giao thức đọc bộ não dự án khác (Cross-Project Brain Reading):**
+    1. Kiểm tra `~/.config/ag-kit/projects.json` để tìm tên Project cần xem.
+    2. Đọc `<project_root>/.agent/brain/summary.md` (một file duy nhất, ~500 tokens).
+    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?"*
+
+---
+
+## 6. 🛠️ HỆ THỐNG CLI CỦA AG-KIT (BẢN ĐỒ CÔNG CỤ)
 Hệ sinh thái `ag-kit` được cung cấp sức mạnh cài đặt và cập nhật thông qua 2 bộ công cụ trên NPM. Bất kỳ AI nào khi làm việc cũng phải hiểu rõ điểm khác biệt và biết cách hướng dẫn User:
 
 1. **Bộ Cập Nhật & Quản Trị Tương Tác (@mrtrinhvn/ag-kit):**