# Pi-Kugetsu Integration: One-Pager

## Overview

Replacing OpenCode with Pi (agent-core) in Kugetsu for better memory, reliability, and control.

---

## Key Metrics

| Metric | OpenCode | Pi | Improvement |
|--------|----------|-----|------------|
| Memory/agent | 340MB | ~80MB | **70% less** |
| Max concurrent | 5 | 15-20 | **3-4x** |
| Context isolation | ❌ | ✅ | **No poisoning** |
| Checkpoint | ❌ | ✅ | **Crash recovery** |

---

## Architecture

```
Telegram → Hermes → Kugetsu-Pi → Shadows → Worktrees
```

---

## What's Implemented

| Level | Status | Description |
|-------|--------|-------------|
| Level 1 | ✅ | Basic Pi agent |
| Level 2 | ✅ | Shadow + Manager + Tools |
| Level 3 | ✅ | Queue + Checkpoint + Context |
| Level 4 | ✅ | Hermes HTTP tool |

---

## Components

- **Shadow**: Isolated agent instance
- **Shadow Manager**: Spawn/terminate/track
- **Queue**: Priority + backpressure
- **Checkpoint**: Save/restore state
- **Context Manager**: Pruning/compression

---

## Quick Commands

```bash
# Test basic agent
npx tsx level1.ts

# Test Shadow + Manager
npx tsx level2.ts

# Test queue system
npx tsx level3c.ts

# Start HTTP server
npx tsx level4.ts
```

---

## Integration Options

| Option | Description | Best For |
|--------|-------------|----------|
| HTTP Server | Hermes → Tool → HTTP → Pi | Production |
| Direct Spawn | Hermes → Tool → Spawn Pi | POC/Simple |

---

## Files

- `README.md` - Full overview
- `implementation-plan.md` - Roadmap
- `hermes-tool-guide.md` - Tool integration
- `queue-research.md` - Queue options
- `llm-compression-research.md` - Compression LLMs

---

## Next Steps

1. Test Hermes integration
2. Direct spawn alternative
3. Production hardening

---

*Last updated: 2026-04-08*