wikimind CLAUDE.md

WikiMind — Agent Instructions

WikiMind is an LLM-powered wiki tool that maintains itself. It has two modes: a CLI (Mode B, calls an LLM provider directly) and an MCP server (Mode A, the AI assistant IS the LLM). Both write to the same .wiki/vault/ directory.

See ARCHITECTURE.md for a full architecture walkthrough.

---

Build & test

pip install -e .           # install with editable mode
pip install -e ".[dev]"    # add test deps
pip install -e ".[pdf]"    # add optional PDF support

pytest                     # run all 82 tests (no API keys needed — all LLM calls are mocked)

Requires Python ≥ 3.11. Entry point: wikimind.cli:app (Typer).

---

Project structure

wikimind/
├── cli.py          # Typer CLI — 8 commands, each loads config → WikiStore + LLMClient + Retriever → operation
├── config.py       # TOML loader → typed dataclasses (ProjectConfig, LLMConfig, WikiConfig, PathsConfig)
├── wiki.py         # WikiStore — ALL filesystem ops (read/write pages, index, log, dedup via SHA256)
├── llm.py          # LLMClient + ProviderAdapter (Anthropic / OpenAI / Ollama) — all return (json, in_tok, out_tok)
├── llm_schema.py   # Typed frozen dataclasses + parse_*() validators for all LLM tool outputs
├── retrieval.py    # Retriever protocol + 3 backends: KeywordIndex / BM25 / Qmd
├── server.py       # FastMCP server — 10 tools, path-sandboxed, background qmd embed thread
├── operations/     # Business logic (ingest, query, lint) — no direct LLM calls in CLI commands
└── prompts/        # System prompts + JSON tool schemas for each operation

---

Core pattern: adding a new operation

Every operation follows a strict 3-part structure:

1. prompts/X.py — X_SYSTEM_PROMPT string + X_TOOL JSON schema dict
2. operations/X.py — def x(store: WikiStore, llm: LLMClient, retriever: Retriever, ...) → XResult
3. cli.py — Typer command that loads config, instantiates dependencies, calls operations.x()