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

Test with Hermes - Try the tool integration
Direct spawn option - Implement alternative approach
Full integration - Replace OpenCode in Kugetsu

Quick Commands

# 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