Architecture of Managed Cross-Harness Workstreams in ai-memory

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. 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, 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, creating tables for workstreams, managed_runs, and related entities.

Native Adapter Layer

Located in 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

# 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	ai-memory run command, lease handling, harness selection
crates/ai-memory-store/src/workstream.rs	Workstream schema, event insertion, search queries
crates/ai-memory-workstream/src/harness.rs	Native adapters for all supported harnesses
docs/managed-workstreams.md	Human-readable specification and adapter behavior table
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 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.

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