docs: unclip fleet-memory's diagrams, and measure the host instead of guessing
Seven labels in fleet-memory.md were losing their last line for readers, in the
document held up as the model for user-facing docs. Found by running a new
mermaid checker against a repo it was not written for, which is the strongest
evidence available that this is a systemic defect class and not one author's slip.
Measured on the real Gitea render rather than a simulation. Gitea serves each
mermaid block from a sandboxed same-origin <iframe srcdoc>, so its
.markup{line-height:1.5!important} never reaches the labels and the page is
directly measurable. On the published version: 31 labels, 6 of them rendering
MORE lines than were authored, worst overflow +0.6px past the clip edge. Mermaid
measures a label with its own metrics, commits to a box, then clips whatever does
not fit; per-line rounding accumulates, so every cut label observed anywhere in
this fleet had four or five rendered lines.
Fixes, all preserving the information rather than deleting it:
- The five store nodes drop their third line; the content shapes they carried
("verbatim text, embedded", "typed facts, time-bounded", "addressed events and
their artifacts", "links between rooms", "read by recency") move into the prose
under the diagram, which is where a qualifier belongs anyway.
- "ask by ADDRESS + ORDER" soft-wrapped its own first line because a caps line
nearly as wide as the box overflows first; shortened to "ask by ADDRESS", with
"read in append order" added to the prose so the ordering property survives.
The table already lists "address, correlation, append order".
- The decision diamond loses "machine or agent" to the sentence above it, which
now asks whether "a specific machine or agent" must act — same words, no clip.
- "to_agent = the specific agent" and the BOTH node shortened; both are spelled
out in full in the worked-examples table directly below.
Nothing was cut for brevity's sake: every phrase removed from a node reappears in
the prose or was already in the table beneath it.
This commit is contained in:
+11
-11
@@ -13,14 +13,14 @@ This document covers: what the stores are, what a central palace changes when se
|
|||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
flowchart LR
|
flowchart LR
|
||||||
Q["ask by MEANING<br/>'what do we know about X?'"] --> D["<b>Drawers</b><br/>chroma.sqlite3<br/>verbatim text, embedded"]
|
Q["ask by MEANING<br/>'what do we know about X?'"] --> D["<b>Drawers</b><br/>chroma.sqlite3"]
|
||||||
R["ask by ENTITY + TIME<br/>'what was true in June?'"] --> G["<b>Knowledge graph</b><br/>knowledge_graph.sqlite3<br/>typed facts, time-bounded"]
|
R["ask by ENTITY + TIME<br/>'what was true in June?'"] --> G["<b>Knowledge graph</b><br/>knowledge_graph.sqlite3"]
|
||||||
S["ask by ADDRESS + ORDER<br/>'what is waiting for me?'"] --> L["<b>Coordination log</b><br/>logstream.sqlite3<br/>addressed events + artifacts"]
|
S["ask by ADDRESS<br/>'what is waiting for me?'"] --> L["<b>Coordination log</b><br/>logstream.sqlite3"]
|
||||||
T["ask by ASSOCIATION<br/>'what else touches this?'"] --> P["<b>Palace graph</b><br/>tunnels.json + hallways.json<br/>links between rooms"]
|
T["ask by ASSOCIATION<br/>'what else touches this?'"] --> P["<b>Palace graph</b><br/>tunnels.json + hallways.json"]
|
||||||
D --> DI["<b>Diaries</b> live here too:<br/>drawers with room=diary,<br/>read by recency, not similarity"]
|
D --> DI["<b>Diaries</b> live here too:<br/>drawers with room=diary"]
|
||||||
```
|
```
|
||||||
|
|
||||||
All four stores are files inside **one palace directory**, so "the palace" is a directory you can back up in one go.
|
All four stores are files inside **one palace directory**, so "the palace" is a directory you can back up in one go. Each holds a different *shape* of thing: drawers hold verbatim text, embedded for similarity; the knowledge graph holds typed facts that are time-bounded; the coordination log holds addressed events and their artifacts, read in append order; the palace graph holds links between rooms. Diaries are drawers, but they are read by recency rather than by similarity.
|
||||||
|
|
||||||
| Store | You get things back by | Typical use | Wrong use |
|
| Store | You get things back by | Typical use | Wrong use |
|
||||||
|---|---|---|---|
|
|---|---|---|---|
|
||||||
@@ -110,19 +110,19 @@ sequenceDiagram
|
|||||||
|
|
||||||
## 3. Deciding where something goes
|
## 3. Deciding where something goes
|
||||||
|
|
||||||
The question that matters is not "is this important?" but **"how will I want this back, and does anyone need to act?"**
|
The question that matters is not "is this important?" but **"how will I want this back, and does a specific machine or agent need to act?"**
|
||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
flowchart TD
|
flowchart TD
|
||||||
Start["I have something worth keeping"] --> Act{"Must a specific<br/>machine or agent<br/>DO something?"}
|
Start["I have something worth keeping"] --> Act{"Must someone specific<br/>DO something?"}
|
||||||
Act -->|no| Change{"Is it a fact that<br/>changes over time?"}
|
Act -->|no| Change{"Is it a fact that<br/>changes over time?"}
|
||||||
Act -->|yes| Know{"Do they also need<br/>to KNOW it later?"}
|
Act -->|yes| Know{"Do they also need<br/>to KNOW it later?"}
|
||||||
Change -->|yes| KG["Knowledge graph<br/>kg_add / kg_supersede"]
|
Change -->|yes| KG["Knowledge graph<br/>kg_add / kg_supersede"]
|
||||||
Change -->|no| Mine{"Is it about MY session<br/>— what I tried, felt, learned?"}
|
Change -->|no| Mine{"Is it about MY session<br/>— tried, felt, learned?"}
|
||||||
Mine -->|yes| Diary["Diary entry"]
|
Mine -->|yes| Diary["Diary entry"]
|
||||||
Mine -->|no| Drawer["Drawer<br/>wing + room, verbatim"]
|
Mine -->|no| Drawer["Drawer<br/>wing + room, verbatim"]
|
||||||
Know -->|yes| Both["BOTH:<br/>drawer for the knowledge,<br/>event pointing at it"]
|
Know -->|yes| Both["BOTH:<br/>drawer + event pointing at it"]
|
||||||
Know -->|no| Event["Coordination event<br/>to_agent = the specific agent"]
|
Know -->|no| Event["Coordination event<br/>to_agent = that agent"]
|
||||||
```
|
```
|
||||||
|
|
||||||
Worked examples:
|
Worked examples:
|
||||||
|
|||||||
Reference in New Issue
Block a user