Skip to content
Blenau Docs

The mental model — tiers, paths, and no tags

If Which one do I use? is the decision map, this page is the model underneath it: what the primitives actually are, and the one design choice that surprises people most — there are no tags or labels; the path is the grouping primitive.

You can print this same model from the CLI at any time with blenau concept (alias blenau model) — it never leaves the terminal.

Three tiers, picked by intent

Section titled “Three tiers, picked by intent”

Blenau has three tiers, each with its own CLI surface. Pick by what you’re trying to do.

1. Knowledge — the durable tier

Section titled “1. Knowledge — the durable tier”

The atomic unit is a document with a hierarchical path (e.g. ganemo/infra-odoo/backups.md). Documents are versioned, provenance-tracked, and git-backed — every write is a commit in a connected GitHub repo. Use Knowledge for things you want to keep and retrieve by meaning. blenau search searches only this tier.

Terminal window
blenau docs list --prefix ganemo/infra-odoo/     # list a subtree
blenau docs get ganemo/infra-odoo/backups.md     # read a doc
blenau ingest --path ganemo/infra-odoo/backups.md --title Backups < backups.md
blenau docs delete --path ganemo/infra-odoo/old-runbook.md   # remove one entirely

2. Notes — the working-memory tier

Section titled “2. Notes — the working-memory tier”

Quick lists, reminders, to-dos, fleeting ideas. Disposable — meant to be completed and cleared. A note has a body and an optional list; it has no path. Notes are never returned by blenau search, on purpose: asking “what do I know about X?” must never surface a grocery item.

Terminal window
blenau notes remember "renew the domain Monday" --list reminders
blenau notes recall --list reminders

3. Collections — the structured-records tier

Section titled “3. Collections — the structured-records tier”

Tables of records synced from an external system (an Odoo ERP, a script): products, partners, orders. An agent resolves a natural-language query to a record’s source id + metadata + confidence, then fetches the volatile truth (stock, live price) straight from the source with that id.

Terminal window
blenau collections query productos -q "queen cotton sheets"

Why grouping is a path, not a tag

Section titled “Why grouping is a path, not a tag”

The most common question: where are the tags/labels? There aren’t any, and that is deliberate.

In Knowledge, the path is the grouping primitive. A shared prefix is the “folder” — ganemo/infra-odoo/ groups every document beneath it — but there are no folder entities to create or maintain. The path is:

  • provenance-tracked — it’s the file’s real location in your GitHub repo;
  • git-backed — moving or grouping documents is an ordinary commit;
  • hierarchical and cheap — prefixes nest arbitrarily, and you invent them on demand just by choosing a path.

A parallel tag or label axis would fragment exactly this. You’d have two competing ways to group — a path and a tag set — that drift out of sync, aren’t reflected in the repo, and can’t be reasoned about from the file tree alone. So instead of tags, choose a path prefix. Need a new grouping? Pick a new prefix; it costs nothing and it’s visible everywhere the path is.

That’s also why filtering is by prefix, not by tag:

Terminal window
blenau docs list --prefix ganemo/infra-odoo/

Where to go next

Section titled “Where to go next”