Bee Box documentation · directory: https://beebox.run/docs/capabilities/ · index: https://beebox.run/docs/capabilities/index.md · root: https://beebox.run/llms.txt

# Dump it in now, shape it later

A box is a directory of your data, kept under version control with a full
history of changes (using git); a card is a markdown file with a structured
header; the agent is the coding agent (Claude Code or Codex) that operates
the box. You do not have to decide how to organize something before putting
it in: give the agent the facts in plain words, and it holds them as a
generic card until a shape is worth building.

**What it does for you**

- Puts things in as generic records or memos, one card per thing, holding
  the facts you gave in plain words.
- When the same kind of thing keeps showing up with the same detail, the
  agent proposes a card type with its own fields for it.
- Whatever does not fit a field stays on the card as your own words, not
  dropped.
- When a type's fields change, a migration reshapes the existing cards; they
  keep their data through the change.
- The checks that exist are on fields, so free text is never rejected for
  not fitting a shape.

**How it works, briefly**

A card's fields are checked against its type; a wrong or missing required
field is an error. The body of a card is free text, not checked at all. A
fact with nowhere else to go lives in the body until its type grows a field
for it. Changing a type's fields does not touch existing cards by itself; a
migration reshapes them, running under version control so the change is a
reviewable set of edits, not a silent rewrite.

**Limits**

A card's structured header can hold keys its type does not declare, but such
a key is dropped when the card is read and flagged for removal, so the
durable place for an unplaced fact is the body's free text, never a stray
field (for the curious: the loader is lenient rather than strict by design). Migrations are written by the agent
or a developer in response to a real change; the box does not reshape cards
on its own. The documentation does not say whether a proposed new type is
applied automatically or only after you agree to it.

**Go deeper**

[../reference/cards/record.md](https://beebox.run/docs/reference/cards/record.md),
[../reference/cards/memo.md](https://beebox.run/docs/reference/cards/memo.md),
[../concepts/cards.md](https://beebox.run/docs/concepts/cards.md),
[../dev/adding-a-card-type.md](https://beebox.run/docs/dev/adding-a-card-type.md),
[../dev/migrations.md](https://beebox.run/docs/dev/migrations.md),
[views.md](https://beebox.run/docs/capabilities/views.md)