kage-research/README.md

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

# 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