Library

The Library is a read-only virtual filesystem projected over three stores you already have: memory, workspace, and artifacts. It stores nothing of its own. It resolves paths like /ring/dev/skills into the underlying rows and adds two LLM features on top: ask (RAG over a path) and eval (an eval-set runner with drift detection). Source: .audit gap-1 §7.

Paths

Two scopes only (src/library/resolver.ts:74-116):

/ring/<name>[/<section>][/<remainder…>]
/agent/<name>/memory          # exactly this shape — nothing deeper

Relative segments (., ..) are rejected. /ring/<name> alone is valid — it resolves to the section listing (src/library/resolver.ts:89-91, 391-407); a section is required-to-be-known only if one is present. A ring has ten sections (src/library/resolver.ts:23-34), each backed by a specific store and filter:

Section	Backed by	Filter
charter	memory	memory_type=charter (singleton per ring)
skills	memory	memory_type=skill
instructions	memory	memory_type=instruction
resources	memory	memory_type=resource
decisions	memory	memory_type=decision
policies	memory	memory_type=policy
protocols	memory	memory_type=protocol
memories	memory	general types (semantic/episodic/emotional/reflective)
workspace	workspace items	folder tree, walked into via remainder; cycle-detected
artifacts	artifacts	filename-prefix match on remainder

ACL is enforced via canAccessNamespace. A ring that doesn’t exist and a ring you can’t see both surface as the same LIBRARY_PATH_NOT_FOUND (a deliberate stealth 404), so you can’t probe for ring names you lack access to (src/library/resolver.ts:118-151).

Listing and drilldown

• list / tree (buildLibraryTree, src/library/resolver.ts:489-513) resolves a path to its nodes at a given depth. Max depth is CHORUS_LIBRARY_MAX_DEPTH (default 5; src/library/validation.ts:5).
• drilldown (buildLibraryDrilldown, src/library/resolver.ts:648-679) expands recursively under caps: max_depth (default 3), max_items_per_level (20), max_total_tokens (4000), circuit_breaker (200) (src/library/validation.ts:18-29). It reports why it stopped — completed, max_depth, max_items_per_level, max_total_tokens, or circuit_breaker — so a truncated tree is never silent.

ask vs eval

ask answers a question over a path; eval runs a whole eval set against the library and scores the answers.

ask — RAG over a path

answerLibraryQuestion (src/library/ask.ts:360-466) embeds the question once, then for each context path (src/library/ask.ts:135-194): vector-searches the resolved memory scope for the top 5, expands the graph over supersedes/derives_from edges, merges by id, sorts, and feeds the result to the LLM. Optional shape (JSON-Schema validation, 2 attempts) and ground mode (extract claims[].evidence[].memory_id citations) are available; latency_budget_ms short-circuits to evidence-only with truncated=true.

ask is a separate, lighter pipeline than memory.query

Do not conflate the two (.audit gap-1 F3). memory.query runs the full ranking stack (KNN over-fetch → query router → hybrid keyword boost → decay → reranker → tiering). library.ask has none of that. Its scores are synthetic ranks, not cosine: vector hits get 1 − index/100, graph hits get seed − 0.05, fallback nodes get 0.5 (src/library/ask.ts:178,128,186). The per-context retrieval limit is hardcoded to 5 (DEFAULT_LIBRARY_ASK_LIMIT, src/library/ask.ts:23) — not request-tunable.

Two dead/degraded edges in ask

• trace.rerank_method only ever reports linear or none. The "cohere" value the type advertises is unreachable — there is no reranker in ask (.audit gap-1 F7).
• With no embedding provider configured, ask silently degrades: the vector branch is skipped and the entire subtree’s node content is dumped in as context, with no semantic ranking and no error (src/library/ask.ts:159,182-190; .audit gap-1 F12).
• Each context path is resolved twice per request — once via buildLibraryTree and once via resolveLibraryMemorySearchScope — each independently paginating the whole namespace (.audit gap-1 F11).

eval — eval-set runner with drift

eval loads an eval set (/<ring>/eval-set.md workspace item, or a workspace_item_id — exactly one required, src/library/validation.ts:31-39), runs library.ask per question, and scores against expected fragments. llm_judge defaults true → one LLM call per expected fragment (cost scales with fragments × evals); set it false for substring scoring. Pass threshold is hardcoded at 0.7, drift threshold at 0.05 (.audit gap-1 §9).

eval mutates its source artifact

After every run, eval writes the new pass rate back into the eval-set workspace item (last_eval_pass_rate / _total / _at) and computes drift_detected against the previously stored rate (.audit gap-1 §9, F8). The “read-only filesystem” framing does not extend to eval — running it changes the source eval set’s metadata.

How the Library differs from memory.query

	Library ask	memory.query
Entry point	a path (/ring/<name>/<section>)	a namespace + query
Ranking	synthetic ranks + graph hop	cosine × decayed confidence (+ opt-in stack)
Retrieval limit	hardcoded 5 per context	request limit, 3× KNN over-fetch
Scope	one or more library paths	one namespace (with optional circle filter)
Reads beyond memory	yes — workspace + artifacts too	memory only

If you want raw recall with tunable ranking, use memory.query. Use the Library when you want a path-addressable view of a ring’s whole context (memory + workspace + artifacts), or a question answered against that view.

Reach surface differs from memory

Unlike memory, the Library is not migrated to the command catalog and has no embedded MCP tools (.audit gap-1 F1, F2). It is reachable over HTTP routes and JSON-RPC; the external chorus_library_* tools map to the JSON-RPC methods, not to catalog commands. Don’t assume Library ops behave like the catalog-backed memory.* ops.