Initial commit: kage-research project files

README.md

@@ -0,0 +1,136 @@
+# 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