Initial commit: kage-research project files

one-pager.md

@@ -0,0 +1,94 @@
+# 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
+
+```bash
+# 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*