From e38cf6bc8b4259f16382a197219110daa6e34bc7 Mon Sep 17 00:00:00 2001
From: shokollm <270575765+shokollm@users.noreply.github.com>
Date: Wed, 1 Apr 2026 05:18:30 +0000
Subject: [PATCH] docs: update benchmark with cloud architecture and memory
 analysis

---
 docs/agent-concurrency-benchmark.md | 55 ++++++++++++++++++++++++-----
 1 file changed, 46 insertions(+), 9 deletions(-)

diff --git a/docs/agent-concurrency-benchmark.md b/docs/agent-concurrency-benchmark.md
index b7182dc..36a1276 100644
--- a/docs/agent-concurrency-benchmark.md
+++ b/docs/agent-concurrency-benchmark.md
@@ -11,6 +11,50 @@
 | 3 | ✓ Works | 4th dev rejected (PM + 3 devs = 4, at limit) | Recommended |
 | 5 | ✓ Works | 6th dev rejected (PM + 5 devs = 6, at limit) | Works, monitor memory |
 
+## Architecture
+
+OpenCode is a **cloud client** - agents run on OpenCode's server (MiniMax), not locally.
+
+```
+┌─────────────────┐         ┌─────────────────┐
+│   Local Host    │         │   OpenCode      │
+│                 │  HTTPS  │   Server        │
+│  kugetsu CLI    │◄───────►│   (MiniMax)     │
+│  worktrees/     │  API    │   Agents run    │
+│  sessions/      │  Key    │   here          │
+│  opencode.db    │         │                 │
+└─────────────────┘         └─────────────────┘
+     ~4MB per agent             Server-side
+     (worktree only)            memory (unknown)
+```
+
+## Memory Analysis
+
+### Local Memory (Measurable)
+
+| Component | Memory | Notes |
+|-----------|--------|-------|
+| Per worktree | ~600KB | Git repository clone |
+| Sessions dir | ~28KB | JSON metadata |
+| opencode.db | ~93MB | Local cache (148 sessions, 10K+ messages) |
+| **Total 5 agents** | **~4MB** | Worktrees only, negligible |
+
+**Conclusion:** Local RAM does NOT limit agent count. A 1GB or 2GB system can run MAX=10 agents.
+
+### Server Memory (Not Measurable)
+
+- OpenCode server runs on MiniMax's infrastructure
+- No local process to measure RSS/memory
+- Agent computation happens server-side
+- Memory limit determined by OpenCode service, not local hardware
+
+### Local Bottleneck
+
+The only local constraint is `MAX_CONCURRENT_AGENTS` limit, which:
+- Counts session files (PM + dev agents)
+- Enforced in kugetsu before spawning
+- Prevents resource overload on OpenCode server
+
 ## Behavior
 
 With MAX_CONCURRENT_AGENTS=N:
@@ -54,13 +98,6 @@ count_active_dev_sessions() {
 }
 ```
 
-## Observations
-
-1. **Idle Memory:** ~1.1GB used even with sessions idle (includes system buffers)
-2. **CPU:** 16 cores available - sufficient for multiple agents
-3. **No Active Processes:** When sessions are idle, opencode processes are not actively running
-4. **PM counts:** PM agent session counts toward MAX_CONCURRENT_AGENTS limit
-
 ## Session Files
 
 ```
@@ -75,8 +112,8 @@ count_active_dev_sessions() {
 
 - **1 agent:** Too strict - just PM + 0 dev agents
 - **3 agents:** Recommended - PM + 2 dev agents, leaves room for PM to coordinate
-- **5 agents:** Works - PM + 4 dev agents, monitor memory
-- **More than 5:** Not tested - may require more RAM
+- **5 agents:** Works - PM + 4 dev agents, monitor OpenCode service limits
+- **More than 5:** Not tested - depends on OpenCode server capacity
 
 ## Session Cleanup