LLM Wiki

@autocut-cli/llm-wiki builds a local, citation-aware wiki from an explicitly approved project scope. It can be used directly or by any MCP client, including AutoCut, Claude Code, Codex, and Hermes.

Public surface

• CLI: llm-wiki
• MCP server: llm-wiki serve --root <project>
• MCP transport: stdio
• MCP tools: wiki_explore only
• Runtime: Node.js 24 or newer

The management CLI owns initialization, building, provider profiles, and structured knowledge updates. Agents querying over MCP cannot mutate the wiki.

Quick start

npm install --global @autocut-cli/llm-wiki
llm-wiki catalog --root /path/to/project --json
llm-wiki init --root /path/to/project --select README.md --yes --json
llm-wiki provider set wiki-generation \
  --kind anthropic --model YOUR_MODEL_ID
llm-wiki provider set-key wiki-generation --key-stdin
llm-wiki provider use wiki-generation --root /path/to/project
llm-wiki build --root /path/to/project --json
llm-wiki serve --root /path/to/project

provider set-key accepts the credential only on stdin, never in process arguments. The default keyring profile persists until a project selects a different profile. For headless environments, use --credential-store env --env-name YOUR_VARIABLE when creating the profile instead.

init shows only eligible first-level entries and defaults all of them to selected. Selected directories are traversed recursively. Any path segment that starts with . and every Git-ignored file are excluded.

If Git metadata is present but Git cannot verify the repository scope, cataloging, status verification, and builds fail closed with GIT_SCOPE_UNAVAILABLE; they never fall back to broader filesystem traversal. Consent also records whether Git or filesystem filtering was confirmed. If that strategy later changes, source enumeration stops with SOURCE_SCOPE_CHANGED until the user re-runs init. State created before this field existed must likewise be reconfirmed once (SOURCE_SCOPE_RECONFIRM_REQUIRED). If a build process is interrupted, the next status check reclaims its dead-owner lock and reports BUILD_INTERRUPTED, so rebuilding can resume automatically. Lock recovery is serialized with a cross-platform process lock, including recovery from a process that exits during the recovery operation.

Interactive init uses a first-level checklist: Up/Down moves, Space toggles, Enter confirms, and Escape cancels. Non-interactive callers must pass both --yes and one or more explicit --select values.

Local files

The only project file intended for commit is llm-wiki.json. Local consent, credentials references, build state, source proxies, and immutable generations live under .llm-wiki/. In Git projects, init adds /.llm-wiki/ to the repository-local .git/info/exclude; it does not edit the shared .gitignore.

Provider secrets are never written to either location. They are read from a system credential store or an explicitly named environment variable.

Compiler adapter

Production builds use an exact-pinned reviewed llm-wiki-compiler fork. It adds native compile({ embeddings: false, systemPolicy }) support and source deletion reconciliation. Tests inject a deterministic engine.

Semantic retrieval is off by default. When enabled, it uses a private SQLite derived cache over compiled Wiki pages only; raw source proxies are never the search corpus. Completed page batches are committed immediately, so a later provider failure or cancelled build can resume without resending completed pages. The embedding client supports OpenAI-compatible and Voyage endpoints.

During an incremental build, the remote embedding provider may receive a strictly length-bounded query containing the topic, source locator, and a short new-evidence excerpt from the user-confirmed source scope. This query is used only to recall existing compiled pages and is not added to the searchable corpus. No automatic secret-pattern redaction is claimed: enabling semantic retrieval authorizes this bounded query egress to the selected independent provider.

Semantic mode requires an explicit embedding profile whose name and credential both differ from the Wiki generation profile and credential. The generation key is never passed to the embedding client. A successful build records only the embedding profile, provider kind, model, availability, and a reason code in its manifest—never a credential.

llm-wiki provider set wiki-generation \
  --kind openai-compatible --model generation-model \
  --credential-store env --env-name WIKI_GENERATION_KEY
llm-wiki provider set wiki-embedding \
  --kind voyage --model voyage-3 \
  --credential-store env --env-name WIKI_EMBEDDING_KEY
llm-wiki provider use wiki-generation --root /project
llm-wiki provider use-embedding wiki-embedding --root /project
llm-wiki semantic enable --root /project
llm-wiki build --root /project

At build and query time, a missing or changed embedding profile, missing credential, bad index, or provider failure produces a stable semantic reason code and falls back to lexical retrieval from compiled Wiki pages in the last good generation.

serve is strictly read-only and exits with its stdio client. Automatic builds run only under the explicit llm-wiki watch --root <project> process; a query never starts a build.

status verifies the approved source scope by default. Polling integrations can use status --fast to read the committed generation and runtime state without rescanning or hashing project files; their watcher remains responsible for marking source changes stale.

Client registration

llm-wiki install and llm-wiki uninstall delegate registration to the installed Claude Code, Codex, and Hermes CLIs. They do not edit those clients' configuration files directly. Missing clients produce stable reason codes; Hermes keeps its required interactive discovery flow.

Management JSON contract

With --json, stdout is exactly one JSON envelope:

{"ok":true,"command":"status","data":{}}

Failures use:

{"ok":false,"command":"build","error":{"code":"ERROR_CODE","message":"..."}}

Structured knowledge never travels in process arguments:

printf '%s' '{"id":"decision-1","title":"Decision","text":"Use stdio."}' |
  llm-wiki upsert --root /project --json

delete likewise reads {"id":"decision-1"} from stdin.