llmwiki-serve

llmwiki-serve is the read-only source layer for existing Markdown, Obsidian-style, and LLMWiki folders. It projects files you already own into agent-readable source evidence over local HTTP and MCP-style tool surfaces.

Use QuickStart for copyable first-run commands. This page explains what the source layer owns and where its boundaries are.

Source And Projection Ownership

The source folder remains the source of truth. Your authoring tool, compiler, wiki workflow, or upstream producer owns the Markdown files and any sidecar metadata it writes.

llmwiki-serve owns only the served projection:

• source identity and manifest metadata
• approved page discovery
• link, tag, source-ref, and graph hints derived from the files
• query, search, read, source-ref, source-bundle, and graph responses
• local process discovery for running source servers
• optional derived graph-cache rows when GraphStore is explicitly enabled
• optional post-query action guidance when a System-One/Jev provider is explicitly enabled by the operator

It does not write back into the source folder, compile upstream material, run ingestion jobs, call a model by default, or synthesize final answers.

What It Reads

The server reads compatible local Markdown/wiki folders. A source can be an existing project wiki, an Obsidian-style vault, LLMWiki compiler output, or an OpenWiki-style Markdown folder that the adapter recognizes.

The projection can use:

• Markdown files and frontmatter
• wiki links, Markdown links, headings, tags, and page roles
• source references declared by approved pages
• optional producer or sidecar metadata when supported by the adapter

Draft and unapproved pages are withheld from default retrieval surfaces. Enable draft serving only in a trusted local workflow where the operator expects those pages to be visible.

What It Serves

llmwiki-serve exposes a local Knowledge Source surface:

Surface	Purpose
/health	Source readiness, version, endpoint, and capability discovery.
/manifest	Redacted source metadata and projection summary.
/query	Context packs with orientation, ranked evidence, limitations, and graph hints.
/search	Candidate pages without the full context-pack envelope.
/read/{page_id}	Full page content after a query or search identifies a page.
/source-refs	Visible source-owned citation handles.
/source-bundle	Source identity, projection metadata, capabilities, and source refs.
/graph/neighborhood	Bounded graph neighborhoods for page, source-ref, tag, or link seeds.
/mcp and /mcp/stream	MCP-style JSON-RPC and Streamable HTTP tool surfaces where supported.

CLI commands such as manifest, query, search, source-refs, and source-bundle run directly against a local source path. serve starts the HTTP/MCP source server. ls and status inspect local running instances from registry records and OS process command lines.

Redaction And Security

The default first-run bind is 127.0.0.1. Keep it on loopback until you have reviewed draft handling, CORS policy, authentication, logging, TLS, and who can reach the endpoint.

Network responses redact the local root where the public contract does not need it. CLI output and local registry commands may include local operator paths so you can verify which folder is being served; redact those before sharing logs, issues, screenshots, or traces.

Local I/O debug logging is operator state. It may include user queries and approved wiki content even when credential-shaped fields are redacted. Disable or redirect it when that is not appropriate for the environment.

Local discovery is also operator state. llmwiki-serve ls/status reads the per-user registry written by serve and can inspect local process command lines to find unregistered llmwiki-serve serve processes. It does not use default fixed-port heuristic probing; --probe-port <port> is only an explicit manual diagnostic. JSON output can mark where a record came from with discovery_source and where a root came from with root_source.

Freshness And Caching

The strict local default checks source freshness before served responses. That keeps edits visible during authoring and tests.

For larger sources, operators can choose a positive refresh interval to reuse an in-memory projection between checks. That improves repeated reads but means recent edits may not be visible until the interval expires. Generated sources can also use a producer-owned freshness marker when the producer updates that marker after every source-changing compile.

Projection signatures and bundle IDs are derived from the served projection, so clients should treat them as source-owned coordination metadata instead of trying to infer local file paths.

Optional SQLite GraphStore Cache

The current llmwiki-serve==0.2.14 package includes the SQLite GraphStore code in the base install. There is no [sqlite] or [graph] extra for the built-in SQLite cache. The default remains off, so ordinary quickstart and package-installed runs keep the in-memory graph projection unless the operator enables a store:

llmwiki-serve serve /path/to/wiki \
  --graph-store sqlite \
  --graph-store-path <outside-root.sqlite>

The environment-variable equivalents are LLMWIKI_GRAPH_STORE=sqlite and LLMWIKI_GRAPH_STORE_PATH=<outside-root.sqlite>.

Use a path outside the served source root. The SQLite file is disposable cache, but it is still sensitive derived data because it can contain graph nodes, edges, labels, paths, and metadata derived from private source files. Do not commit it, serve it as a public asset, or store it inside the wiki folder.

Startup should fail early when sqlite is selected without a usable --graph-store-path or LLMWIKI_GRAPH_STORE_PATH. Runtime cache failures use the configured failure policy: the default fallback-local recomputes graph payloads from the current projection, while fail-fast reports the GraphStore failure instead of serving a recomputed graph.

Optional System-One/Jev Query-Action Judgment

Serve 0.2.13 can add a post-query action hint for direct agents that already use /query or MCP llmwiki_context. The feature is disabled by default. An operator enables it explicitly:

export LLMWIKI_QUERY_ACTION_JUDGE_API_KEY="<your-provider-key>"

llmwiki-serve serve /path/to/wiki \
  --query-action-judge system-one

The same setting is available through LLMWIKI_QUERY_ACTION_JUDGE=system-one. LLMWIKI_QUERY_ACTION_JUDGE_API_KEY is the preferred key environment variable; TYPESAFE_API_KEY and JEV_API_KEY are accepted as compatibility aliases. Provider keys are environment-only; do not put real keys in public docs, shell history examples, CLI arguments, or shared issue logs. Optional provider settings are LLMWIKI_QUERY_ACTION_JUDGE_MODEL, LLMWIKI_QUERY_ACTION_JUDGE_ENDPOINT, LLMWIKI_QUERY_ACTION_JUDGE_BASE_URL, and LLMWIKI_QUERY_ACTION_JUDGE_TIMEOUT_MS.

When enabled, context packs can include retrieval_action_guidance, an additive field that recommends one next retrieval action: stop, read, search, graph, or ask_clarification. The guidance is not an answer, does not rerank evidence, and does not change source parsing, GraphStore, OKF, MCP, or draft-visibility behavior.

The provider receives masked query text plus structural state such as evidence counts, route labels, score buckets, snippet lengths, source-ref counts, path depth, graph counts, and overlap ratios. It does not receive raw page text, raw snippets, page ids, source-ref labels, raw paths, local roots, private URLs, or obvious credentials.

Comparison area	Default off	System-One/Jev on
Provider calls	0; retrieval stays local.	One post-query judgment call when configured.
Agent next step	The caller decides from the full context pack.	The caller gets a bounded next-action recommendation.
Decision input	Full 7,095 byte public-sample ContextPack.	3,124 byte masked structural provider request body (56.0% smaller).
Failure behavior	Baseline output.	Missing key reports unconfigured; provider failure reports failed; evidence is preserved.

This is not a live-provider speed claim. A provider round trip can make the current query slower. The intended benefit is fewer unnecessary follow-up tool calls and a smaller, masked external decision payload.

Protocol Posture

The public contract is a Knowledge Source over local HTTP, plus MCP-style and MCP Streamable HTTP surfaces where implemented by the installed package and client. Legacy A2A-style source compatibility is opt-in when a client requires that adapter surface.

These are integration surfaces, not broad certification claims. Do not describe the project as certified MCP or certified A2A unless a separate conformance effort documents that status.

Boundaries With Other Components

Component	Relationship to llmwiki-serve
llmwiki-bridge-start	Guided next step after the source layer works. It discovers folders, starts loopback sources, registers optional bridge sources, and runs smoke checks.
llmwiki-agent-bridge	Optional companion endpoint. It fans out across selected sources, can call a configured runtime, and returns a normalized cited artifact. It does not read local source files directly.
llmwiki-chat	Optional browser workbench for humans to inspect source readiness, graph context, citations, bridge settings, and traces. It does not serve the wiki files.
RAG apps and vector databases	Separate retrieval architectures. The default llmwiki-serve path remains lexical and read-only. Optional vector or hybrid retrieval, when installed and explicitly enabled, uses a source-owned local sidecar for derived chunk/index data; it does not write into the served source folder, imply a remote vector database, expose a private endpoint, or own answer quality.
Upstream wiki producers	Own authoring, ingestion, compilation, and source file layout. llmwiki-serve reads the compatible output after it exists.

The practical rule is simple: start with one SOURCE_PATH, get one SOURCE_URL, verify evidence, and add other components only when they remove a specific local workflow hurdle.