bio-agent-os 0.1.0

Open-source Bio-Inspired Memory Framework for AI Agents — Biết nhớ, Biết quên, Biết tư duy.

🧠 Bio-Agent OS

Open-source Bio-Inspired Memory Framework for AI Agents

Biết nhớ · Biết quên · Biết tư duy

Designed by Locaith Solution Tech | 🇻🇳 Make in Vietnam

---

🔬 Vấn đề

Mọi AI hiện tại (ChatGPT, Claude, Gemini) đều bị giới hạn bởi Context Window — một vùng nhớ tạm thời bị xoá sạch sau mỗi phiên hội thoại. Giải pháp "Compact" của Big Tech chỉ là nén rác thành rác nhỏ hơn.

Bio-Agent OS giải quyết vấn đề này bằng cách mô phỏng cơ chế trí nhớ sinh học của con người:

Cơ chế	Não người	Bio-Agent OS
Hippocampus	Dán nhãn, phân loại ký ức	Hippocampus — Label metadata real-time
Synaptic Pruning	Cắt tỉa khớp thần kinh rác	GarbageCollector — TTL + Ebbinghaus decay
Encoding Shift	Nén sự kiện → Logic trừu tượng	Hippocampus.consolidate() — Core Identity
Prefrontal Cortex	Bộ đệm ngắn hạn	L1WorkingMemory — Episodic buffer
Neocortex	Bộ nhớ dài hạn	L2SemanticMemory — Vector + Time-decay
Association Areas	Kết nối thông tin	KnowledgeGraph — Entity-Relationship

🏗️ Kiến trúc

bio_agent_os/
├── core/
│   ├── llm_engine.py        # LLM Abstraction (Gemini, Ollama, vLLM, OpenAI)
│   ├── router.py             # Intent classification (L1? L2? Graph?)
│   └── persona.py            # Core Identity — "Linh hồn" bất biến của AI
├── memory/
│   ├── l1_working.py         # Short-term buffer (TTL, CRUD)
│   ├── l2_semantic.py        # Long-term Vector Search + Ebbinghaus decay
│   └── knowledge_graph.py    # Entity-Relationship Graph (Reasoning DB)
├── background_jobs/
│   ├── hippocampus.py        # Sleep → Label + Encode (Sự kiện → Logic)
│   ├── graph_builder.py      # Extract Entities/Relations from text
│   └── garbage_collector.py  # TTL cleanup + Vector pruning
└── api/
    └── main.py               # FastAPI endpoints

🔄 Luồng vận hành

┌─────────────────────────────────────────────────────────┐
│  USER sends message                                      │
│  ↓                                                       │
│  Router.classify() → Needs L1? L2? Graph?               │
│  ↓                                                       │
│  Build Context: L1 (recent) + L2 (semantic) + Persona   │
│  ↓                                                       │
│  LLMEngine.generate() → Response to User                │
│  ↓                                                       │
│  Hippocampus.label() → Store in L1                      │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  SLEEP CYCLE (Background / Idle)                         │
│  ↓                                                       │
│  GarbageCollector.run() → Prune junk from L1 + L2       │
│  ↓                                                       │
│  Hippocampus.consolidate() → Encode survivors → Persona │
│  ↓                                                       │
│  GraphBuilder.process() → Update Knowledge Graph        │
└─────────────────────────────────────────────────────────┘

🚀 Quick Start

Installation

# From PyPI (coming soon)
pip install bio-agent-os[gemini]

# From source
git clone https://github.com/locaith/bio-agent-os.git
cd bio-agent-os
pip install -e ".[gemini]"

Setup

# Create .env file
echo "GEMINI_API_KEY=your-key-here" > .env

Run the API Server

python -m bio_agent_os.api.main
# → http://localhost:8055

Use as a Library

import asyncio
from bio_agent_os import LLMEngine, L1WorkingMemory, Persona, Hippocampus, GarbageCollector

async def main():
    # 1. Initialize components
    engine = LLMEngine(backend="gemini", model_id="gemini-3-flash-preview")
    l1 = L1WorkingMemory(agent_name="my-agent")
    persona = Persona(name="my-agent")
    hippo = Hippocampus(engine=engine, l1=l1, persona=persona)
    gc = GarbageCollector(l1=l1)

    # 2. Ingest data (real-time labeling)
    await hippo.label_and_store("API /login trả về 500 do thiếu await", source="dev-log")
    await hippo.label_and_store("Hôm nay ăn phở, nước dùng hơi mặn", source="chat")

    # 3. Sleep cycle (prune + encode)
    gc.run()
    stats = await hippo.consolidate()
    
    # 4. Check Core Identity
    print(persona.get_identity_prompt())
    # → "Quy tắc: Khi gọi database trong async context, luôn sử dụng await."

asyncio.run(main())

Use with Ollama (Local LLM)

engine = LLMEngine(
    backend="ollama",
    model_id="llama3.1:8b",
    base_url="http://localhost:11434",
)

Use with vLLM / LM Studio (OpenAI-compatible)

engine = LLMEngine(
    backend="openai",
    model_id="Qwen/Qwen2.5-7B-Instruct",
    base_url="http://localhost:8000/v1",
)

📊 API Endpoints

Method	Endpoint	Description
POST	/api/chat	Chat với AI (Router → L1+L2 → LLM → Response)
POST	/api/ingest	Nạp dữ liệu thô vào Pipeline (Chunk → Label → Store)
POST	/api/sleep	Kích hoạt vòng lặp đêm (Prune + Encode)
GET	/api/state	Xem trạng thái bộ nhớ (L1, L2, Graph, Persona)
GET	/api/graph	Xem Knowledge Graph data
POST	/api/reset	Hard reset L1 memory

🧪 So sánh 3 chiều

Tiêu chí	Compact (Big Tech)	Bio-Memory (Bio-Agent OS)
Xử lý nhiễu	Nén rác → rác nhỏ hơn	Tiêu hủy hoàn toàn (rm -rf)
Cơ chế	Cắt tỉa văn bản đồng bộ	Chuyển hóa bất đồng bộ (Sleep mode)
Chi phí	Đốt GPU liên tục	Tối ưu VRAM, chạy khi rảnh
Kết quả	Mất trí nhớ sau session	Tích luỹ Core Identity vĩnh viễn
Scalability	Tràn bộ nhớ → Hallucination	Chạy vĩnh viễn, không suy giảm

🛡️ License

MIT License — Free for commercial and personal use.

🤝 Contributing

Pull requests welcome! See CONTRIBUTING.md for guidelines.

---

Bio-Agent OS — Trí nhớ sinh học cho AI thế hệ mới
Designed with 🧠 by Locaith Solution Tech