# How the ai-memory Managed Workstream Enables Cross-Harness Session Continuity

> Learn how the ai-memory managed workstream enables cross-harness session continuity by persisting a global identifier and using cursor-based event replay for seamless LLM session resumption.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: deep-dive
- Published: 2026-08-20

---

**The ai-memory managed workstream feature persists a global workstream identifier in SQLite, links native harness-specific session IDs to it, and uses cursor-based event replay to let any LLM harness resume exactly where another left off.**

The `akitaonrails/ai-memory` repository implements a persistence layer that treats LLM sessions as durable, harness-agnostic streams. By decoupling the logical session from the native implementation details of Claude, Cursor, Kiro, or OpenCode, the managed workstream ensures your conversation context survives process restarts, IDE switches, and even complete tool migrations.

## What Is a Managed Workstream?

A managed workstream is a persistent, globally unique session log stored in SQLite. Unlike native harness sessions that expire when the process dies, a workstream maintains continuity through a stable identifier and a deterministic event log. It acts as a hub where multiple native sessions—each from different AI agents—can attach, contribute, and resume processing without losing historical context.

## How Cross-Harness Session Continuity Works

The continuity mechanism relies on four coordinated operations: atomic workstream selection, exclusive lease management, native session linking, and cursor-based event replay.

### Workstream Selection and Lease Acquisition

When you execute `ai-memory run`, the system invokes `ai_memory_store::prepare_workstream_run`, which calls `crate::workstream::select_workstream` in **[`crates/ai-memory-store/src/workstream.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/workstream.rs)**. This function either selects the most recently used workstream, retrieves a named workstream specified via `--workstream <name>`, or executes `INSERT INTO workstreams …` to create a fresh record.

Once selected, the workstream acquires a **run lease** consisting of `workstream_id` and `run_id`. This lease guarantees exclusive access while the child harness remains alive. If the harness crashes or exits without finalizing, the lease expires automatically, allowing a new process to claim the workstream.

### Native Session Linking

Each AI harness generates its own native session identifier—such as a Claude conversation ID or a Kiro run ID. The `ai_memory_store::prepare_workstream_run` function calls `workstream::link_native_session` to persist this mapping in the `workstream_native_sessions` table.

The table schema captures:

- `workstream_id`: The global workstream identifier
- `agent_kind`: The harness type (e.g., "claude", "kiro")
- `native_session_id`: The harness-specific session token
- `delivery_cursor`: The event offset processed so far
- `is_current`: A boolean flag marking the active session

When a new harness starts, it upserts its native session ID and marks itself as current, enabling seamless handoffs between tools.

### Event Synchronization and Cursor Tracking

Workstream events reside in the `workstream_events` table. During execution, the harness that owns the lease reads new events through `workstream::prepare_run`, processing them from the last saved `delivery_cursor`. Upon completion, `workstream::finish_run` writes any generated events back to the store and releases the lease.

This cursor-based approach ensures that a harness waking up after a crash—or a completely different agent starting fresh—can query the exact event offset where the previous process stopped, eliminating duplicate processing or context gaps.

### Transcript Extraction for Historical Context

The **[`crates/ai-memory-workstream/src/transcript.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-workstream/src/transcript.rs)** module provides `export_transcript`, which extracts conversation history from native sessions and re-imports it as managed workstream events. This allows you to seed an empty workstream with legacy context from a previous Claude session before switching to Cursor or Kiro, effectively migrating history across incompatible harness formats.

## CLI Workflow Example

Start a persistent session and verify cross-harness continuity:

```bash

# Create or attach to a named workstream

$ ai-memory run --workstream my-project

# Query events visible to the current harness

$ ai-memory workstream-search

# Finalize the session, persisting events and releasing the lease

$ ai-memory finalize-session

```

When you later open a different IDE with a different AI agent, re-running `ai-memory run --workstream my-project` attaches the new harness to the same event log, resuming from the previous cursor position.

## Programmatic API Usage

Integrate workstream continuity into custom tooling:

```rust
use ai_memory_store::{self as store, StoreResult};

async fn start_cross_harness_run() -> StoreResult<()> {
    // Prepare creates the workstream and acquires the lease
    let prepare = store::workstream::prepare_workstream_run(&mut conn, &input).await?;
    
    // Link the harness-specific session ID
    store::workstream::link_native_session(
        &mut conn, 
        prepare.run_id, 
        "claude-conversation-uuid"
    ).await?;
    
    // Process events from the current delivery_cursor...
    
    // Finalize writes new events and releases the lease
    store::workstream::finish_run(&mut conn, prepare.run_id).await?;
    Ok(())
}

```

The **[`crates/ai-memory-core/src/workstream.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/workstream.rs)** module defines the `MANAGED_WORKSTREAM_PACKET_MARKER` constant used to embed workstream metadata in LLM output streams, ensuring markers survive clipboard operations or file exports.

## Summary

- **Global SQLite persistence**: Workstream IDs survive process death and IDE switches because they reside in the `workstreams` table.
- **Atomic lease management**: Prevents concurrent access via `run_id` leases while permitting automatic recovery after crashes.
- **Native session linking**: Maps harness-specific IDs to a unified workstream record via `workstream::link_native_session`.
- **Cursor-based replay**: `delivery_cursor` tracking enables exact resume points across different agents.
- **Transcript migration**: Historical context imports via `export_transcript` bridge incompatible native formats.

## Frequently Asked Questions

### What happens if a harness crashes before finalizing?

The run lease expires automatically when the parent process dies without calling `workstream::finish_run`. A subsequent `ai-memory run` command detects the expired lease and allows a new harness to claim the workstream, resuming from the last committed `delivery_cursor` in `workstream_events`.

### How does ai-memory prevent concurrent harnesses from corrupting the same workstream?

The lease mechanism in `prepare_workstream_run` grants exclusive access via the `run_id` lease held in the SQLite store. Until `finish_run` releases the lease or the process terminates, other instances attempting to claim the same `workstream_id` will block or fail, ensuring atomic event writes.

### Can I migrate historical context from Claude to Kiro using this feature?

Yes. Use the transcript extraction logic in **[`crates/ai-memory-workstream/src/transcript.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-workstream/src/transcript.rs)** to export the Claude native session via `export_transcript`, then re-ingest those events as managed workstream events before starting Kiro. The new harness links to the same `workstream_id` and sees the migrated history as prior events in the log.

### Where is the workstream state actually stored?

All state lives in a local SQLite database managed by **[`crates/ai-memory-store/src/workstream.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/workstream.rs)**. The schema includes the `workstreams` table for global identifiers, `workstream_native_sessions` for harness mappings, and `workstream_events` for the append-only event log that powers cursor-based continuity.