Operations

init_wiki(config::WikiConfig)

Create the full directory structure for a new LLMWiki instance: sources/, wiki/concepts/, wiki/queries/, .llmwiki/. Existing directories are left untouched.

wiki_status(config::WikiConfig) -> WikiStats

Compute summary statistics for the wiki by scanning the filesystem.

compile!(config::WikiConfig; force::Bool=false) -> NamedTuple

Run the full compilation pipeline:

1. Lock — Acquire filesystem lock to prevent concurrent compiles.
2. Detect — Load state, hash sources, classify changes.
3. Affected — Find unchanged sources sharing concepts with changed ones.
4. Extract — Call LLM to extract concepts from all changed+affected sources.
5. Late-affected — Post-extraction pass for newly discovered overlaps.
6. Merge — Merge extraction results by concept slug.
7. Generate — Call LLM to generate/update wiki pages.
8. Delete — Mark orphaned pages for deleted sources.
9. Resolve — Bidirectional wikilink resolution.
10. Index — Regenerate wiki/index.md.
11. Log — Append compile operation to the log.
12. Save — Persist updated state and release lock.

If force=true, all sources are recompiled regardless of hash changes.

Returns (compiled=N, skipped=N, deleted=N).

ingest!(config::WikiConfig, path_or_url::String; filename::Union{Nothing,String}=nothing) -> String

Ingest a source into the wiki. Accepts:

• Local file paths (copies to sources/)
• HTTP/HTTPS URLs (fetches and converts to markdown)

Returns the filename of the ingested source in sources/. If filename is provided, uses that as the target filename; otherwise derives one from the path or URL.

query_wiki(config::WikiConfig, question::String;
           save::Bool=false) -> String

Answer a question using the wiki as a knowledge base via a two-step LLM-driven retrieval-augmented generation (RAG) pipeline:

1. Page selection — Present the wiki index to the LLM and ask which pages are most relevant to the question.
2. Answer generation — Load the selected pages and ask the LLM to synthesise a comprehensive answer with wiki-link citations.

If save=true, the answer is persisted as a query page in queries/ and the wiki index is regenerated.

Returns the generated answer text.

search_wiki(config::WikiConfig, query::String;
            method::Symbol=:bm25, top_k::Int=0) -> Vector{SearchResult}

Unified search over wiki pages.

Methods

• :bm25 — BM25 keyword search (default, no external dependencies).
• :semantic — Semantic vector search (requires Mem0 extension).
• :hybrid — Combination of BM25 and semantic scores.

top_k defaults to config.search_top_k when 0.

bm25_search(index::BM25Index, query::String; top_k::Int=10) -> Vector{SearchResult}

Search the BM25 index and return ranked results.

Returns at most top_k results, each with a slug, title (extracted from the indexed content), BM25 score, and a snippet from the first matching sentence.

lint_wiki(config::WikiConfig; verbose::Bool=false) -> Vector{LintIssue}

Run health checks on the wiki and return a list of issues:

• :orphan_page — Pages with no inbound wikilinks from other pages.
• :broken_link — Wikilinks pointing to non-existent pages.
• :missing_page — Concepts referenced in links but without their own page.
• :stale_page — Pages whose sources have been modified since last compile.
• :no_source — Pages that have no associated source files in state.
• :empty_page — Pages with very short body content.
• :frontmatter_orphan — Pages explicitly marked orphaned in frontmatter.

If verbose=true, INFO-level issues are included; otherwise only WARNING and ERROR_SEVERITY issues are returned.

watch_wiki(config::WikiConfig;
           callback::Union{Nothing,Function}=nothing,
           debounce_seconds::Float64=2.0)

Watch the sources directory for changes and auto-recompile the wiki.

Uses FileWatching.watch_folder() to receive filesystem events. Changes are debounced so rapid successive edits trigger only one compilation.

If callback is provided, it is called after each successful compilation with the result NamedTuple from compile!.

Blocks until interrupted (Ctrl-C / InterruptException).

Example

config = load_config("./my-wiki")
watch_wiki(config) do result
    println("Compiled $(result.compiled) pages")
end

create_wiki_agent(config::WikiConfig) -> AgentFramework.Agent

Create an AgentFramework Agent with tools for managing a LLMWiki instance.

Tools

• wiki_ingest(path_or_url) — Ingest a source file or URL
• wiki_compile() — Run the compilation pipeline
• wiki_query(question) — Query the wiki knowledge base
• wiki_search(query) — Search wiki pages by keyword
• wiki_lint() — Run health checks
• wiki_read(slug) — Read a specific wiki page
• wiki_status() — Show wiki statistics

Example

config = load_config("./my-wiki")
agent = create_wiki_agent(config)
response = run_agent(agent, "What concepts are in the wiki?")
println(response.text)