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

> Learn how ai-memory's managed workstream transparently resumes cross-harness sessions using a server-side ledger and preparation protocol, preserving context and settings.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```rust
// 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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`:

```rust
// 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:

```rust
// 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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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

```bash

# 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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/workstream.rs) | Defines request/response structs for CLI-server communication |
| [`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/ops.rs) | Persistent storage, lease enforcement, and failure recovery |
| [`docs/managed-workstreams.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/managed-workstreams.md) | Human-readable specification of the workstream model |
| [`crates/ai-memory-workstream/src/harness.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/ops.rs) and [`crates/ai-memory-core/src/workstream.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/workstream.rs), with orchestration in [`run.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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.