How ai-memory's Managed Workstream Resumes Cross-Harness Sessions Transparently

ai-memory uses a server-side versioned ledger and a three-phase preparation protocol to let you resume AI coding sessions across different harnesses without losing context or reconfiguring settings.

ai-memory is an open-source CLI tool that introduces managed workstreams to eliminate the fragmentation problem when switching between AI coding agents. When you run ai-memory run <harness> --workstream <name>, the system automatically preserves your conversation history, project context, and configuration—regardless of which harness you used last. This article explains exactly how the managed workstream resume cross-harness sessions mechanism works by examining the source code in the akitaonrails/ai-memory repository.

What Is a Managed Workstream?

A managed workstream is a server-side, versioned ledger that lives in the same scope as your code repository. It stores observations, handoffs, and managed-run metadata across all sessions. Unlike native harness sessions that exist in isolation, a managed workstream acts as a persistent bridge that any supported harness can connect to.

The workstream is uniquely identified by the tuple (workspace × project × workstream-name). This scoping prevents accidental cross-project leakage and ensures that resuming a session requires only the workstream name, not complex reconfiguration.

The Three-Phase Preparation Protocol

The CLI in crates/ai-memory-cli/src/commands/run.rs implements a transparent managed workstream resume cross-harness sessions flow through three coordinated steps:

Phase 1: Prepare the Managed Run

When you execute ai-memory run, the CLI constructs a PrepareManagedRunRequest and sends it to the server:

// From crates/ai-memory-cli/src/commands/run.rs
let prepare = PrepareManagedRunRequest {
    workspace,
    project,
    cwd: repository.cwd.to_string_lossy().into_owned(),
    repo_fingerprint: repository.repo_fingerprint,
    worktree_fingerprint: repository.worktree_fingerprint,
    agent: provisional_harness.agent_kind(),
    automatic_harness,
    available_agents: unique_auto_agents(&auto_candidates),
    workstream: args.workstream,
    new_workstream: args.new_workstream,
    lease_owner: lease_owner(),
};
let prepared = prepare_managed_run(&endpoint, &prepare).await?;

The PrepareManagedRunResponse returns:

• A unique run_id for this managed run
• Any existing native session ID that can be adopted
• The resolved harness-agent configuration

This request is defined in crates/ai-memory-core/src/workstream.rs alongside related structures like ManagedRunStatus and ManagedRunContextResponse.

Phase 2: Link or Adopt the Native Session

The CLI then determines how to connect the native harness process to the managed workstream. Around lines 46-66 and 78-84 of run.rs, two paths emerge:

If a native session exists (e.g., from a previous Claude CLI run in the same workstream), the CLI issues a LinkManagedRunRequest:

// From crates/ai-memory-cli/src/commands/run.rs
if plan.mode == LaunchMode::Session && let Some(native_session_id) = &plan.expected_session_id {
    post_json_no_content(
        &endpoint,
        &format!("{run_path}/link"),
        &LinkManagedRunRequest {
            native_session_id: native_session_id.clone(),
        },
    )
    .await?;
}

If no native session exists, the CLI either:

• Automatically adopts the newest checkout-local session (the "auto-candidate")
• Interactively prompts you to select one

This adoption logic enables seamless managed workstream resume cross-harness sessions—the workstream ledger already contains the history; only the native process binding changes.

Phase 3: Deliver Harness-Specific Context

Different harnesses require different initialization data. The CLI fetches and injects these automatically:

// Pseudocode representing harness-specific packet fetching
fetch_grok_context(&endpoint, &run_id).await?;    // Grok's --rules
prepare_crush_context(&endpoint, &run_id).await?; // Crush context packets

These packets append to the launch arguments so the new harness receives complete historical evidence without manual steps. The ManagedHarness enum in crates/ai-memory-workstream/src/harness.rs maps identifiers and contains utilities for harness-specific handling, including Kiro v3 resume logic.

Heartbeat Lease Management

A heartbeat loop (HEARTBEAT_INTERVAL) maintains the managed workstream lease while your native process runs. This prevents workstream hijacking and enables clean failure recovery.

If the process crashes or you abort, the CLI calls cancel_managed_run_after_failure to release the lease. The server-side lease semantics—implemented in crates/ai-memory-store/src/ops.rs—include purge-while-lease logic that preserves data integrity across failures.

Supported Harnesses

The managed workstream resume cross-harness sessions capability works across all supported agents:

• Claude (Anthropic's CLI)
• Codex (OpenAI)
• Open-Code
• Pi
• Crush
• Kimi
• Command Code
• Kiro v2 and v3

Switching between any of these requires only the same --workstream name. The ledger persists the conversation; the harness-specific adapter handles the rest.

Practical Example

# Start a Claude session in a new managed workstream called "demo"

$ ai-memory run claude --workstream demo

# CLI creates the workstream, launches Claude, and starts the heartbeat

# Later, switch to the Grok harness, re-using the same workstream

$ ai-memory run grok --workstream demo

# CLI discovers the existing workstream, links the new native Grok session,

# fetches the Grok-specific "rules" packet, and resumes the conversation

No manual export, no context loss, no reconfiguration. The workstream identifier (demo) is sufficient.

Key Source Files

File	Role
crates/ai-memory-cli/src/commands/run.rs	Orchestrates the managed-run lifecycle: preparation, session adoption, packet injection, and heartbeat maintenance
crates/ai-memory-core/src/workstream.rs	Defines request/response structs for CLI-server communication
crates/ai-memory-store/src/ops.rs	Persistent storage, lease enforcement, and failure recovery
docs/managed-workstreams.md	Human-readable specification of the workstream model
crates/ai-memory-workstream/src/harness.rs	Harness enumeration and agent-specific resume logic

Summary

• ai-memory's managed workstream is a server-side ledger scoped to (workspace × project × workstream-name) that preserves AI coding session history
• The managed workstream resume cross-harness sessions protocol uses three phases: PrepareManagedRunRequest, native session link/adoption, and harness-specific context delivery
• Lease management via heartbeats ensures exclusive access and clean recovery from failures
• Supported harnesses (Claude, Codex, Grok, Crush, Kiro, and others) resume transparently using only the workstream name
• All state lives in crates/ai-memory-store/src/ops.rs and crates/ai-memory-core/src/workstream.rs, with orchestration in run.rs

Frequently Asked Questions

What happens if two users try to use the same workstream simultaneously?

ai-memory enforces lease semantics through the heartbeat mechanism. When you start a managed run, you acquire a lease with a unique lease_owner. If another user attempts to access the same workstream, the server rejects or queues the request based on lease state. The heartbeat interval keeps the lease alive; failure to heartbeat releases it automatically.

Can I resume a workstream on a different machine?

Yes. Since the workstream ledger is server-side, any machine with access to the same ai-memory server instance can resume the session. The repo_fingerprint and worktree_fingerprint in PrepareManagedRunRequest verify repository identity, but the workstream itself is not tied to a specific client device.

Does switching harnesses lose any context?

No. The managed workstream stores observations and handoffs in a harness-agnostic format. When you switch harnesses, only the harness-specific packets (like Grok's rules or Crush's context) are fetched fresh. The core conversation history transfers transparently because it lives in the server-side ledger, not the native session.

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