Required keys

Optional keys

Content keyspace

The primary content lives in an FT keyspace (full-text indexed). Each entry is a document keyed by its entry ID. The content format is declared in the manifest: "markdown" (preferred) or "plain".

local ft = db:ft_keyspace("content")
ft:put("rfc-790", "# RFC 790\n\nAssigned Numbers\n\n...")

Metadata keyspace

An optional KV keyspace holding per-entry metadata as JSON strings. Each key matches the corresponding entry ID in the content keyspace.

local meta = db:keyspace("meta")
meta:set("rfc-790", json.encode({
    title = "Assigned Numbers",
    authors = {"J. Postel"},
    date = "1981-09",
    status = "Historic"
}))

The metadata schema is not prescribed by the convention, applications store whatever fields are useful for their domain. The viewer reads available fields and adapts its display accordingly.

Shared key convention

The same key identifies an entry across all keyspaces. Entry rfc-790 in the content FT keyspace corresponds to rfc-790 in the metadata KV keyspace and serves as a prefix for related vectors.

Index descriptor

[
    {"keyspace": "meta", "set": "by_date",  "label": "By date",  "order": "desc"},
    {"keyspace": "meta", "set": "by_pages", "label": "By size",  "order": "desc"}
]

Each sorted set maps scores to entry IDs:

local zs = meta:sorted_set("by_date")
zs:add(198109, "rfc-790", 202301, "rfc-9293")

Browse entry point

{"mode": "browse", "index": "by_date", "order": "desc"}

Opens the specified browsing index. The index value must match a set name from the indexes array.

Search entry point

{"mode": "search"}

Presents the user with a search prompt.

If entry_point is absent, the viewer should default to search mode when no indexes are available, or to the first declared index otherwise.

Collection descriptor

The collections manifest key is a JSON array of collection objects:

[
    {
        "name": "quotes",
        "label": "Quotes",
        "content_keyspace": "quotes",
        "content_format": "markdown",
        "meta_keyspace": "quotes_meta"
    }
]

The primary collection is always defined by the top-level content_keyspace, content_format, and meta_keyspace fields. The collections field defines additional collections only.

Collection-aware indexes

Index descriptors gain an optional collection field that binds the index to a specific collection:

[
    {"set": "by_alpha", "label": "Alphabetical", "order": "asc"},
    {"set": "by_author", "label": "By author", "order": "asc", "collection": "quotes"}
]

When collection is absent, the index belongs to the primary collection. When present, the viewer uses the named collection's meta keyspace for the sorted set and title lookups, and the collection's FT keyspace for content retrieval.

Viewer behavior

Browsing an index sets the viewer's current collection. Subsequent view and search commands operate on the current collection. The search -c <name> flag explicitly targets a collection.

Vector keyspace

Embeddings are stored in a dedicated KV keyspace using MNEME's native vector type. Vectors may use compound keys of the form {entry_id}:{chunk_idx} when multiple embeddings represent a single entry (e.g., different sections of a long document).

local vec = db:keyspace("vec")
vec:vset("rfc-790:000", embedding_abstract)
vec:vset("rfc-790:001", embedding_section1)

The vec_metric manifest key declares the distance metric used for search: "cosine" (default if absent), "dot", or "l2".

Embedded CALM model

When the model key is present in __wiki, it contains a CWGT binary blob -- a complete CALM model that the viewer loads into memory for on-the-fly query embedding.

This makes the wiki-db fully portable: vector search works without any external model files. Even the largest CALM model (small, ~24MB) is negligible relative to typical wiki-db sizes.

local wiki = db:keyspace("__wiki")
local model_blob = wiki:get("model")
-- Load model from blob and use for query embedding

When vec_keyspace is declared but model is absent, the viewer may fall back to FT-only search, or load a model from a known system path.

TSS stylesheet

The optional tss manifest key holds a TSS stylesheet serialized as JSON. The viewer deserializes it to a Lua table and passes it to the pager for rendering.

local wiki = db:keyspace("__wiki")
local tss_json = wiki:get("tss")
if tss_json then
    local rss = json.decode(tss_json)
    local style = tss.new(rss)
    pager:set_style(style)
end

If tss is absent, the viewer uses its default stylesheet.

Graceful degradation

A conforming viewer should adapt to what the manifest advertises rather than requiring every optional feature to be present:

Lilush Shell Wiki mode

The Lilush Shell includes a built-in wiki-db viewer as one of its shell modes, activated with F3.

It provides a command-driven interface with tab completion, renders content through the shell's pager (with markdown support and optional custom TSS from the database), and performs hybrid search (BM25 + vector via RRF) when the database includes an embedded CALM model. Type help inside wiki mode for a quick command reference.