Content
# PolarisAGI Harness
An **open-source, self-hosted** AI Agent system for 2026+. Built strictly according to Harness Engineering's six architectural invariants. Can run on a single machine with 8GB of memory, supporting mainstream third-party integrations like Telegram, Discord, Slack, and more. End-users can customize lifecycle behavior through Shell Script Hooks without modifying the source code.
## Positioning and Constraints
| Dimension | Content |
|------|------|
| Positioning | Open-source, self-hosted AI Agent (2026+) |
| Operating Environment | Can run on a single machine, consumer-grade laptop, 8GB+ memory |
| Base Language | Go (orchestration/services) + Rust (performance-critical path) |
| Storage | Multi-engine coexistence: relational + vector + graph + KV + full-text search + event stream |
| Form | Multi-agent collaboration: blackboard mode + CAS atomic claim + supervisor tree |
| Core Capabilities | Self-learning / self-evolution / self-enhancement (no gradient mainline + conditional gradient training) |
| LLM Pool | Provider-agnostic: `<flash-class>` Provider model for Budget pool (Tier 0-1), `<reasoning-class>` model for Reasoning pool (Tier 2-3 complex reasoning). Adapters implemented for OpenAI, Anthropic, DeepSeek, and other mainstream protocols |
> **Default Recommendation**: Out-of-the-box configuration (`configs/defaults.toml`) uses DeepSeek V4 series (Flash + Pro), tested on Tier-0 baseline long-term testing. Any provider compatible with the above protocol can be replaced - see `docs/arch/M01-Inference-Runtime.md §3 Provider Adapter`.
## Harness Engineering's Six Invariants
| # | Invariant | Connotation |
|---|--------|------|
| 1 | **Observability First** | Full-chain traceability from line 0, Token_Burn_Rate + Surprise_Index as first-class citizens |
| 2 | **Verifiable Execution** | No probability filtering as a security boundary, security decisions physically/cryptographically verifiable |
| 3 | **Composable Primitives** | Minimal reusable units, module hot path synchronous interface + cold path structured event communication |
| 4 | **Data-Driven Iteration** | Eval Harness drives self-evolution, all changes gated by CI |
| 5 | **State Machine Holds Control Flow** | Go deterministic state machine holds control flow, LLM only does probabilistic fill-in |
| 6 | **State-in-DB** | All states persisted to disk, asynchronous events decouple cross-storage state changes, crash recovery from EventLog replay |
## Architecture
### Four-Layer Architecture / 13 Modules / 6 Code Packages
```
┌──────────────────────────────────────────────────────┐
│ L3 Interface & Scheduler (M13) │ Eval Harness (M12) │ ← Governance/Interface
├──────────────────────────────────────────────────────┤
│ L2 Orchestrator (M8) │ Self-Improve (M9) │ RAG (M10)│ ← Collaboration/Learning
├──────────────────────────────────────────────────────┤
│ L1 Agent Kernel (M4) │ Memory (M5) │ Skill (M6) │ │ ← Cognitive Core
│ Tool & Action (M7) │
├──────────────────────────────────────────────────────┤
│ L0 Inference (M1) │ Storage (M2) │ Observability │ ← Infrastructure
│ (M3) │ Policy & Safety (M11) │
└──────────────────────────────────────────────────────┘
```
### Module → Code Package Mapping
| Code Package | Module | Responsibility |
|--------|------|------|
| `pkg/substrate` | M1 Inference · M2 Storage · M3 Observability · M11 Policy & Safety | LLM routing, multi-engine storage, full-chain tracking, policy execution |
| `pkg/cognition` | M4 Kernel · M5 Memory · M6 Skill | State machine, hierarchical memory, skill library |
| `pkg/action` | M7 Tool & Action | Sandbox execution, MCP bidirectional, tool registration |
| `pkg/swarm` | M8 Orchestrator · M9 Self-Improve · M10 RAG | Multi-agent blackboard, self-evolution, knowledge intake |
| `pkg/governance` | M12 Eval Harness | Evaluation gating, trajectory replay, shadow execution |
| `pkg/edge` | M13 Interface & Scheduler | CLI/API/WebUI, task scheduling, HITL |
### Hardware Tiers
| Tier | RAM | Inference Source |
|------|-----|---------|
| Tier 0 (Floor) | 8GB | All remote API |
| Tier 1 (Sweet Spot) | 16GB | Remote API + high concurrency |
| Tier 2 | 24GB+ | Remote API + multi-agent + full storage stack |
| Tier 3 | 64GB+ (Apple Silicon) | Full local inference |
## Project Structure
```
polarisagi-harness/
├── cmd/polaris/ # Entry point
├── pkg/
│ ├── substrate/ # L0: inference, storage, observability, policy
│ ├── cognition/ # L1: kernel, memory, skill
│ ├── action/ # L1: tool
│ ├── swarm/ # L2: orchestrator, self_improve, knowledge
│ ├── governance/ # L3: eval
│ └── edge/ # L3: scheduler
├── internal/ # Private sharing: protocol, config, errors
├── rust/substrate/ # Rust FFI performance path
├── skills/ # Built-in skills
├── policies/ # Cedar policies
├── configs/ # Default configurations
├── docs/arch/ # Architecture design documents
├── go.mod
└── Makefile
```
## Running
**Prerequisites**: Go 1.26+, Rust 1.94+
## Data Directory
The project's global working directory is located at `~/.polarisagi/harness/`. All state data (including database `polaris.db`), log files, runtime cache, etc. are persisted in this directory.
```bash
# Build
make build
# Run
make run
# Test
make test
# Full check
make all
```
## Architecture Design Documents
See 15 architecture design documents in `docs/arch/` (1 global public dictionary + 1 overview + 13 module depth selection), covering all 13 modules' pre-research and technical selection.
## Contact and Community
- **Official Website**: [https://polarisagi.online/](https://polarisagi.online/)
- **Author / Follow me**: mrlaoliai (same name across platforms: Xiaohongshu, Douyin, TikTok, X, etc.)
- **Contact Email**: [polarisagi.online@gmail.com](mailto:polarisagi.online@gmail.com)
