Library

Documents your agents can search. Where memory holds short insights an agent produced, the library holds authored prose: research notes, decision records, project documentation.

Part of the brain.

What goes in it#

Documents are classified as research, decision, project doc, note, or rule, so a search can be narrowed to one class of knowledge (only decisions, say). A body is markdown or HTML, and every document is either global or scoped to one project. Rule documents feed the library layers in Directives.

Two ways in:

• Authored, written directly, from board or the CLI. A research run publishes its finding this way, behind an approval gate.
• Imported, pulled from a repository's own docs/ directory.

Import is idempotent and incremental: unchanged files are skipped by content hash, so re-importing a large docs tree is cheap. Board's Projects screen has a per-project Refresh docs button that does exactly this, which is the usual way documentation in a repo becomes searchable.

The library is a push store: docs on disk are not searchable until something imports them. That is a deliberate trade for search speed, and the reason the refresh button exists.

Markdown round trips#

An authored document can be exported as a markdown file whose frontmatter preserves its title, category, scope, project, and other document semantics. Importing that file recreates the same document rather than flattening its metadata into body text. A multi-file import reports failures per file, so one bad document does not discard the successful imports beside it.

From Board's Library detail panel, Export writes that markdown file and Reveal opens its location in the system file browser. This makes the file a portable editing and review format without changing the library's role as the searchable store.

Search#

Three modes:

• Full text, Postgres text search, with titles weighted above bodies.
• Semantic, meaning-based, via embeddings.
• Hybrid (default), which runs both and fuses the two ranked lists by position, so a document that ranks well either way surfaces.

Embedding is best-effort. If the local model host is down when a document is written, it is stored without a vector and stays findable by text search; a warning is printed and nothing fails. A later reembed pass backfills anything missing, and writes only when the embedding succeeds, so an outage can never destroy vectors you already had.

A search that falls back to full text says so. The agent's library_search result names the retrieval that ran; toryo library search --envelope gives scripts the same information.

In board#

The Library screen browses, filters, and reads documents with markdown rendering, and is where you author, edit, export, reveal, or import them.

From a terminal, toryo library stats counts every document, including global documents omitted from earlier totals, and splits global from project-scoped.

Full command surface: CLI & contract reference.