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

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. 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 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:

# 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:

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 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 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. 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.

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