Session is the atom
Everything else attaches to it.
How each concept behaves
Same eight concepts, four properties each. Read across a row.
| Concept | Origin | Per session | Cross-project | Shape |
|---|---|---|---|---|
Sessionatom One conversation. Immutable UUID. | Auto | One per session | Not applicable | None |
Project Derived from the working directory. | Auto | One per session | Not applicable | None |
Alias Human-readable nickname for a session. | You create it | One per session | Not applicable | None |
Tag Flat #keyword labels. | Auto or manual | Many per session | Yes | Flat |
Collection Hand-picked tree, up to 8 deep. | You create it | Many per session | Yes | Tree (8 deep) |
Thread DAG of sessions tied by intent. | Auto or manual | Many per session | Yes | DAG |
Pin Floats a session to the top of its list. | You create it | One per session | Not applicable | Single star |
Note Markdown attached to a session. | You create it | One per session | Not applicable | None |
- Sessionatom
One conversation. Immutable UUID.
- Origin
- Auto
- Per session
- One per session
- Cross-project
- Not applicable
- Shape
- None
- Project
Derived from the working directory.
- Origin
- Auto
- Per session
- One per session
- Cross-project
- Not applicable
- Shape
- None
- Alias
Human-readable nickname for a session.
- Origin
- You create it
- Per session
- One per session
- Cross-project
- Not applicable
- Shape
- None
- Tag
Flat #keyword labels.
- Origin
- Auto or manual
- Per session
- Many per session
- Cross-project
- Yes
- Shape
- Flat
- Collection
Hand-picked tree, up to 8 deep.
- Origin
- You create it
- Per session
- Many per session
- Cross-project
- Yes
- Shape
- Tree (8 deep)
- Thread
DAG of sessions tied by intent.
- Origin
- Auto or manual
- Per session
- Many per session
- Cross-project
- Yes
- Shape
- DAG
- Pin
Floats a session to the top of its list.
- Origin
- You create it
- Per session
- One per session
- Cross-project
- Not applicable
- Shape
- Single star
- Note
Markdown attached to a session.
- Origin
- You create it
- Per session
- One per session
- Cross-project
- Not applicable
- Shape
- None
Decide in one glance
Which concept fits the moment?
If Same concept appears across many sessions?
Tag it
e.g. #auth ยท #migration ยท #bug-fix
If A handful of sessions for one milestone?
Make a Collection
e.g. v1.0 launch decisions
If One particular session to recall by name?
Alias and pin it
e.g. auth-middleware-refactor
If Several sessions form one unit of work?
Spin up a Thread
e.g. planning + execution children
How things are organized
The diagram above maps every concept onto the Session atom. The matrix:
| Concept | Auto / manual | Per-session | Cross-project | Hierarchical |
|---|---|---|---|---|
| Project | auto from cwd | one | โ | no |
| Alias | manual | one (history kept) | n/a | no |
| Tag | manual or auto-scan | many | yes | flat |
| Collection | manual | many | yes | tree, max 8 deep |
| Thread | manual now, auto in v0.15b | many | yes | DAG |
| Pin | manual | one (boolean) | n/a | no |
| Note | manual | one (history kept) | n/a | no |
#Which one when
- Same concept across projects โ tag
- Curated, nestable bundle โ collection
- One specific session you'll search for by memory โ alias + pin
- Connected unit of work (planning + execution) โ thread