Skip to content

docs(readme): architecture diagram for 'Design, in one paragraph'#9

Merged
nickroci merged 2 commits into
mainfrom
docs/readme-architecture-diagram
May 27, 2026
Merged

docs(readme): architecture diagram for 'Design, in one paragraph'#9
nickroci merged 2 commits into
mainfrom
docs/readme-architecture-diagram

Conversation

@nickroci

Copy link
Copy Markdown
Owner

Summary

Adds a Mermaid flowchart at the top of the Design, in one paragraph section so first-time readers get the conceptual mental model before they hit the bio references and numbered principles.

```
[Sessions A · B · C] ──events──▶ Ultan ──primes next turn──▶ back to sessions

Inside Ultan:
Librarian (Sonnet) ──proposes──▶ Scholar (Opus, the gate) ──writes approved──▶ Knowledge library
Knowledge library ──surfaces──▶ Librarian
```

Multiple agent sessions feed Ultan with conversation events; the Librarian watches and proposes what's worth remembering; the Scholar is the gate (approves or vetoes each proposal); approved proposals land in the markdown library; the library then surfaces relevant entries back to the Librarian (for context) and primes future sessions (Tier-1 ambient).

Deliberately simpler than the detailed How it works mermaid further down — that one carries the full event-log → tailer → debounce → librarian pool → scholar → reconciler chain. This one is the conceptual agents-↔-Ultan loop the design paragraph is about.

Test plan

  • Renders on GitHub (Mermaid block is standard `flowchart LR` syntax)
  • Placed inside the section it describes; doesn't disturb the existing structure (just inserts between the intro sentence and the numbered list)

🤖 Generated with Claude Code

nickroci and others added 2 commits May 27, 2026 14:04
High-level Mermaid flowchart for readers landing on the README:

  Sessions (Session A · B · C) → Ultan ↻ Sessions

  Inside Ultan:
    Librarian (Sonnet) — proposes → Scholar (Opus) — writes
    approved → Knowledge library. Library surfaces back to the
    Librarian on next batch. Library primes the sessions on the
    next turn.

Placed right after the section's intro sentence ("Three ideas
drive the whole system") and before the numbered principles, so
the diagram frames the reader's mental model before the bio
references arrive. Deliberately simpler than the detailed
"How it works" mermaid further down (which carries the full
event-log → tailer → debounce → librarian pool → scholar →
reconciler chain). This one captures only the conceptual
agent-↔-Ultan loop the design paragraph is about.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…agram

Per user pref [[global/user/tech-preferences/prefer-hand-drawn-diagrams]]
(coleam00 excalidraw, roughness:1) — the Mermaid block from PR #9
landed too rigid / corporate for a project that's otherwise written
with personality. Replaced with an Excalidraw diagram in the same
hand-drawn aesthetic as the cover illustration.

Content: minimal labels per user's "don't add much text" guidance.
Three cascading coding-window panes on the left (with macOS-style
title-bar dots) representing multiple sessions; on the right, an
"Ultan" box containing Librarian → Scholar → Knowledge stacked
vertically (Knowledge drawn as offset paper stack to convey "lots
of doc files"). Two bidirectional arrows between sessions and
Ultan capture the agent-↔-memory loop without labels.

Source ``.excalidraw`` file committed alongside the PNG so future
edits don't need to start from scratch — open in
https://excalidraw.com or any Excalidraw-compatible editor.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@nickroci nickroci merged commit a93b11e into main May 27, 2026
3 checks passed
@nickroci nickroci deleted the docs/readme-architecture-diagram branch May 27, 2026 13:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant