|
| 1 | +# Visual memory |
| 2 | + |
| 3 | +The fifth memory layer. Every other layer is text; this one is pictures. |
| 4 | + |
| 5 | +``` |
| 6 | +working/ scratchpad for the current task |
| 7 | +episodic/ raw experience log |
| 8 | +semantic/ distilled lessons |
| 9 | +personal/ user preferences |
| 10 | +visual/ drawings the agent and user share <-- you are here |
| 11 | +``` |
| 12 | + |
| 13 | +Visual memory lives as snapshots of a live tldraw canvas (see the |
| 14 | +`tldraw` skill). The canvas itself is ephemeral — the browser tab closes, |
| 15 | +the drawing is gone. Snapshots make a specific canvas state durable and |
| 16 | +recallable. |
| 17 | + |
| 18 | +## Shape |
| 19 | + |
| 20 | +``` |
| 21 | +visual/ |
| 22 | + README.md this file |
| 23 | + snapshots.jsonl source of truth: one metadata record per snapshot |
| 24 | + INDEX.md rendered view of snapshots.jsonl (human-readable) |
| 25 | + snapshots/ |
| 26 | + <id>.json full canvas state for snapshot <id> |
| 27 | + archive/ archived (never deleted) snapshots |
| 28 | + visual_memory.py CRUD module + CLI |
| 29 | +``` |
| 30 | + |
| 31 | +`snapshots.jsonl` is the source of truth. `INDEX.md` is re-rendered from |
| 32 | +it; do not hand-edit. This mirrors the `lessons.jsonl` / `LESSONS.md` |
| 33 | +pattern in `semantic/`. |
| 34 | + |
| 35 | +## CLI |
| 36 | + |
| 37 | +```bash |
| 38 | +# capture the current canvas (shapes JSON on stdin) |
| 39 | +<get_canvas output> | python3 .agent/memory/visual/visual_memory.py \ |
| 40 | + snapshot --label "auth-flow-v1" --tags architecture,auth \ |
| 41 | + --note "agreed login + refresh flow" |
| 42 | + |
| 43 | +# list stored snapshots |
| 44 | +python3 .agent/memory/visual/visual_memory.py list [--tag architecture] |
| 45 | + |
| 46 | +# load a snapshot's full shape data |
| 47 | +python3 .agent/memory/visual/visual_memory.py load <id> |
| 48 | + |
| 49 | +# archive a stale snapshot (moves to snapshots/archive/, never deletes) |
| 50 | +python3 .agent/memory/visual/visual_memory.py archive <id> |
| 51 | + |
| 52 | +# show layer status |
| 53 | +python3 .agent/memory/visual/visual_memory.py status |
| 54 | +``` |
| 55 | + |
| 56 | +The module is also importable: |
| 57 | + |
| 58 | +```python |
| 59 | +from visual_memory import snapshot, list_snapshots, load_snapshot, archive_snapshot |
| 60 | +``` |
| 61 | + |
| 62 | +## Rules |
| 63 | + |
| 64 | +- Append-only. `archive` moves a snapshot into `snapshots/archive/`. Nothing |
| 65 | + is ever deleted from disk. |
| 66 | +- Ids are time-sortable so `ls snapshots/` reads chronologically. |
| 67 | +- Snapshots are self-contained: a single `<id>.json` carries everything |
| 68 | + needed to restore the canvas. `snapshots.jsonl` is an index over them. |
0 commit comments