Wiki-DB -- Self-Describing MNEME Wiki Databases

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.

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.

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 searches entries with BM25 full-text ranking. Type help inside wiki mode for a quick command reference.