npm package: @mrtrinhvn/ag-kit
Description: Antigravity Kit Base Framework - Generic Agentic AI Programming Core
Author: mrtrinhvn
Latest version: 1.6.1
Deprecated: Hệ thống Ag-Kit đã chuyển sang Private (Github SSH). Vui lòng cài bằng lệnh: npx github:mrtrinhvn/ag-kit

# Antigravity Kit (`@mrtrinhvn/ag-kit`) 🧠

**Universal Memory System** - Trái tim nhận thức và ghi nhớ cho mọi dự án AI Agentic.
Cấy ghép Lõi Bộ Nhớ 3 Tầng (.agent) vào bất kỳ dự án nào để cung cấp khả năng lưu trữ Context, cấu trúc Codebase, và Vector Semantic Search (nhờ `Ollama` + `nomic-embed-text`) cho các tác tử AI.

## 📦 Quick Start

Cách tốt nhất để cấy ghép AG-Kit vào dự án là dùng `npx`. Chạy lệnh sau để mở **Bảng điều khiển Tương tác**:

```bash
npx @mrtrinhvn/ag-kit@latest
```

Hoặc chạy các lệnh đơn lẻ nếu bạn đã nhớ cú pháp:
```bash
# 1. Khởi tạo / Cấy ghép Lõi (.agent folder)
npx @mrtrinhvn/ag-kit@latest init

# 2. Xây dựng Bộ não (Quét Codebase & Vector hóa ký ức)
npx @mrtrinhvn/ag-kit@latest brain

# 3. Tra cứu Vector Memory (Xem các node đã lưu)
npx @mrtrinhvn/ag-kit@latest memory

# 4. Kiểm tra cửa ngõ IDE, Telegram Bot (Dành cho project dùng bot)
npx @mrtrinhvn/ag-kit@latest gateway
```

---

## 🛠 Lệnh CLI & Hệ sinh thái Bộ Não

| Lệnh | Ý nghĩa | Chi tiết tác vụ |
|---|---|---|
| `ag-kit` | **Dashboard** | Mở menu tương tác trực quan. Khuyên dùng. |
| `ag-kit init` | **Khởi tạo** | Cấy ghép toàn bộ tủy não `.agent` vào dự án trắng. |
| `ag-kit brain` | **Bộ Não** | Tự động gọi `brain_builder.py` để quét Codebase, trích xuất Vector Memory và viết Báo cáo Nhận thức `summary.md`. |
| `ag-kit memory` | **Ký ức** | Hiển thị các Mảnh ký ức (Hot/Cold Nodes) đang được lưu trong Không gian Vector `graph.db`. |
| `ag-kit gateway` | **Bot Test** | (Tùy chọn) Quét cổng CDP (IDE), Ollama và Telegram Bot Token cho các dự án dùng Agentic bot. |
| `ag-kit update` | **Cập nhật** | Nâng cấp Agents/Skills/Workflows mới nhất từ NPM mà không làm mất dữ liệu Ký ức hoặc Knowledge của dự án. |
| `ag-kit status` | **Trạng thái** | Hiển thị phiên bản Tool và kiểm tra xem Bộ Não (`summary.md`) đã được hình thành chưa. |

---

## 🏗 Kiến trúc Trí nhớ 3 Tầng (3-Tier Memory)

Sau khi chạy `init` và `brain`, dự án của bạn sẽ vận hành theo mô hình:

1. **Lớp L1 (Working Index):** `repomap.json` - Sơ đồ hàm, class của toàn bộ codebase.
2. **Lớp L2 (Graph Vector Memory):** `graph.db` - Cơ sở dữ liệu đồ thị + Vector Embeddings. Hệ thống ngầm gọi **Ollama (nomic-embed-text)** để mã hóa mọi lệnh `memory_save` thành toán học, cho phép RAG tìm kiếm theo ý nghĩa (Semantic Search) với độ trễ 0ms và chi phí API $0.
3. **Lớp L3 (Knowledge Base):** Báo cáo `summary.md` + file markdown gốc của dự án.

## 🤖 Dual-Model Coordination

Gói `ag-kit` khuyến khích nguyên lý kết hợp 2 AI:
- **Local AI (Ollama):** Đảm nhiệm việc đánh chỉ mục Vector (Embedding) lặng lẽ ở background.
- **Cloud AI (Gemini/Claude):** Dùng để suy luận logic và viết code dựa trên Context mớm từ Local AI.

> Vui lòng tải model: `ollama pull nomic-embed-text` để kích hoạt tính năng Semantic Search của `ag-kit`.

## 🚀 Agentic Port Fusion (Cơ chế Hợp Thể Cổng)

AG-Kit sử dụng kỹ thuật **JSON Introspection** và **Chromium Multiplexing** để giải quyết vĩnh viễn bài toán đụng độ Cổng (Port) khi chạy nhiều Agent/IDE cùng lúc trên một máy:

1. **Lớp IDE (Cổng Trạm - `IDE_PORT`):** 
   - Mọi dự án có thể **dùng chung một cổng duy nhất (VD: 9555)**. 
   - `start.sh` sẽ tự động ping cổng 9555, dùng `curl` quét danh sách JSON (`/json/list`) xem dự án của mình đã mở chưa.
   - Nếu chưa, nó ra lệnh cho Chrome tự động rẽ nhánh thêm một cửa sổ (Workspace) ngay trên cổng 9555 đó. Bot của dự án nào sẽ tự động bắt đúng UUID WebSocket của dự án đó! Chấm dứt cảnh spam Port làm rác cấu hình.

2. **Lớp Bot (Cổng Nội Bộ - `BRIDGE_PORT`):**
   - Không thể xài chung do giới hạn của Node.js. 
   - Khi chạy lệnh `ag-kit init`, AG-Kit sẽ tự động săn tìm một cổng Bridge đang trống (từ 9656 trở lên) và cấp phát **độc quyền** cho dự án thông qua file `.env`.

---

## 🛡️ Zero Context-Contamination (Cách Ly Ruy Băng Phiên Bản 1.5.0+)

**AG-Kit 1.5.0 đánh dấu kỷ nguyên Kiến trúc Phân Tán (Federated Architecture)**, chặn đứng hoàn toàn hiện tượng AI râu ông nọ cắm cằm bà kia:

1. **MCP Memory Sandbox:** Mọi truy vấn Lưu/Ra-Đa Ký Ức đều bị ép khóa vào cờ `workspace_path`. Không bao giờ có chuyện AI tiêm nhầm dữ liệu chứng khoán vào dự án quản trị nhân sự.
2. **Process Lifecycle Shield:** Xóa bỏ bộ Lock PID truyền thống tại thư mục chung `/tmp`. AG-Kit v1.5 thiết lập cơ chế tự dọn rác Bóng Ma Task (Ghost Session) dựa trên sự kiện `lifespan` FastAPI / Node, giúp Bot chống sập trong môi trường Docker Container.
3. **Identity Shifting (Thuật Biến Hình):** Agent sử dụng AG-Kit có khả năng soi mã nguồn Xuyên Dự Án (Cross-Project Vision) để học lỏm mẫu thiết kế. Nhưng khi đóng góp code/trí nhớ cho nhà hàng xóm, Bot sẽ tự động **nhập gia tùy tục** và dùng chính ngôn ngữ của dự án đó!

---

## 🔄 Cập nhật & Bảo trì

Chúng tôi liên tục nâng cấp kỹ năng cho Agent (Skills, Workflows). Để bộ não dự án của bạn luôn thông minh nhất:

```bash
# Luôn dùng @latest để lấy bộ kỹ năng mới nhất
npx @mrtrinhvn/ag-kit@latest update
```

---
*Built with ❤️ to enforce Institutional-Grade AI Memory Standards.*