kage-research/one-pager.md

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

# 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