SessionManager
An LLM-agnostic orchestrator for concurrent AI sessions — entity-tag overlap, conflict detection, relevance-filtered context, and a durable work journal. Zero operator input at launch.
The Problem
LLM sessions are isolated
Each LLM session starts with zero knowledge of other active sessions — what they're working on, what files they've touched, what decisions they've made. The operator is the only bridge, manually relaying context and resolving conflicts. This doesn't scale.
This is LLM-agnostic. Sessions may be Claude Code, Codex, Gemini CLI, Aider, custom agents, or any future tool. The session manager sits outside all of them.
Three problems compound:
Context loss. Starting a new session requires re-explaining what other sessions have done. With 2-3 concurrent sessions, this becomes significant overhead.
Blind conflicts. Two sessions can edit the same file without either knowing. Git catches this after the fact, but the sessions can't coordinate in advance.
No fleet visibility. The operator has no way to see, at a glance, how many sessions are active, what each is doing, or which files are under contention.
The Solution
Maia as orchestrator, not broadcaster
A single privileged process — the Maia orchestrator — owns fleet coordination, narration, and context routing. Sessions emit structured events; Maia decides what's relevant and injects context proportional to overlap.
Relevance, not broadcast. Sessions receive context only about other sessions whose entity tags overlap with their own. Zero overlap = zero injection = zero tokens spent.
Filesystem is the coordination layer. Sessions communicate via shared files. No IPC, no sockets, no network. The filesystem is the only mechanism all sessions can access, regardless of which LLM tool they run.
Token cost awareness. Orchestration mechanics (heartbeat checking, overlap computation, conflict detection) run as compiled Rust — zero LLM tokens. Only narration synthesis uses an LLM, routed to the cheapest capable model (Haiku). Frontier models stay in the sessions doing actual work.
Design Principles
Eight principles govern the architecture:
- LLM-agnostic. The session manager does not live inside any LLM runtime. No hooks, no plugins, no extensions. Any LLM CLI that runs in a terminal can participate without modification.
- Maia is the sole voice. Only the orchestrator calls the voice endpoint. Sessions emit structured events; Maia narrates. No session speaks directly. Bearer-token enforced.
- Relevance, not broadcast. Zero overlap between sessions means zero context injected and zero tokens spent.
- Filesystem coordination. All session communication via
runtimeOS/sessions/. No IPC, no sockets. - Read-heavy, write-light. Sessions read the registry; only the orchestrator writes the consolidated registry.
- Graceful degradation. If the orchestrator isn't running, everything works as it does today — isolated sessions. Orchestration is additive, not required.
- Token cost awareness. ~70% of orchestration is deterministic compiled code. Only narration needs an LLM.
- High-precision timestamps. Every event records ISO-8601 with nanosecond precision for deterministic ordering.
Architecture
Component overview
Three layers, cleanly separated:
Sessions — any LLM CLI wrapped by a thin shim that captures PID and writes heartbeats. The LLM never knows the shim exists.
Orchestrator core (Rust binary) — heartbeat monitoring, entity-tag overlap computation, conflict detection, registry consolidation, event queue consumption, and journal appends. Zero LLM tokens.
Narration engine (Haiku) — clusters events into voice-ready summaries, batched every 30-60 seconds. ~200-500 tokens per call, ~6,000 tokens/hour. Negligible cost.
Filesystem layout
All session state lives in runtimeOS/sessions/:
events.jsonl— append-only event bus (all sessions write)registry.json— consolidated registry (orchestrator writes)entities.toml— auto-learned entity graphheartbeats/{session-id}.json— per-session heartbeat (shim writes)context/{session-id}.json— per-session context injection (orchestrator writes, session reads)
No lock file. Maia is the sole orchestrator — no election, no contention.
Entity Tags and Overlap
Dynamic inference, zero operator input
Tags emerge during the session's lifetime. The orchestrator observes the session's PID tree and infers tags from activity:
- Files read/written — project inferred from path, language from extension
- SSH connections — host entity inferred from hostname (e.g. db-01 → production-cluster)
- Git activity — repo/project name from
.git/logs/HEADmtime - Process children — tools invoked (cargo → Rust, npm → TypeScript)
A session starts with zero tags and accumulates them as it works. The orchestrator re-computes overlap every time a tag set changes.
Auto-learned entity graph
entities.toml is built by the orchestrator from observed behaviour, not manually authored. Flat tags appear first from file paths and hostnames. Correlations emerge over time — if sessions touching a project frequently SSH to the same cluster hosts, the orchestrator infers the relationship after a confidence threshold.
Overlap-driven injection tiers
| Overlap depth | Injection | Token cost |
|---|---|---|
| 0 tags | Nothing | 0 |
| 1 tag (indirect) | One-liner summary | ~30 |
| 2+ tags (direct) | Task + recent action | ~100 |
| Same file modified | Conflict alert | ~150 |
Conflict Detection
File-level awareness
When the orchestrator consolidates heartbeats, it checks for overlapping files_modified. If two sessions list the same file, the relevant context files are annotated with a warning.
The orchestrator detects conflicts but does not resolve them — that's the operator's decision: coordinate, merge, or promote one session as the authority.
files_modified tracks writes only — reads inform entity tags but don't trigger conflict detection.
Work Journal
Durable record across sessions
Beyond live session coordination, the session manager maintains a durable, queryable journal of everything each session has done, decided, and deferred. Today this data is scattered across git commits, PRD files, DAILYLOG entries, and CHANGELOGs.
Six entry types: achievement (concrete work completed), decision (choice made with rationale), todo (actionable work identified), aspiration (future-looking idea), learning (non-obvious discovery), blocker (impediment needing resolution).
Entries are project-scoped JSONL at memoryOS/journal/{project}.jsonl — append-only, one per line. Queryable via jq or a dedicated reader skill.
Three creation modes: explicit (operator invokes /journal), inferred (orchestrator scans git commits, PRDs, DAILYLOG), hooked (session-end summary emitted automatically).
Context injection
When a new session starts, the journal injects a project-scoped summary: recent achievements, open TODOs, active decisions, aspirations. ~300-500 tokens per project, only for projects the session is working in.
Security and Durability
Security model
- Session files are local to
runtimeOS/sessions/— ephemeral, not synced or backed up - No secrets in heartbeats — task descriptions and file paths, not contents or credentials
- Voice endpoint is bearer-token protected — only the Maia orchestrator holds the token
- Context injection is untrusted — sessions should verify claims rather than blindly trusting the registry
Durability
runtimeOS/ is ephemeral by design. The orchestrator self-heals on startup — missing directories are created, stale heartbeats are rebuilt. The only durable record is the journal in memoryOS/, backed up per the infrastructure spec.
entities.toml stays in runtimeOS/ — it's auto-learned and rebuilds itself over time. Loss means temporary loss of relationships until re-observed.
Token Economics
Model routing
| Task | Runs as | Tokens |
|---|---|---|
| Heartbeat monitoring | Rust binary | 0 |
| Entity-tag overlap | Rust binary | 0 |
| Conflict detection | Rust binary | 0 |
| Registry consolidation | Rust binary | 0 |
| Narration synthesis | Haiku API | ~200-500/call |
| Session work | Session's own model | Session's budget |
~10-20 narration calls per hour, ~6,000 tokens/hour, ~48,000 tokens/day. At Haiku pricing: negligible. Complex multi-session narrations fall back to Sonnet. Frontier models stay in sessions.
Current Status
The session manager is fully specified with architecture, entity-tag model, overlap computation, conflict detection, work journal, and implementation priorities defined. Implementation pending — the spec is the deliverable for this phase.