Home

Welcome to the llm-wiki wiki!

llm-wiki

A self-healing, local-first knowledge base where a local LLM compounds your documents across four memory tiers — working, episodic, semantic, and procedural — with bi-temporal facts, automatic contradiction resolution, and scheduled memory maintenance.

llm-wiki is a FastAPI service that turns a folder of raw documents into a continuously self-organising Markdown wiki. Drop PDFs, DOCX, PPTX, XLSX, HTML, or Markdown into the ingest endpoint and the system extracts entities, claims, and relations; writes confidence-scored pages; and keeps them honest over time through bi-temporal fact tracking, Ebbinghaus decay, and weekly self-lint runs.

The wiki conforms to Google's Open Knowledge Format (OKF) v0.1 — every page carries typed YAML frontmatter and bundle-relative links, so the whole knowledge base exports as a portable OKF bundle (and external bundles import as curated, high-trust pages).

PyPI: pip install llm-compounding-wiki (import package: llm_wiki)
Docs: https://krishddd.github.io/llm-wiki/
License: MIT

Why this exists

Most "chat-with-your-docs" stacks throw documents into a vector store and walk away. After three months they are full of stale claims, duplicate entities, and dangling references. llm-wiki treats the knowledge base as a living artefact that has to be maintained — it promotes recurring ideas, decays unreinforced ones, supersedes facts when newer sources contradict older ones, and crystallises repeated query patterns into reusable procedures.

The four memory tiers

Tier	Where	Lifetime	Contents
Working	in-process state	one request	retrieved candidates, draft answer
Episodic	`wiki/episodic/<date>.md`	14 days (config)	every ingest / query / lint event, correlation IDs
Semantic	`wiki/sources/`, `wiki/entities/`	indefinite, decays	consolidated pages, auto entity pages
Procedural	`wiki/procedures/` + `procedures.db`	indefinite	recurring query patterns crystallised into procedures

Promotion rules: a topic recurring ≥ 3 times across ≥ 14 days of episodic auto-promotes to semantic (daily 04:00 UTC); a query pattern recurring ≥ 5 times becomes a procedure (weekly Sun 06:00 UTC); a high-confidence answer (≥ 0.80, ≥ 2 citations) is saved back immediately at query time.

Architecture at a glance

flowchart LR
    subgraph IN["Input"]
        DOCS["Raw docs<br/>PDF · DOCX · PPTX · XLSX · HTML · MD"]
        OKFIN["External OKF bundles<br/>(curated, no LLM pass)"]
    end
    subgraph ING["Ingest pipeline"]
        direction TB
        REDACT["Privacy redaction"] --> PLAN["Agentic chunk plan"]
        PLAN --> SUMM["Summarise + extract entities/claims"]
        SUMM --> CONF["Merge + confidence gate"]
        CONF --> D2Q["Doc2Query questions"]
        D2Q --> AUTO["Review Autopilot<br/>staged pages verified vs source"]
    end
    subgraph STORE["Knowledge store"]
        direction TB
        WIKI["Markdown wiki = OKF bundle"]
        KG["Knowledge graph<br/>bi-temporal facts, SQLite"]
        IDX["Indexes<br/>BM25 + dense + hq units"]
    end
    subgraph QRY["Query pipeline"]
        direction TB
        CACHE{"Semantic answer cache<br/>cosine ≥ 0.95? (opt-in)"}
        CACHE -- "miss" --> ORCH["Agentic orchestrator"]
        ORCH --> RET["Hybrid retrieval<br/>RRF · rerank · small-to-big · MMR"]
        RET --> SYNTH["Synthesis + citations<br/>+ NLI claim verification"]
    end
    SCHED["Scheduler<br/>decay · promote · review · lint · procedures · topics"]
    DOCS --> ING
    OKFIN --> WIKI
    ING --> STORE
    STORE --> QRY
    CACHE -- "hit" --> ANS["Cited answer"]
    SYNTH --> ANS
    ANS -- "save-back if conf ≥ 0.80" --> WIKI
    SCHED --> STORE
    WIKI -- "export" --> OKFOUT["Shareable OKF bundle"]

Key capabilities

Provider-agnostic fleet — every LLM role (summary / reason / fast / solver / embed / vision) points at Ollama (default, local) or any OpenAI-compatible provider (Groq, GitHub Models, Gemini, OpenAI, Anthropic, xAI, OpenRouter, or a custom vLLM/LM Studio gateway) with one env var. HTTP errors fall back to Ollama automatically.
Best-of-best RAG package — small-to-big retrieval, Doc2Query, lost-in-the-middle reorder, NLI-lite claim verification, machine-page down-weight, RAPTOR-lite topic pages.
2026 adaptive upgrades — adaptive model routing (quantitative questions → a maths/STEM specialist), domain detection, agentic retrieval + ingestion, privacy redaction, optional multimodal graph and semantic answer cache.
Governance & learning — a runtime-enforced profile/schema contract at the write surface, plus a feedback curator that turns corrections/preferences into durable memory.
Bi-temporal facts — a new source never deletes an old fact; it marks it superseded (valid_to, superseded_by). Confidence decays with a 90-day half-life and is reinforced on access.
Evaluation harness — golden Q/page generation, recall@k / MRR / hit-rate, one-flag-off ablations, and full answer eval (keyword coverage, groundedness, confidence).

Quickstart

pip install llm-compounding-wiki          # core pipeline + FastAPI app
pip install "llm-compounding-wiki[mcp]"   # + agent-facing MCP server

llm-wiki serve --port 8000                # run the API
llm-wiki mcp                              # run the MCP server

From source:

git clone https://github.com/krishddd/llm-wiki.git
cd llm-wiki
pip install -e ".[dev]"
cp .env.example .env
# fully local: ollama pull qwen3:14b gemma4:e4b nomic-embed-text
# or bring your own: PROVIDER_REASON=anthropic ANTHROPIC_API_KEY=sk-ant-...
uvicorn llm_wiki.api:app --reload --port 8000

Ingest and query:

curl -F files=@paper.pdf http://localhost:8000/ingest
curl -X POST http://localhost:8000/query \
     -H 'Content-Type: application/json' \
     -d '{"question": "What did the paper conclude about transformer scaling?"}'

Validation

Exercised end-to-end against hosted models (NVIDIA build.nvidia.com, and a mixed vLLM + OpenAI fleet): ingest went live at confidence 0.95; retrieval recall@5 / MRR / hit-rate 1.000 across baseline + 4 ablations; answer-cache precision correct at threshold 0.80; 145 unit + integration tests, ruff-clean. The README documents the honest caveats (small corpus, citation-marker strictness) and the real robustness bugs the live runs surfaced.

Learn more

CLAUDE.md — full page schema and frontmatter contract
AGENTS.md — the agent tool catalogue (MCP)
docs/design/ — design notes (e.g. the multimodal-graph rollout)
CONTRIBUTING.md / CHANGELOG.md — dev setup and change history

Navigation Menu