Architecture

Fisk AI is a single Go module, github.com/choria-io/fisk-ai, built on Go 1.26. The code separates cleanly into a thin command layer, three drivers that each expose the tools a different way, a shared core, and a persistence and protocol tier underneath. A handful of interface seams keep those tiers independent.

The layers

The top layer is package main at the repository root: main.go registers the subcommands and each *_command.go file owns one of them. It does flag wiring, mode selection, the signal and suspend contract, and the choice between the full-screen and line UIs. It holds no run logic of its own.

Below it are three drivers. internal/agent runs the agentic loop for run. internal/mcpserver serves the tools over MCP for mcp. internal/a2anats serves them over NATS for a2a. All three consume the same tool set from the shared core.

The core is internal/util plus config. util owns command-tree introspection, translation of tools into Anthropic API parameters, the built-in tools, the confirm gate, the prompter contract, the model call, and run statistics. config is the single agent.yaml schema and its mode-based validation.

The bottom tier is durable state and protocol types: internal/runstate journals a run, internal/memory persists model notes, internal/rag holds the SQLite knowledge index behind the knowledge_search tool, and the a2a package holds the transport-agnostic protocol messages that internal/a2anats binds to NATS. internal/remotetools sits beside the core as the import-policy layer for tools pulled from a peer agent.

Like memory, internal/rag is reached only through a built-in tool in the core: internal/util/builtin_rag.go opens a rag.Store and wraps it as knowledge_search. The agent and MCP drivers open the store read-only while the knowledge command is its single writer, so an index can be rebuilt while an agent runs. It is the one package in this tier that reaches an external system of its own, an optional local embeddings server, and only when the vector tier is on.

The seams that keep it composable

The tiers stay independent because the boundaries between them are narrow interfaces, not concrete types. Each one lets a driver swap an implementation without the core knowing.

Events

`internal/agent/events.go`. The agent decides what happened; the caller decides how it looks. `cliEvents` renders line output, `tcellEvents` drives the full-screen UI, both from the same callbacks.

Prompter

`internal/util/prompter.go`. The only path allowed to read the terminal. A line implementation (`survey_prompter.go`) and a full-screen one (`internal/tui/prompter.go`) satisfy it; deny-by-default lives at the caller, never in the prompter.

Store / Journal

`internal/runstate/store.go`. A run is an append-only record stream. The file backend is the only one today; the interface is shaped for a JetStream backend next. `Fold` turns records into resumable state with no IO.

memory.Store

`internal/memory/store.go`. A pluggable key/value store; the `file` backend exists, a NATS KV backend is the planned second.

rag.Embedder

`internal/rag/embed.go`. The knowledge vector-tier seam; the OpenAI-compatible client is the only implementation, tests mock it, and a nil embedder is the lexical-only path, so the vector tier is fully optional.

RemoteInvoker

`internal/util/remote.go`. A one-method interface so `util` depends only on `a2a` types, not the NATS binding, which avoids an import cycle and lets tests supply a fake.

One configuration, three modes

A single agent.yaml drives all three faces. config.ParseConfigForMode validates it against ModeAgent, ModeMCP, or ModeServer, each requiring a different subset of fields. The info command deliberately parses with the most lenient mode so it can inspect a config written for any face.

How a run composes

The run path threads every tier together in a fixed order.

1. Parse and select tools `main` parses the config, then `util.LoadTools` introspects the fisk binary, strips `ai:deny`, and applies include and exclude rules.
2. Set up the run `agent.Run` injects the built-in tools, imports any remote tools, builds the Anthropic tool params, constructs the confirm gate, and opens or resumes the journal.
3. Drive the loop The `runner` calls the model, runs the tools it asks for through `util.ExecuteToolUse` behind the confirm gate, and journals each event as it happens.
4. Surface it Every step is reported through `Events` to whichever UI is active, and the operator answers gates through the `Prompter`.

Tools and Introspection

The tool model is the center of the whole system. Fisk AI never lets a model run arbitrary commands. It introspects a fisk application once, turns its runnable commands into named tools, and then decides which of those tools a model is even allowed to see.

From a command tree to a tool list

ToolsForApp execs the target binary with --fisk-introspect and unmarshals the emitted fisk.ApplicationModel (fisk.go:696, fisk.go:714). ApplicationTools then walks the command tree with commandTools (fisk.go:558, fisk.go:584). The walk keeps only runnable leaf commands: a hidden command is skipped, and a grouping node with subcommands is recursed into but is not itself a tool. Every surviving leaf becomes one Tool bound to its fisk.CmdModel, the source of truth for the command’s schema and tags.

A tool’s name is its command path joined with underscores. The command auth user add becomes the tool auth_user_add (Tool.Name, fisk.go:103). That name is what the model addresses, what include and exclude rules match against, and what a remote import prefixes with its alias.

Reserved tags

Three tags carry meaning to Fisk AI itself. The rest are free-form and can only be referenced by include and exclude rules. Tags are set in the fisk command definition, or in YAML for an App Builder application.

Selecting tools

LoadTools is the pipeline (util.go:221). It always runs one filter pass first with a nil filter, which strips ai:deny and nothing else, so deny is enforced even when no rules are configured. Then, if include names any tools or tags, only matching tools are kept; if exclude names any, matching tools are dropped.

A rule’s tools entries are regular expressions matched against the tool name. Its tags entries are exact tags, where an empty string matches a tool with no tags at all. A tool matches a rule if any name regex matches or any tag is present (matchesFilter, fisk.go:666). Include and exclude can be combined: include ^cow but exclude ^cow_think.

Tool search deferral

Recent Anthropic models can search a large tool set on demand rather than receive every definition up front. Fisk AI uses this above a threshold. BuildToolParams counts local, remote, and built-in tools together; at ten or more (toolSearchThreshold, anthropic.go:21) it marks tools for deferred loading and appends the BM25 tool-search server tool. Below the threshold every tool is sent directly and no search tool is added.

A tool tagged ai:no_defer is always sent directly even in a deferred set, which keeps the handful of commands a model needs on most requests immediately available. Because the model discovers deferred tools by their description, ModelDescription appends a trailing Tags: ... line so a tag search can find them (fisk.go:126).

Running a tool

Tool.Execute turns the model’s JSON arguments into a command line with t.Model.ArgsFromJSON, the trust boundary that bounds input to the command’s schema, then runs exec.CommandContext with the argument vector (fisk.go:449). No shell is involved, so model input can never be interpreted as a shell command. A non-zero exit is a normal result carrying the exit code, not an error, so the model can react to it. Output handling and credential stripping are detailed in Safety and Human in the Loop.

The Agent Loop

The agent loop is what fisk-ai run drives. It calls the Anthropic model, runs the tools the model asks for, feeds the results back, and repeats until the model gives a final answer or a budget stops it.

Setup, then loop

agent.Run does all the one-time work before the loop starts (agent.go:119): load and validate tools, inject the built-in tools, import any remote tools, build the Anthropic tool params, construct the confirm gate, build the client, seed the conversation, compute the resume fingerprint, and open or resume the journal. It then constructs a runner and calls its loop. The runner splits its state in two: infrastructure that is rebuilt from config on every start or resume, and mutable conversation state that is resumable. That split is what makes a run suspendable.

How one iteration runs

The loop runs while the iteration count is below max_iterations (runner.go:368).

1. Check for suspend Only at the loop boundary, before the iteration index is consumed, never mid-tool, so the conversation is always left coherent (`runner.go:384`).
2. Call the model Under a per-call timeout derived from `call_timeout`. `util.CallLLM` wraps the single request in its own context (`llm.go:16`).
3. Journal the turn The assistant response is appended to the conversation and journaled before any tool runs, so a crash mid-batch resumes without re-paying for the call (`runner.go:444`).
4. Decide terminality A turn with no tool-use blocks, and not a paused turn, is the final answer and ends the run. Otherwise the tool calls are executed (`runner.go:470`).
5. Run tools and feed back Each tool result is journaled as it completes, then all results are appended as one user message that becomes the next iteration's input (`runner.go:494`).

Budgets

Two different token caps apply. defaultMaxOutputTokens (8192, or 16384 with thinking) bounds a single response so a call stays under the non-streaming ceiling (agent.go:39). The configured llm.budget.max_tokens bounds the whole run. The run budget is a soft cap checked after each call but before that turn’s tools run, so an over-budget turn incurs no further tool side effects (runner.go:490). All four token tiers, input, output, cache read, and cache create, are summed so the cap measures total throughput.

max_iterations bounds the loop count and call_timeout bounds each call. The defaults are 200000 tokens, 50 iterations, and 120 seconds.

Reporting, not rendering

The loop never draws anything. It emits typed callbacks through the Events interface, and the caller decides how they look. The same callbacks back both the line UI and the full-screen UI, which keeps the loop free of terminal concerns. Tool dispatch distinguishes local, remote, built-in, and memory tools so each is traced correctly.

Safety and Human in the Loop

Safety is the reason Fisk AI exists. Two ideas carry it: a command runs with no shell and no credentials so it is bounded by construction, and a tagged command can require a human to approve it before it runs. Both default to the safe outcome.

A command is sandboxed by construction

When the loop runs a tool, Tool.Execute passes an argument vector to exec.CommandContext. No shell is involved, so model-supplied arguments can never be interpreted as shell syntax; t.Model.ArgsFromJSON is the trust boundary that bounds input to the command’s schema. The child gets no stdin, a ten-second wait delay after cancellation, an environment with credentials stripped, and its combined output capped.

commandEnv removes five secret-bearing variables so a model-chosen command can never read the agent’s own credentials: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_IDENTITY_TOKEN, ANTHROPIC_WEBHOOK_SIGNING_KEY, and ANTHROPIC_CUSTOM_HEADERS (fisk.go:511). It appends LLMFORMAT=1 so a fisk application can render output suited to a model rather than a terminal. Output is capped at 64 KiB, keeping the head and tail with a truncation marker, so a chatty command cannot flood the model’s context.

Two ways to put a human in the loop

The two mechanisms are distinct and address different needs.

ai:confirm

An application author gates a specific command. The operator must approve it before it runs; the command itself is unchanged. Always active, no configuration flag.

human_in_the_loop

A configuration flag that gives the model three `ask_human_*` tools so it can ask the operator a question it chose to ask.

Reach for ai:confirm when a normal command should run only with the operator’s say-so. Reach for human_in_the_loop when the model should decide when to check in. The harness.confirm_tags key extends the gate to any tag an application already uses, for example impact:rw.

The confirm gate defaults to deny

When the model calls a gated command, the gate runs the checks in a fixed order, and every failure is a denial.

1. Missing parameters first A structurally invalid call is rejected before the gate, so the operator is never asked to approve a broken command (`runner.go:608`).
2. Session-allow short-circuit If the operator earlier chose "allow for the session" for this command, it runs without asking again.
3. No terminal, no run Without an interactive terminal, or with a canceled context, the gate denies before any prompt is shown (`confirm.go:76`).
4. Prompt the operator The sanitized full command line is shown. Any prompter error, an interrupt, an end-of-input, or an Escape, is a denial.

A denial is returned to the model as an authoritative, non-error result whose reason ends with a note not to retry, so the model reasons about the refusal rather than routing around a tool failure. An “allow for the session” answer is remembered by command name, regardless of arguments, and lasts only for that run.

The ask_human tools

When human_in_the_loop is enabled the model gets three tools: ask_human_confirm (yes or no), ask_human_select (choose one option), and ask_human_input (a free-text value). Each denies by default: a missing terminal, an interrupt, or an end-of-input yields a negative answer rather than a guess. Each renders on stderr so a piped final answer stays clean, and the model-supplied text is stripped of terminal control sequences first, before any truncation, so a cut can never leave a dangling escape.

Sessions and Resume

By default a run lives only in memory. With --checkpoint it is journaled to disk as an append-only record stream, so it can be suspended and resumed later, in a fresh process or on another machine. The journal is also the foundation for the durability guarantees the agent loop relies on.

A run is a record stream

A run is an ordered sequence of self-describing records. A MetaRecord is always first at sequence one. Each model turn is an AssistantRecord stored verbatim, each tool result a ToolResultRecord, each interactive follow-up a UserRecord, and the run ends with a single TerminalRecord carrying its reason. The schema is at Version = 2; a reader accepts any older version but refuses a newer one, because every version only adds records or optional fields.

Fold replays a record set into a resumable RunState with no IO (state.go:93). The state carries the committed conversation prefix, cumulative counters derived from the journal so they can never drift, the next iteration number, and any in-flight tool batch. It deliberately holds no client, credentials, or config; those are rebuilt on resume.

Suspend, crash, and resume

The ordering within a turn is deliberate: the assistant turn is journaled before any tool runs, and each tool result is journaled the instant that tool completes. That gives two semantics.

• A clean suspend is exactly-once. The terminal record marks the boundary, and resume never repeats a tool call or a model call.
• A crash resumes from the last recorded event, so at most one tool call is repeated: the one in flight when the process died, whose side effect completed but whose result never reached disk. On resume, completePending reuses journaled results for answered tools and re-runs only the unanswered ones.

Every append is a write followed by an fsync, and the first append also fsyncs the directory, so a new run survives a crash. Reading tolerates exactly one torn tail line, which is safe because on an append-only fsynced file only the last record can be incomplete.

The resume guard

Continuing a conversation against a changed model, prompt, or tool set can be incoherent, so a resume is refused when the configuration no longer matches. The fingerprint covers the model, a hash of the system prompt, a hash of the tool set, the thinking mode, and both budgets (fingerprint.go:21). Hashes are stored, never the prompt itself, so nothing leaks. A mismatch names exactly what changed and refuses unless --force is given.

Storage and locking

Sessions live under the XDG state directory, $XDG_STATE_HOME/fisk-ai/runs or ~/.local/state/fisk-ai/runs, never the working directory, so runs do not leak into repositories. Each run is a <id>.json journal plus an <id>.lock file; the directory is 0700 and journals are 0600. On unix a per-run advisory flock held for the life of an open journal prevents two processes appending to the same run, and the kernel releases it on exit so a crash leaves no stale lock. Load and List do not lock, since they only read.

Memory

Memory gives the model a small key/value store that persists across runs, so it can keep durable notes and pick them up next time rather than rediscovering them. It is opt-in, agent-mode only, and never exposed over MCP.

Four tools over one interface

When memory is enabled the model gets four tools: memory_list returns keys and descriptions, memory_read fetches one entry, memory_write saves an entry, and memory_delete removes one. All four go through the Store interface, so the storage backend is pluggable behind them.

Keys, files, and races

A key is letters, digits, and . _ = -, with no leading or trailing dot and no .. (key.go:25). The slash that a NATS KV key also permits is deliberately excluded, so a key maps one-to-one to a flat filename with no separator to traverse. ValidateKey guards every operation and filters directory entries, which makes it a path-traversal defense as well as a format rule.

The file backend stores each entry as a markdown file with a YAML frontmatter description under memory/<identity>, where the identity defaults to the application binary’s base name. Two agents pointed at the same directory share a memory; the default keeps each separate. Create and overwrite use the filesystem for atomicity: a create links a staged temp file into place and fails if the name exists, giving a race-safe create guard, while an overwrite renames over the target. Content is capped at 64 KiB, sized to what a future NATS KV backend would accept.

The start-of-run index

At the start of a run, if the index is enabled, the stored keys and descriptions are injected into the system prompt inside a <memory-index> block, so the model knows what it has saved. memory_list is the live view during the run. The index is turned off with no_index.

Knowledge and RAG

Knowledge gives the model one tool, knowledge_search, over a locally built index of the operator’s own markdown and text files, so it can ground an answer in project documentation instead of its training data. The whole retrieval system, index and search, lives in the one fisk-ai binary and one process. It is opt-in and off by default, agent-mode only, and served over MCP only through an explicit allowlist, the same posture as Memory.

Two tiers, one search

A search always runs the lexical tier and, when the vector tier is on, runs it too and fuses the two. The lexical tier is an FTS5/BM25 full-text index; it is always active when knowledge is enabled and needs no model, no server, and no per-query cost. The vector tier is a separate opt-in: adding an embeddings block turns it on, each chunk is embedded through a local OpenAI-compatible server, and a query fuses the lexical and vector rankings with Reciprocal Rank Fusion. Lexical matches on shared words; vector matches on meaning, so a query finds the right section even when it shares no keywords with it.

Search runs FTS5 first (ftsSearch, search.go:104), then, if an embedder is configured, embeds and normalizes the query and runs a KNN over the sqlite-vec table (vecSearch, search.go:123). Each retriever over-fetches searchFanout = 50 candidates (search.go:25), rrf fuses the two ranked lists with the constant rrfK = 60 (search.go:20, search.go:286), and the top_k survivors are hydrated into cited hits. RRF fuses by rank, not score, so the incomparable scales of BM25 and L2 distance never need normalizing against each other.

Building the index

knowledge index is the single writer. It is incremental and per-file: a file whose content hash is unchanged is skipped, a changed file is re-chunked, and a walk of a full configured root reconciles deletions. Only .md, .markdown, .txt, and .text files are walked, and the store directory and any memory/ directory are always excluded.

1. Walk and hash Each eligible file's SHA-256 is compared to the stored document row; an unchanged hash skips the file, a new or changed one is queued (`ingestOne`, `index.go`).
2. Chunk `ChunkDocument` splits on ATX headings and packs blocks to roughly 1200 bytes, keeping fenced code blocks whole and folding the heading breadcrumb into each chunk (`chunk.go`).
3. Embed outside the transaction When the vector tier is on, `EmbedDocuments` runs and each vector is L2-normalized (`index.go:274`, `index.go:283`), before any write transaction opens.
4. Upsert in one short transaction The document, its chunks, and their vectors are written in a single `BeginTx` block (`index.go:287`); FTS5 triggers keep the full-text table in sync, and a foreign-key cascade clears old chunks first.

The embed step sits deliberately outside the transaction so a slow or hung embeddings call never holds the single writer slot open. The writer is serialized across processes by an advisory flock on Unix (lock_unix.go) and an O_CREATE|O_EXCL lock file on Windows (lock_windows.go), since WAL mode lets multiple processes open the file and MaxOpenConns(1) alone cannot serialize them.

The knowledge_search tool

When knowledge is enabled the agent run path opens the store read-only and builds one built-in tool (RAGTools, builtin_rag.go:38), tracked in its own slice beside the memory tools (agent.go:189). A start-of-run system note tells the model the tool exists and to consult it before answering project-specific questions (RAGSystemNote, builtin_rag.go:50). The tool takes a query and an optional top_k; the effective count is min(requested or configured, 20), and the total returned text is capped at max_injected_tokens by capHits at roughly four characters per token (builtin_rag.go:177).

Each result carries a citation token of the form relpath#ordinal plus the section’s heading path. The same token is printed by knowledge search and knowledge sources and accepted verbatim by knowledge show, so a hit resolves back to its full text. When no index exists yet the tool returns a soft index_not_built status naming the fix rather than failing the run, so a missing index never bricks agent startup.

Over MCP the tool is served only when it is allowlisted in expose.agent.mcp.builtins (MCPExposesKnowledgeSearch, config.go:726). knowledge_search is the one exposable built-in because it is read-only and needs no operator prompt; the memory and human-in-the-loop tools stay agent-only. The MCP path opens the same read-only store and closes it after the server stops (mcp_command.go:109).

The Terminal UI

The default run presentation is a full-screen terminal UI built on tview and tcell. It shows the run as it happens, folds thinking and tool output on a keypress, and can keep a chat bar open to continue after a turn. The same widget model backs the read-only transcript viewer.

Two goroutines, one writer

A live run has two goroutines. One runs agent.Run and emits Events; the other is the tview event loop that owns the screen. The run goroutine never touches widgets directly. Every cross-goroutine mutation is marshaled onto the tview loop with QueueUpdateDraw, so view state has a single writer. tcellEvents is the only producer, and it always goes through Live.Append.

Rendering and hot-keys

Each Events callback maps to one or more Line values and appends them. Narration is rendered as markdown, then escaped; everything else is sanitized and wrapped in trusted per-kind color tags, so model text can never open a color or region tag. Tool output starts collapsed. The z and Z keys toggle folding of thinking and tool output as a global view mode, since a flat text view has no per-block cursor. The view tails the run like tail -f, re-arming follow when a scroll reaches the bottom, and ? opens interactive help.

The chat bar

With --chat, an input row is added above the status bar. At each turn boundary the agent calls NextPrompt, which activates the field and blocks the run goroutine until the operator submits or leaves. Enter sends, Alt-Enter inserts a newline, Ctrl-D ends cleanly, and Ctrl-C aborts. Slash commands like /clear and /restart are resolved before the text is sent.

Keeping stdout pipeable

The full-screen UI collapses answers, narration, and traces into one viewport, so it must protect the alt-screen. muzzleStderr redirects os.Stderr into a buffer for the whole run so library logging cannot corrupt the display, then flushes it to the restored terminal on exit. The raw answer, warnings, and rotated-session ids are captured as they arrive and re-printed to real stdout and stderr after teardown, so a piped answer still lands on stdout exactly as the line UI would deliver it.

Interoperability: MCP and A2A

The same tool model that backs the agent loop can be served two other ways: over the Model Context Protocol for a client like Claude Desktop, and over a NATS-based agent-to-agent protocol for peer agents. A run can also import a peer’s tools and present them to the model as if they were local.

Serving over MCP

mcp serves util.ServedTools, the loaded set narrowed by expose.agent.tools, over streamable HTTP. The port comes from --port, then the config, then a default of 8080. Each tool keeps its fisk input schema. A tool with a name the protocol rejects is skipped with a warning.

A confirm-tagged command is realized over MCP as an elicitation that asks the client for an approve boolean, driven by a confirm mode: auto asks clients that can elicit and runs others ungated with a warning, always refuses a client that cannot elicit, and never delegates approval to the client’s own UI. The gate fails closed on anything that is not an explicit accept.

A2A over NATS

The a2a package models the protocol as self-describing messages. Every message embeds a Header carrying its own framing, so a captured message is fully decodable without the transport. The NATS binding never infers meaning from the subject; it decodes the header’s protocol id and dispatches on that. The subjects exist only as permission seams, which is what lets the same message bodies move to another transport later without change.

Both servers bound an un-budgeted caller: a shared semaphore caps in-flight calls at two and a per-call timeout defaults to thirty seconds. An execution failure is always an in-band error result, never a transport error, and a non-zero command exit is a successful result carrying the exit code, so the caller can reason about either.

Importing a peer’s tools

A run with configured remote hosts discovers each one, filters by name, and assigns final model-facing names. A bare name is prefixed with the host’s alias when a local tool already holds it or when more than one host exposes it, decided over the whole set so runs are reproducible. A residual collision fails the run closed. The imported schema is untrusted and must parse as a JSON object. At call time a remote tool is invoked over NATS and its reply is mapped back to the same result shape a local tool produces, so the model cannot tell remote from local. Import is strict for a run, since the prompt may depend on those tools, but best-effort for info, which still shows local tools if a host is unreachable.

Reserved and planned

The streaming task flow, the Event, Result, Cancel, and Ack messages with their event blocks, is fully modeled and schema-validated but not yet carried by the NATS binding, which transports only discovery and direct tool calls. Wrapping the same message bodies in the Choria Protocol, with its authentication and authorization, is the planned second binding; the subject-contract design exists so that binding needs no change here.

Reference and Map

A quick index into the codebase: what each command does, where each package lives, the types worth knowing, and the vocabulary the rest of this map uses.

Command surface

main.go registers seven commands on the fisk-ai root. Each is defined in its own *_command.go file.

Source-file map

Key types

Glossary

Tool

A single runnable fisk leaf command exposed to the model, named by its command path joined with underscores.

Introspection

Running a fisk binary with `--fisk-introspect` to read its command tree as a model.

Deferral

Sending tool definitions on demand through the tool-search tool once the set reaches ten tools, rather than all up front.

Confirm gate

The default-deny check that makes an operator approve a command tagged `ai:confirm` or a `confirm_tags` tag before it runs.

HITL

Human in the loop: the `ask_human_*` tools the model can call to ask the operator a question.

Journal

The append-only record stream a checkpointed run writes to disk, event by event.

Fold

Replaying a record stream into a resumable `RunState` with no IO.

Fingerprint

A hash of model, prompt, tool set, thinking mode, and budgets that must match for a resume to proceed.

Identity

An agent's logical name, defaulting to the binary base name, used for the memory directory and the A2A subjects.

Elicitation

The MCP mechanism by which a served command asks the calling client to approve it.

Agent card

An A2A agent's self-description: name, version, protocols, and tools.

RAG

Retrieval-augmented generation: searching a local document index and feeding the matches to the model as grounding.

Chunk

A heading-delimited, size-packed slice of a document, the unit that is indexed, ranked, and cited.

Lexical tier

The always-on FTS5/BM25 full-text search over chunks; needs no model or server.

Vector tier

The opt-in semantic search: chunk embeddings in sqlite-vec, matched by nearest neighbor.

RRF

Reciprocal Rank Fusion: combining the lexical and vector rankings by rank rather than score, with constant K=60.

Citation

A `relpath#ordinal` token naming a chunk, resolvable back to full text by `knowledge show`.