brief

Data Model

Entry Categories

Categories are a fixed enum:

• note
• lesson
• decision
• preference
• workflow
• snippet

Unknown categories on post or put are usage errors.

Entry Shape

Entries are exposed through brief get --json as objects with this shape:

[
  {
    "id": 494,
    "title": "...",
    "content": "...",
    "category": "note",
    "language": null,
    "tags": ["hooks", "go"],
    "created_at": "2026-03-12T00:00:00Z",
    "updated_at": "2026-03-12T00:00:00Z",
    "deprecated_at": null
  }
]

Schema

entries

• id integer primary key
• title required text
• content required text
• category required text
• language nullable text
• created_at datetime
• updated_at datetime
• deprecated_at nullable datetime
• embedding nullable blob (normalized float32 vector; null when no embedding was stored)
• embedding_model nullable text (model name used to produce a stored embedding; null when no embedding was stored)

tags

• id integer primary key
• entry_id foreign key to entries.id
• tag text
• unique on (entry_id, tag)

config

• key primary key
• value text

Valid config keys:

• default_limit
• default_category

Search

Full-text search uses SQLite FTS5 over title and content.

Query processing:

• Bare tokens are lowercased and prefix-matched (word*).
• Quoted phrases ("exact phrase") are passed to FTS5 as phrase literals.
• Other special characters are stripped.
• If an AND query returns no results, it is automatically retried with OR.

Ranking:

• BM25 with title weighted 10× over content.
• Entries whose tags match query tokens rank above equivalent untagged entries.
• A recency decay factor promotes recently updated entries among equal-scored results.

Text output includes a content snippet with match terms highlighted in [brackets]. The --json output shape is unaffected; the snippet is text-only.

Lifecycle

• deprecate is the standard lifecycle path
• deprecated entries are excluded from normal get results by default
• brief get --include-deprecated opts them back in
• delete is irreversible hard delete