How Managed Workstreams Enable Cross-Harness Continuity in ai-memory

Managed workstreams are the core mechanism in akitaonrails/ai-memory that allows a single logical coding session to migrate seamlessly between different AI coding agents—including Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, Kiro CLI v2/v3, OMP, Grok Build CLI, and Antigravity CLI—by maintaining an immutable, harness-agnostic ledger of events.

The akitaonrails/ai-memory repository treats the logical coding session as a first-class entity independent of any specific AI harness. By decoupling session state from the native transcript stores of individual agents, managed workstreams preserve user intent, tool results, and compaction summaries across heterogeneous toolchains.

Architecture of Managed Workstreams

The system implements three tightly-coupled layers that coordinate to abstract session persistence away from any single vendor's format.

Launcher and Wrapper Layer

The entry point for every managed session is the ai-memory run command handler. This layer parses CLI arguments, resolves the current workspace-project scope, and creates or resumes a workstream ID. It injects wrapper-owned flags such as --yolo and --fresh while opening a 90-second renewable lease (tracked via AI_MEMORY_RUN_ID) to guarantee exclusive ownership of the workstream during execution. The human-readable specification for these steps is documented in docs/managed-workstreams.md.

Workstream Ledger Layer

At the heart of continuity lies an immutable, append-only sequence of visible events stored under <data_dir>/raw/workstreams/<workstream-id>/segments/. Each event carries a WorkstreamEventKind tag and a deterministic ID derived from the SHA-256 hash of the raw JSONL line, ensuring idempotent imports even during retries. The ledger is indexed in SQLite for fast search and is defined in crates/ai-memory-workstream/src/transcript.rs, with checkpoint handling implemented in crates/ai-memory-workstream/src/repository.rs.

Native Adapter Layer

Each supported AI harness includes a lightweight adapter that reads the harness’s native transcript store read-only, extracts only public-visible events, and appends them to the workstream ledger. When a harness starts, the adapter injects the workstream’s portable packet—the delta of events the harness has not yet seen—via harness-specific resume flags such as --resume, --session-id, or --conversation. After the child process exits, the adapter executes the FinishWorkstreamRun command to synchronize new events without mutating the native store. This logic is coordinated through the writer-actor commands PrepareWorkstreamRun and FinishWorkstreamRun in crates/ai-memory-store/src/writer.rs.

The Managed Workstream Lifecycle

A complete managed run follows seven deterministic phases that ensure state consistency across agent boundaries.

1. Preparation – The wrapper resolves the repository fingerprint, workspace, and project, then either creates a new workstream (--new) or reuses the most recent one (--workstream). It writes a client-projects.json entry linking the local checkout to the server-side (workspace, project) tuple.

2. Lease Acquisition – The system takes a 90-second renewable lease (AI_MEMORY_RUN_ID) so only one launcher can own the workstream at a time, preventing race conditions during concurrent access attempts.

3. Native Session Linking – The wrapper either creates a fresh native session (if --fresh is passed or no existing session exists) or resumes an existing one using flags like --resume-id or --session. It records the native session ID in the workstream metadata for subsequent correlation.

4. Packet Injection – On SessionStart, the server delivers any workstream events the target harness has not yet processed. The wrapper passes this "portable delta" to the harness through its native flag interface, bounded to fit within the model’s context window.

5. Run Execution – The harness runs normally. All lifecycle-hook observations—including prompts, tool calls, and compaction events—are captured by installed hooks and streamed to the server.

6. Import and Ledger Append – When the child process exits, the wrapper reads the native transcript store without mutating it, extracts visible events, and appends them to the workstream ledger via NewWorkstreamEvent. The deterministic ID generation guarantees that retries do not duplicate history.

7. Release – The lease is released, allowing the next harness to resume the same workstream and receive only the newly added events.

Cross-Harness Continuity in Practice

Because the ledger is independent of any specific harness, every subsequent ai-memory run <harness> reads the same workstream ID, imports the new native session if any, and receives the cumulative portable packet. This allows the logical thread of work to persist across completely different agent implementations.

Start a session in Claude Code and continue it in Codex:

# Start a Claude Code session (creates workstream "default")

cd /path/to/project
ai-memory run claude

# Later, continue the same logical workstream in Codex

ai-memory run codex --yolo   # --yolo forwards Codex’s dangerous-mode flag

Append events to the ledger programmatically:

// Adding an event to the workstream ledger (simplified)
use ai_memory_workstream::transcript::{NewWorkstreamEvent, WorkstreamEventKind};

let event = NewWorkstreamEvent {
    kind: WorkstreamEventKind::Message,
    role: Some("assistant".into()),
    content: "Here is the summary of what we did…".into(),
    ..Default::default()
};
ledger.append(event);

Import from a native transcript store:

// Native adapter example for a generic harness (pseudo-code)
fn import_native_transcript(path: &Path, ws: &mut Workstream) {
    let raw = std::fs::read_to_string(path)?;
    for line in raw.lines() {
        if let Some(event) = parse_visible_event(line) {
            ws.append(event);
        }
    }
}

Core Source Files for Managed Workstreams

• docs/managed-workstreams.md – Human-readable specification of the managed workstream flow, flags, and policies.
• crates/ai-memory-workstream/src/transcript.rs – Definition of WorkstreamEventKind, NewWorkstreamEvent, serialization logic, and deterministic ID generation.
• crates/ai-memory-workstream/src/repository.rs – Checkpoint handling and persistence of the workstream ledger.
• crates/ai-memory-store/src/writer.rs – Writer-actor commands PrepareWorkstreamRun and FinishWorkstreamRun that coordinate ledger updates with the server.
• scripts/managed-workstream-acceptance.sh – End-to-end acceptance test exercising cross-harness adoption, lease handling, and packet delivery.

Summary

• Managed workstreams abstract session state into a harness-agnostic ledger, enabling migration between Claude Code, Codex, Kimi Code, and other supported agents.
• The three-layer architecture (Launcher, Ledger, Native Adapter) maintains strict separation between the wrapper’s control plane and the harness’s native storage.
• A 90-second renewable lease (AI_MEMORY_RUN_ID) prevents race conditions during workstream handoff.
• Deterministic SHA-256 event IDs guarantee idempotent imports and prevent history duplication during retries.
• Native adapters operate in read-only mode, preserving the integrity of proprietary transcript formats while extracting portable, visible events.

Frequently Asked Questions

What AI coding agents are compatible with managed workstreams?

The system supports Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, Kiro CLI v2/v3, OMP, Grok Build CLI, and Antigravity CLI. Each harness uses a dedicated native adapter to translate between its proprietary transcript format and the portable workstream ledger.

How does the ledger prevent duplicate events during retries?

Each event carries a deterministic ID derived from the SHA-256 hash of its raw JSONL representation. When the FinishWorkstreamRun command appends events, the system checks these IDs to ensure that retries or overlapping imports do not create duplicate entries in the immutable ledger.

What is the purpose of the 90-second lease in managed workstreams?

The AI_MEMORY_RUN_ID lease ensures that only one launcher process owns a workstream at any given time. This prevents race conditions where multiple ai-memory run invocations might simultaneously modify the ledger or inject conflicting packets into a harness session.

How does ai-memory handle native transcript stores without corrupting them?

Native adapters are designed to access harness-specific transcript stores in read-only mode. They extract only public-visible events and append them to the workstream ledger without modifying the original files, ensuring that proprietary data structures remain intact and private to their respective tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}