Estratos

Designing your hierarchy

Your hierarchy is the shape of your company's memory — and the most important decision you'll make in Estratos. Get it roughly right and every memory has an obvious home and every agent retrieves exactly the right scope. This guide walks through the model, what makes a good layer, and how to change the structure later without breaking anything.

The model

A hierarchy is an ordered set of layers, from a shared root down to your most specific level. Each layer is a kind of thing; the actual values live underneath as folders. A folder is addressed by a dot-path — its segments joined with . — starting at the root.

For an accounting firm, three layers are usually enough:

Depth Layer What a folder is Example segment
0 root The organization itself root
1 clients One client pennine-joinery
2 services A service you deliver for that client vat

That produces paths like root.pennine-joinery.vat — the VAT engagement for Pennine Joinery. An agency might use root → clients → brands; a product team might use root → services → projects. The layers are yours to name.

What makes a good layer

A layer earns its place when it answers "what kind of thing is this?" for a whole level of your work, and when memories naturally attach at that level.

  • Layers are categories; folders are instances. clients is a layer; pennine-joinery is a folder in it. If a candidate layer only ever has one value, it probably isn't a layer.
  • Order from general to specific. Depth 0 is the widest scope every agent shares; each layer down narrows it. A memory high in the tree applies broadly; a memory deep in the tree applies narrowly.
  • Prefer a few meaningful layers over many thin ones. Two or three layers cover most firms. Every extra layer is another decision your team (and their agents) makes on every write.
  • Design for retrieval. Ask: when an agent works on one engagement, what path should it retrieve to get everything relevant? Your layers should make that path obvious.

Naming guidance keeps folders consistent

Consistent folder names are what make a hierarchy usable — pennine-joinery in one place and Pennine Joinery Ltd in another would fragment a client's memory. Each layer therefore carries semantic metadata that both your team and your agents read:

  • Display name — the human-friendly label for the layer.
  • Description — what this layer represents.
  • Naming guidance — how to name a segment at this layer (for example, "lowercase kebab-case of the client's trading name").
  • Examples — a few sample segment values that model the convention.
  • Allow tagged — whether tagged memories may attach to this layer.

This metadata isn't decoration. When an agent calls describe_hierarchy, it receives every layer's naming guidance and examples, so it names new folders the way you would — without asking. Filling these in well is the highest-leverage thing you can do for consistency.

Where you build it

Your hierarchy is set up when your organization is created and edited from the Memories › Tagged screen, where the layer rail shows each layer with its metadata. Managing the hierarchy is an Admin or Owner action (see roles and permissions).

Changing structure: draft and publish

Estratos treats structural changes carefully, because they affect every path in your workspace. There are two kinds of edits:

  • Semantic edits happen in place on the active hierarchy. You can update a layer's display name, description, naming guidance, and examples at any time — those don't move anything.
  • Structural changes — adding a layer, removing one, renaming a layer's slug, or reordering layers — never mutate the live hierarchy directly. Instead you build a draft from the active version, make your changes there, and publish it. Publishing swaps the draft in as the new active version and archives the old one.

This means exactly one hierarchy version is active at a time, agents always read a consistent structure, and you can prepare a reorganization without disrupting anyone mid-conversation. Folders keep referencing the layer they were created against, so history stays intact across re-versioning.

Renaming a folder (not a layer) is different and always safe: the old path continues to resolve as an alias, and retrieval headers always show the new canonical path. See how retrieval works for the details.

A worked example

An accounting firm sets up:

  • root — display name "Firm"; structural anchor only. Firm-wide standards live as scoped memories at root.
  • clients — naming guidance "kebab-case trading name", examples pennine-joinery, camden-roasters.
  • services — naming guidance "the service line, lowercase", examples vat, year-end, payroll; allow tagged on (so a rule can target every vat engagement).

Now root.pennine-joinery.vat is the obvious home for that client's VAT specifics, a tagged memory on services=vat applies the firm's VAT sign-off checklist to every VAT engagement, and a scoped memory on root carries the house working-papers standard everywhere.

Next steps