Skip to content

How things are organized

Seven concepts underpin every view in Claude Recall. Knowing which to reach for is the difference between a tidy library and a pile.

The map

See the diagram above. Session is the atom — one Claude Code conversation, identified by an immutable UUID. Every other concept attaches to it.

One-liners

  • Session - one conversation with Claude Code. Identified by an immutable UUID.
  • Project - auto-derived from the session's cwd (working directory). Coarse; one per session.
  • Alias - the human-readable nickname you give a session (e.g. auth-middleware-refactor). Replaces the UUID in the UI.
  • Tag - a flat #keyword label. Many per session. Cross-project.
  • Collection - a hand-picked, hierarchical bundle of sessions (tree, up to 8 levels deep). Many per session. Cross-project.
  • Thread - a DAG of sessions connected by intent (a planning session plus the execution sessions it spawned). Many per session. Cross-project. Navigable as a node graph. See the Threads section for the full story.
  • Pin - a local ★ that floats a session to the top of the list. Per-browser.
  • Note - markdown you write about a session. One per session, with full edit history.

Comparison matrix

| Concept | Auto or manual? | One or many per session? | Cross-project? | Hierarchical? | |---|---|---|---|---| | Project | auto (from cwd) | one | - | no | | Alias | manual | one (prior values archived) | n/a | no | | Tag | manual (or auto-scan) | many | yes | no (flat) | | Collection | manual | many | yes | yes (tree, max 8 deep) | | Thread | manual now; auto in v0.15b Pro | many | yes | yes (DAG, multiple origins allowed) | | Pin | manual | one (boolean) | n/a | no | | Note | manual | one (with history) | n/a | no |

Which one when?

  • Tag keywords that might repeat across sessions — #auth, #migration, #bug-fix.
  • Collection the handful of sessions that mattered for a milestone — "v1.0 launch decisions", "Scraping — current state".
  • Alias the one session you'll look for by memory — auth-middleware-refactor.
  • Pin your canonical sessions so they sit at the top of their project.
  • Note the 3-bullet takeaway you'll re-read in 3 months.

Rules of thumb

  • If two sessions share a concept and might show up in unrelated projects: tag.
  • If you want a named, curated, nestable bundle you'll open directly: collection.
  • If the answer is "this one particular session", name it with an alias and pin it.
  • If the sessions are a connected unit of work (a planning session plus the execution sessions it spawned), use a thread (see the Threads section below).