# Project Summary: Pi Integration for Kugetsu

## Overview

This project explores replacing OpenCode with Pi (agent-core) in the Kugetsu orchestration system.

---

## Documents

### Research Documents

| Document | Description |
|----------|-------------|
| `research.md` | Initial agent framework comparison |
| `pi-integration-research.md` | Deep dive on Pi architecture |
| `kugetsu-pi-feature-mapping.md` | What stays vs what changes |
| `queue-research.md` | Queue system options |
| `llm-compression-research.md` | LLMs for context compression |
| `hermes-tool-guide.md` | Hermes tool implementation |

### Implementation Documents

| Document | Description |
|----------|-------------|
| `implementation-plan.md` | Roadmap with progress |
| `level1.ts` | Basic Pi agent (working) |
| `level2.ts` | Shadow + Manager + Tools |
| `level3.ts` | Task queue + checkpoint/recovery |
| `level3b.ts` | Context management |
| `level3c.ts` | Queue system |
| `level4.ts` | Hermes HTTP server |
| `pi_agent_tool.py` | Hermes tool (HTTP approach) |

---

## Completed Levels

### Level 1: Basic Agent ✅
- Pi agent works
- Tool execution works
- Memory: ~130MB RSS

### Level 2: Shadow + Manager ✅
- Shadow class with isolation
- Shadow Manager
- Tool registry (read, write, edit, bash, grep, ls)
- Concurrency control

### Level 3: Checkpoint/Recovery + Context + Queue ✅
- Task status tracking
- Retry with backoff
- Checkpoint save/load
- Context pruning
- Priority queue
- Backpressure

### Level 4: Hermes Integration ✅
- HTTP server
- Webhook endpoint
- Tool integration guide
- HTTP vs Direct Spawn comparison

---

## Key Findings

### Memory Usage

| Component | Memory |
|-----------|---------|
| OpenCode | ~340MB |
| Pi Agent | ~80-100MB |
| Improvement | ~70% reduction |

### Concurrency

| Setup | Max Concurrent |
|-------|-----------------|
| OpenCode | ~5 |
| Pi | ~15-20 |

### Queue Options

For production: **Priority Queue + Rate Limiting**

---

## Architecture Options

### Current (OpenCode)
```
Telegram → Hermes → Kugetsu → OpenCode → Worktree
```

### Proposed (Pi)
```
Telegram → Hermes → Kugetsu-Pi → Shadows → Worktrees
```

### Alternative (HTTP Server)
```
Telegram → Hermes → HTTP Tool → Pi Server → Shadows
```

---

## Next Steps

1. **Test with Hermes** - Try the tool integration
2. **Direct spawn option** - Implement alternative approach
3. **Full integration** - Replace OpenCode in Kugetsu

---

## Quick Commands

```bash
# Test Level 1
npx tsx level1.ts

# Test Level 2
npx tsx level2.ts

# Test Level 3 (queue)
npx tsx level3.ts

# Test Level 4 (HTTP server)
npx tsx level4.ts
```

---

## Last Updated

2026-04-08