Estratos

How retrieval works

Retrieval is the core read path in Estratos. An agent asks for a scope path and gets back one Markdown bundle. This page explains, in plain words, exactly what that bundle contains and in what order — so you can predict what any agent will see.

Paths address scopes, never single memories

A path like root.pennine-joinery.vat addresses a scope in the hierarchy. It never points at an individual memory. There is no way to fetch one memory by key, id, or version through retrieval — memory bodies are only ever returned as part of a scope bundle. (The one exception is delete_memory, which takes a memory id purely to delete it, never to read it.)

The walk: root to target

When you retrieve root.pennine-joinery.vat, Estratos walks the tree from the root down to that folder, visiting each ancestor in order:

root  →  root.pennine-joinery  →  root.pennine-joinery.vat

At each step (depth) along that walk, it gathers the memories that apply, and stitches them together into one bundle from the top down. So a memory high in the tree (say, a firm-wide standard on root) comes before the specifics of the exact engagement.

The order at each depth

Within each depth, memories come in a fixed order — always these three buckets, in this sequence:

  1. Scoped memories attached at that folder.
  2. Layer-wide tagged memories for that folder's layer (no value).
  3. Value-targeted tagged memories where the layer's value matches that folder's segment.

Inside each bucket, memories are ordered by their stable key, so the bundle is deterministic — the same scope produces the same bundle every time. Each block is preceded by a header comment naming its kind, title, key, memory id, and version, so an agent (and you) can see exactly where every piece came from.

An empty scope is a valid answer

If nothing applies to a scope, retrieval returns an empty bundle — that's a success, not an error. A scope with a single memory is still a scope retrieval; no memory is ever fetched on its own.

Canonical paths and aliases

You can rename a folder without breaking anything. After a rename:

  • The old path keeps resolving as an alias, so agents and bookmarks that used it still work.
  • Retrieval headers always show the canonical (current) path, even when you retrieved through an alias — so what an agent reads back is never stale.

This is why renaming a folder is always safe, while changing the hierarchy's structure goes through the draft-and-publish flow instead.

What you see vs. what everyone sees

Retrieval honors the review workflow's visibility rules. Published memories are visible to everyone. On top of that, your own pending work folds into your bundles: a pending create you made appears in its bucket, and a pending edit's content replaces the published body — but only for you, through your own agent. Everyone else sees published content only, until an approver signs off.

Over MCP

An agent performs a retrieval with the retrieve tool, passing the scope path. It accepts canonical or aliased paths and returns the bundle as Markdown. See the MCP reference for the tool's exact contract.

Next steps