duoduo

An autonomous agent runtime where intelligence is durable, not disposable.

Most agent stacks are request/response wrappers: prompt in, answer out, state gone. duoduo is built as a long-lived runtime with a durable body (filesystem), explicit event history, and a dual-loop cognitive model — foreground conversations plus a background subconscious that runs continuously.

Core Innovations

1. Filesystem-First, Event-Sourced Runtime

Most agent runtimes keep session state in process memory. duoduo externalizes everything — conversations, outputs, jobs, memory — to durable files. The canonical event log (WAL) is written before any action executes. If the process dies mid-turn, nothing is lost: the system rehydrates from files and resumes exactly where it left off.

This is not a backup strategy. It is the primary design: the filesystem is the database, the event log is the source of truth, and the process is stateless by default.

2. WAL-Before-Execute at the Gateway Boundary

Every inbound message follows a strict contract: write a canonical event to the append-only log first, then enqueue the session, then execute. This ordering gives three properties simultaneously: replayability (re-run any input from the log), auditability (every event is permanently recorded), and crash recovery (restart resumes from the last committed event, not from volatile memory).

3. One External Identity, Many Internal Sessions

Externally, duoduo presents one coherent agent identity. Internally, it orchestrates multiple concurrent session actors — one per conversation channel, plus background job sessions and subconscious partitions — each with explicit lifecycle and concurrency control (one runner per session, enforced by lease locks). This separates user-facing continuity from execution scalability.

4. Dual-Loop Cognition: Cortex + Subconscious

Foreground (Cortex) responds to live channel messages. Sessions persist across restarts and resume conversation history exactly.

Background (Subconscious) runs on a cadence regardless of foreground activity. It consolidates memory, reflects on past sessions, and maintains a broadcast board of curated knowledge that is automatically loaded into every future session's context. The subconscious runs even when no one is chatting.

5. Self-Programming Cognitive Topology

Subconscious behavior is defined by filesystem files — each partition has its own prompt, schedule, and cooldown. Partitions can modify their own prompts, create new partitions, and adjust their execution schedule. The runtime ships a scaffold; long-term behavior is increasingly authored by the agent itself through durable files, making the system self-extending over time.

6. Minimal Runtime Layer, Maximum Model Delegation

duoduo keeps application code deliberately thin. It delegates reasoning, tool orchestration, and planning entirely to the foundation model and SDK. The runtime owns only what the model cannot reliably own by itself: durability, lifecycle, scheduling, and concurrency boundaries. This makes the system forward-compatible: as the model improves, the system improves without code changes.

Core Principles

Filesystem-First, Event-Sourced

All state — conversations, memory, jobs, session outputs — lives in files. Nothing critical is in process memory only. If the process dies, the system rehydrates from durable state and continues.

Every inbound message is written to an append-only event log before any action executes (WAL-before-execute). This gives replayability, auditability, and deterministic crash recovery.

One Identity, Many Sessions

Externally, duoduo presents one coherent agent. Internally, it orchestrates multiple session actors — one per conversation, plus background job sessions and subconscious partitions — each with explicit lifecycle and concurrency control.

Dual-Loop Cognition

Foreground (Cortex) handles live conversations. Each channel (Feishu, CLI, etc.) maps to a dedicated session with its own history. Sessions persist across restarts and resume from where they left off.

Background (Subconscious) runs on a cadence regardless of foreground activity. It consolidates memory, reflects on past sessions, maintains a shared knowledge surface loaded into every future conversation, and executes scheduled jobs. Subconscious behavior is defined by filesystem files — partitions can modify their own prompts and schedule, making the system self-extending over time.

Channel-Agnostic Protocol

The core runtime speaks a standard JSON-RPC protocol. Channel adapters (Feishu, ACP, etc.) are independent processes that translate between their native protocol and this standard. Adding a new channel requires zero changes to the core.

How It Works

Channel → Gateway → Event Log → Mailbox → Session Runner → Outbox → Channel
                                   ↑
Cadence → Subconscious partitions ─┘
        → Job scanner → Job sessions

Gateway normalizes raw channel inputs into canonical events, routes them to the right session, and handles commands (/status, /cancel, /cd, etc.) without requiring an active foreground session.

Event Log is the append-only source of truth. All events are durable before execution.

Session Runner drains session mailboxes and executes SDK turns. One runner per session, enforced by lease locks.

Subconscious is a playlist-driven set of background partitions. Each runs stateless per cadence tick with its own prompt. Partitions can create new partitions.

Job System manages recurring work as files with cron schedules. The cadence scanner evaluates due jobs each tick and spawns dedicated sessions to execute them.

Memory Pipeline reads the event log, extracts insights, and promotes them to a broadcast board automatically loaded into every future session's context.

Installation

npm install -g @openduo/duoduo
duoduo

Requires Node.js 20+. Docker is recommended for container mode.

On first run, an interactive wizard walks through model configuration, runtime mode, and directory setup.

Runtime Modes

Container mode (recommended) — runs the daemon inside Docker. Isolated, consistent toolchain, automatic restart. State persists in host-mounted directories.

Host mode — runs the daemon directly on your machine. Useful when Docker is unavailable.

Channel Plugins

Channels connect duoduo to external messaging platforms. Install and start a channel plugin alongside the daemon:

duoduo channel install @openduo/channel-feishu
duoduo channel feishu start

Available:

• @openduo/channel-feishu — Feishu / Lark

Packages

| Package | Description | | ------------------------- | ------------------------------------ | | @openduo/duoduo | Core runtime + CLI | | @openduo/channel-feishu | Feishu / Lark channel adapter | | @openduo/protocol | Shared RPC types (zero dependencies) |

License

Private. All rights reserved.