docs(readme): architecture diagram for 'Design, in one paragraph'#9
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
🤖 Generated with Claude Code