# Architecture of Managed Cross-Harness Workstreams in ai-memory

> Explore the architecture of managed cross-harness workstreams in ai-memory. Learn how this three-layer system facilitates seamless agent CLI migration for a unified coding experience.

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

---

**Managed cross-harness workstreams in `ai-memory` enable a single logical coding session to migrate seamlessly between agent CLIs like Claude Code, Codex, OpenCode, and others through a three-layer architecture of launcher/wrapper, immutable ledger, and read-only native adapters.**

The `ai-memory` project solves a critical problem for developers who switch between AI coding assistants: fragmented session history. When you start a task in Claude Code but want to continue in Codex or Kimi Code, you normally lose context. Managed cross-harness workstreams eliminate this friction by treating the session as a portable, continuous entity. This article examines the complete architecture based on the source code in `akitaonrails/ai-memory`.

## The Three-Layer Architecture

The architecture consists of tightly coupled layers that handle orchestration, persistence, and native integration.

### Launcher and Wrapper Layer

The entry point is `ai-memory run`, implemented 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). This layer:

- Parses user commands and resolves the current `(workspace, project, repo fingerprint, worktree fingerprint)` tuple
- Opens a **renewable 90-second lease** for exclusive access
- Selects the appropriate native harness when none is specified by scanning local native sessions and picking the newest usable one

The launcher distinguishes wrapper-owned flags (`--yolo`, `--fresh`, `--new`) from native arguments, forwarding everything else directly to the underlying binary.

### Managed Workstream Ledger

At [`crates/ai-memory-store/src/workstream.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/workstream.rs), the ledger provides **immutable, append-only storage** for all session events:

- Segments stored as sanitized JSONL under `<data_dir>/raw/workstreams/<workstream-id>/segments/`
- Each launch writes a **workstream packet** containing portable events, handoffs, and project briefs
- Full-text search available via `ai-memory workstream-search`

The database schema is established by migration [`V31__managed_workstreams.sql`](https://github.com/akitaonrails/ai-memory/blob/main/V31__managed_workstreams.sql), creating tables for `workstreams`, `managed_runs`, and related entities.

### Native Adapter Layer

Located in [`crates/ai-memory-workstream/src/harness.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-workstream/src/harness.rs), adapters enforce a critical **read-only policy**:

- Extract visible events from native transcript stores without mutation
- Inject resume selectors (`--session-id`, `--resume`) into native launches
- Support adapters for Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, Kiro v2/v3, OMP, Grok Build CLI, and Antigravity CLI

## How a Managed Run Executes

The lifecycle follows six deterministic steps:

1. **Workspace/Project Resolution** — Resolves stable repository fingerprint and opens exclusive lease (one writer per workstream)

2. **Harness Selection** — Auto-detects newest usable native session when no harness specified

3. **Lease & Resume** — `AI_MEMORY_RUN_ID` tags lifecycle hooks as *managed*; `SessionStart` links native session and delivers unseen portable events

4. **Native Execution** — Wrapper forwards arguments to native binary, adding resume selectors like `--resume <id>` for Claude Code

5. **Transcript Import** — After child exit, adapter reads native transcript read-only, extracts visible messages/tool calls/compaction summaries, appends as immutable JSONL

6. **Search & Continuity** — Full ledger searchable with harness, role, and event order preserved

## Critical Guarantees and Invariants

| Guarantee | Implementation |
|-----------|----------------|
| **Single-writer lease** | Prevents race conditions on native-session pointers and delivery cursors |
| **Append-only immutable ledger** | Sanitized JSONL segments; retries cannot duplicate history |
| **Read-only native adapters** | Native harness ownership and security model remain untouched |
| **Deterministic event IDs** | SHA-256 of raw transcript line enables deduplication |
| **Cross-harness consistency** | Subsequent harnesses link to same workstream ID, delivering only delta |

Event IDs derived from SHA-256 hashing ensure that repeated imports of identical content produce identical identifiers, eliminating duplication risk.

## Practical Usage Examples

```bash

# Start a new workstream named "feature-X" using Claude Code

ai-memory run --new feature-X claude

# Switch to the same workstream in Codex (auto-adopts Claude's history)

ai-memory run codex

# Resume the most recent workstream in the current directory

ai-memory run

# Search the ledger for a particular event

ai-memory workstream-search "scope resolver decision"

```

The `--yolo` and `--fresh` flags modify wrapper behavior before harness selection; all other arguments pass through unmodified.

## Key Source Files

| File | Purpose |
|------|---------|
| [`crates/ai-memory-cli/src/commands/run.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/run.rs) | `ai-memory run` command, lease handling, harness selection |
| [`crates/ai-memory-store/src/workstream.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/workstream.rs) | `Workstream` schema, event insertion, search queries |
| [`crates/ai-memory-workstream/src/harness.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-workstream/src/harness.rs) | Native adapters for all supported harnesses |
| [`docs/managed-workstreams.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/managed-workstreams.md) | Human-readable specification and adapter behavior table |
| [`crates/ai-memory-store/migrations/V31__managed_workstreams.sql`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/migrations/V31__managed_workstreams.sql) | SQLite schema for workstreams and managed runs |

## Summary

- Managed cross-harness workstreams enable seamless session portability across 11+ AI coding assistants
- **Three-layer architecture**: launcher/wrapper for orchestration, JSONL ledger for immutable history, read-only adapters for native integration
- **90-second renewable leases** enforce single-writer safety without blocking indefinitely
- **Read-only adapter policy** preserves native harness security models while enabling cross-tool continuity
- **Deterministic SHA-256 event IDs** guarantee idempotent imports and deduplication
- All components implemented in Rust across `crates/ai-memory-cli`, `crates/ai-memory-store`, and `crates/ai-memory-workstream`

## Frequently Asked Questions

### What AI coding assistants does ai-memory support?

`ai-memory` supports Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, Kiro v2/v3, OMP, Grok Build CLI, and Antigravity CLI. Each has a dedicated adapter in [`crates/ai-memory-workstream/src/harness.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-workstream/src/harness.rs) that handles read-only transcript extraction and resume selector injection.

### How does ai-memory prevent data loss when switching between harnesses?

The managed workstream ledger maintains **immutable append-only JSONL segments** under `<data_dir>/raw/workstreams/<workstream-id>/segments/`. When resuming in a new harness, the `SessionStart` hook delivers only the delta of events that specific harness hasn't seen, ensuring complete continuity without duplication.

### Why are native adapters read-only?

Adapters never write to native harness stores to **preserve each tool's ownership and security model**. The native transcript remains the source of truth for that specific tool; `ai-memory` only imports visible events into its own ledger. This design prevents conflicts with native session management and respects user data boundaries.

### What happens if two processes try to access the same workstream simultaneously?

A **single-writer lease mechanism** prevents concurrent access. The launcher opens a renewable 90-second lease at startup; only one process may own a workstream at a time. This eliminates race conditions on native-session pointers and ensures consistent event delivery ordering.