Plastic Labs Internal Wiki

Recently Updated

Detailed Internals — Sequence Diagram

2 min read

Honcho Detailed Internals

Source-of-truth Mermaid for the “how Honcho actually works” sequence diagram published in the public docs (architecture.mdx). The public page uses an Excalidraw-rendered version of this same diagram (repos/honcho/docs/images/honcho-system-diagram.png) for visual polish — this page keeps the raw Mermaid so it can be edited or re-imported into Excalidraw without redrawing from scratch.

Verified against repos/honcho/src/ as of 2026-07-01: write path (src/routers/messages.py), Deriver (src/deriver/), Summarizer (src/utils/summarizer.py), Dreamer (src/dreamer/specialists.py — DeductionSpecialist + InductionSpecialist only, no abduction specialist currently implemented), Dialectic (src/dialectic/).

sequenceDiagram
    participant Dev as Developer/Agent
    participant API as Honcho API
    participant Storage
    participant Queue
    participant Deriver
    participant Summarizer
    participant Dreamer

    rect rgb(230, 245, 220)
    note over Dev,Queue: Write Path (synchronous)
    Dev->>API: create message(s)
    API->>Storage: store message
    API->>Queue: enqueue representation + summary tasks (background_tasks)
    API-->>Dev: return immediately
    note over Dev: caller unblocked — reasoning happens off the request path
    end

    rect rgb(210, 230, 245)
    note over Queue,Summarizer: Deriver + Summarizer (async, batched per peer)
    Queue->>Deriver: representation task (batched to ~1k tokens)
    Deriver->>Storage: read pending messages for (observer, observed)
    Deriver->>Deriver: single structured-output LLM call<br/>(minimal deriver — no tool loop)
    Deriver->>Storage: write explicit + deductive conclusions

    Queue->>Summarizer: summary task
    Summarizer->>Storage: read recent messages
    Summarizer->>Summarizer: direct LLM call (no tools)
    Summarizer->>Storage: write short summary (every N msgs)<br/>write long summary (every M msgs)
    end

    rect rgb(250, 235, 205)
    note over Storage,Dreamer: Dreamer (scheduled dream, not per-message)
    loop On schedule or explicit dream task
        Dreamer->>Dreamer: surprisal-based prioritization<br/>(pick conclusions to expand)
        Dreamer->>Storage: get_recent_observations / search_memory / search_messages
        note over Dreamer: DeductionSpecialist
        Dreamer->>Storage: create_observations_deductive
        Dreamer->>Storage: delete_observations (consolidate redundant/stale)
        Dreamer->>Storage: update_peer_card
        note over Dreamer: InductionSpecialist
        Dreamer->>Storage: create_observations_inductive
        Dreamer->>Storage: update_peer_card
    end
    end

    rect rgb(240, 220, 240)
    note over Dev,Storage: Query Path (Dialectic agent, synchronous)
    Dev->>API: peer.chat("What does this user care about?")
    API->>Storage: fetch observer + observed peer cards (upfront, not via tool)
    API->>API: spawn DialecticAgent (reasoning tier: minimal..max)
    loop Tool loop (bounded, until enough context)
        API->>Storage: search_memory (semantic search over conclusions)
        Storage-->>API: relevant conclusions
        API->>Storage: search_messages / grep_messages / get_messages_by_date_range
        Storage-->>API: message history
        API->>Storage: get_observation_context / get_reasoning_chain
        Storage-->>API: premises behind a conclusion
    end
    note over API: peer card was injected into system prompt at start,<br/>not re-fetched mid-loop
    API->>API: synthesize grounded answer
    API-->>Dev: return response (optionally streamed via SSE)
    end

Last updated: 2026-07-01, alongside the architecture.mdx / reasoning.mdx public docs update.

Graph View