ai-wiki-service

A self-synthesizing AI knowledge wiki (Karpathy LLM-wiki pattern). The successor to ai-wiki-mcp: instead of the calling agent doing synthesis, this service does it itself.

Three parts:

• UI — vanilla JS/HTML, served by the server (ingest box, file tree, wikilink graph).

• Server — FastAPI HTTP API for the UI + a read-only FastMCP surface for external agents to trace the wiki. Writes only raw/.

• Worker — a LangGraph agentic loop that, on each ingested raw document, runs the import + synthesis process against a configured model (via the LiteLLM proxy) and commits the result.

State (job queue + LangGraph checkpoints) lives in Postgres. The wiki itself is a git repo of markdown — one commit per import/synthesis run. A periodic lint pass is the correctness safety net; there is no human review gate.

See docs/plans/ for the implementation plan.

Commands

uv sync                        # install deps
uv run pytest                  # run tests (offline; DB tests need AIWIKI_TEST_DSN)
uv run ruff check src tests    # lint

For the full local dev loop (rootless Postgres, env, running the server/worker, and the manual end-to-end spikes), see CLAUDE.md.

Related MCP server: Predicate

Deployment (llm-server / VM 215)

Built as one image with two entrypoints; docker-compose runs it as three services (ai-wiki-service-{db,server,worker}) on the existing app-net bridge.

# 1. Image is built + pushed to the Gitea registry automatically by CI on merge to main
#    (.gitea/workflows/ci.yaml; bump pyproject version per PR). To build by hand instead:
#    docker build -t 192.168.10.32:3000/jhonnold/ai-wiki-service:<ver> . && docker push …

# 2. One-time host provisioning (creates + git-inits the wiki tree, seeds from live ai-wiki):
bash deploy/bootstrap.sh                       # run on VM 215

# 3. Add the three services from deploy/docker-compose.snippet.yaml into
#    ~/projects/llm-server/docker-compose.yaml, add the AIWIKI_* vars to its .env, then:
docker compose up -d ai-wiki-service-db ai-wiki-service-server ai-wiki-service-worker

The UI + read-only MCP are then at http://192.168.10.40:3011/app/ and …/mcp. The worker auto-synthesizes each ingested source and runs a lint pass after every AI_WIKI_LINT_AFTER_N syntheses. See .env.example for all settings.