Core concepts

flower models your work as a small set of primitives. Learn these five and the rest of the docs read easily.

Project

A project is a codebase flower knows about — usually one git repository. It has a root_path, a slug, and a flag for whether it's indexed (actively watched). Projects are the top scope: everything else hangs off a project.

A project can have several worktrees (git worktrees / checkouts on different branches). Recall scope nests as worktree ⊂ project ⊂ global.

Session

A session is one run of a coding agent against a project — a Claude Code, Codex, or Pi conversation. flower ingests the session's transcript: its events, tool calls, token usage, and the files it touched. A session has a harness (claude / codex / pi), a status (busy / idle / active / ended / abandoned) that flower resolves to live or retired, and a git branch.

Segment

Agents don't work in one straight line — they pursue a goal, finish it, pivot to the next. A segment is one such unit of intent within a session: a goal, a status (in-progress / done), a summary, next_steps, and the files + commits tied to it. Segments are what make "where did I leave off?" answerable — recall_resume returns the most-recent unfinished segment.

Segmentation is done by an LLM over the raw session (see the ingest pipeline).

Chunk

A chunk is a unit of the corpus that can be embedded and searched. Sessions, segments, scratchpads, todos, commits, repo docs, and briefs are all chunkable — each becomes one or more chunks with a vector embedding, indexed into Meilisearch for hybrid (keyword + vector) search.

When you run recall_search, you're searching chunks. A hit tells you which source it came from (a segment, a commit, a brief) and links back to it.

Brief

A brief is a durable "manila folder" for a unit of work: capture an idea, refine it into a spec, dispatch it to an agent, and keep an append-only trace of everything that touched it. Briefs carry relationships — an epic parent, and depends-on edges that gate dispatch until blockers finish.

Briefs are the planning spine; the whole lifecycle has its own page: Briefs & the dispatch lifecycle.

How they relate

 Project
   ├── Worktree (branch checkout)
   ├── Session ── Segment ── Segment ...      (agent runs, split by goal)
   │                 └── artifacts (files), commits
   ├── Brief ── depends-on ▶ Brief            (planning + gating)
   │      └── Dispatch request ── spawns ─▶ agent session
   └── Daemon (orchestrator / ops / refine)   (standing agents)

 everything chunkable ─▶ embeddings ─▶ Meilisearch ─▶ recall_* / /search

Next: see how a brief becomes running work in Briefs & dispatch, or how the standing agents are managed in Daemons & the roster.