A field guide to organizing thousands of AI coding sessions

Once you cross a thousand Claude Code sessions, the problem changes. It is no longer "where is my history" (Recall indexes it). It is "what is the mental model that keeps this usable in a year". This post is that mental model, from a setup that is currently at 1,200 and climbing.

Recall gives you five overlapping organizational primitives: projects, aliases, tags, collections, pins, and notes. They do different jobs and they do not compete. Using them well is knowing which does which.

Projects are automatic, and that is on purpose

Projects in Recall are derived from the cwd Claude Code was started in. You do not create them. You do not rename them. You do not merge them. The project identity is the path on disk, encoded once when the session starts and never changed.

This is correct and you should not fight it. The cwd is stable ground truth: two sessions in the same repo really are about the same code, and two sessions in different repos are not the same project no matter what they are "about". Fighting the automatic derivation means adding a human-curated layer that will drift from the truth. Let projects be automatic.

When you want to move a session out of a project, you do not move it. You tag it or collect it, which are the right tools for human-curated groupings.

Aliases are titles, not categories

An alias renames a single session for humans:

recall alias 0f3c9a11 "billing: webhook retry backoff"

Aliases are one-to-one with sessions. They are the thing you read when you are scanning a list. Write them in a consistent shape: a prefix for the area (billing:, auth:, infra:), a short descriptive phrase, nothing more. Do not try to encode dates (they are already on the session), do not try to encode tags (that is what tags are for).

The only hard rule: alias every session you might want later, before you close the tab. Alias-later discipline fails within a week.

Tags are flat, global, and auto-filtered

recall tag add 0f3c9a11 auth
recall tag add 0f3c9a11 rate-limit
recall tag add 0f3c9a11 needs-followup

Tags are the cross-cutting dimension. A tag like auth legitimately applies to sessions in five different repos, and filtering on it surfaces all of them. The web UI renders tags as clickable chips that auto-filter the current list.

Two rules that keep the tag namespace healthy:

1. Flat, not hierarchical. Do not invent auth/oauth and auth/saml. That is what two tags are for: auth and oauth. The UI does not understand slashes.
2. Small. Aim for 50, not 500. Every new tag should earn its place. If a tag has one session under it, it is probably an alias that leaked.

Special-purpose tags are allowed: needs-followup, blocked, archived. These are working-memory tags that come and go. That is fine. They just should not outnumber the content tags.

Collections are hand-picked and hierarchical

A collection is the opposite of a tag: curated by you, can nest, can span any set of sessions.

recall collection create "Q2 migration"
recall collection add "Q2 migration/billing" 0f3c9a11
recall collection add "Q2 migration/auth" 3d8b2c4e

Use a collection when you are building a narrative. A migration project, a postmortem investigation, a gnarly cross-repo debugging session that spanned three weeks. The collection is the thing you show a teammate when you want to explain what happened.

Tags answer "what is this about". Collections answer "what is this part of".

Pins are for the canonical-decision session

Some sessions matter more than others. The one where the architecture was settled. The one where the bug was finally understood. The one where the retry strategy was picked. These sessions are load-bearing and you want them to float.

recall pin 0f3c9a11

Pinned sessions rise to the top of the project view and show up in a dedicated "pinned" list in the UI. The number should stay small. One or two per project, maybe. Pinning everything is the same as pinning nothing.

Notes are the executive summary

A note is free-text attached to a session UUID. It is the thing you read instead of re-reading the transcript.

recall note add 0f3c9a11 "Decided on exponential backoff with jitter, max 6 retries. \
Rejected fixed interval because of thundering herd risk. See Claude's analysis \
around turn 47 for the math."

The conventions that make notes useful:

1. One paragraph. Not a novel. If it needs more, that is a doc in the repo, not a note.
2. Decision first, rationale second, pointer third.
3. Write it at session close, not later.

A worked example

Here is one session and all six dimensions applied:

Project: ~/code/billing         (automatic, cwd-derived)
Alias:   "billing: webhook retry backoff"
Tags:    billing, auth, rate-limit, pinned-decision
Pin:     yes
Collection: Q2 migration/billing
Note:    "Chose exponential backoff with jitter, max 6 retries. Rejected fixed
         interval because of thundering herd risk. Canonical for the webhook
         retry strategy."

Six weeks later, I am in a new repo and vaguely remember the retry conversation. I run:

recall search "exponential backoff jitter"
# or
recall list --tag rate-limit --pinned

Either one surfaces the session by its note text or by the pin plus tag. The alias tells me at a glance it is the right one. The note tells me the answer without opening the full transcript.

The compressed playbook

1. Let projects be automatic.
2. Alias every session before closing the tab.
3. Tag flat, global, max 50 tags.
4. Collect when you are building a narrative.
5. Pin the decision sessions, sparingly.
6. Write the note at close, one paragraph, decision-first.

That is the whole system. See the collections doc for the CLI reference, and tips for the keyboard shortcuts that make this fast in the UI.