Show HN: A Karpathy-style LLM wiki your agents maintain (Markdown and Git)

Source: Hacker News

Overview

I shipped a wiki layer for AI agents that uses Markdown + Git as the source of truth, with a Bleve (BM25) + SQLite index on top. It runs locally in ~/.wuphf/wiki/ and can be git clone‑ed to take your knowledge with you. The design follows the Karpathy‑style LLM‑native knowledge substrate: agents both read from and write into the wiki, so context compounds across sessions instead of being re‑pasted each morning.

Features

• Private notebooks – each agent gets a notebook at agents/{slug}/notebook/.md, plus access to a shared team wiki at team/.
• Draft‑to‑wiki promotion flow – notebook entries are reviewed (by an agent or a human) and promoted to the canonical wiki with a back‑link. A small state machine drives expiry and auto‑archive.
• Per‑entity fact log – append‑only JSONL files at team/entities/{kind}-{slug}.facts.jsonl. A synthesis worker rebuilds the entity brief every N facts. Commits are made under a distinct “Pam the Archivist” Git identity so provenance is visible in the Git log.
• Wikilinks – [[Wikilinks]] with broken‑link detection (rendered in red).
• Daily lint cron – checks for contradictions, stale entries, and broken wikilinks.
• Lookup tools – a /lookup slash command plus an MCP tool for cited retrieval. A heuristic classifier routes short lookups to BM25 and narrative queries to a cited‑answer loop.

Substrate Choices

• Markdown for durability: the wiki outlives the runtime, and a user can walk away with every byte.
• Bleve for BM25 retrieval.
• SQLite for structured metadata (facts, entities, edges, redirects, supersedes). No vectors yet.
• Benchmark (500 artifacts, 50 queries) clears 85 % recall@20 on BM25 alone, which meets the internal ship gate. sqlite-vec is the pre‑committed fallback if a query class drops below that.
• Canonical IDs are first‑class. Fact IDs are deterministic and include sentence offset. Canonical slugs are assigned once, merged via redirect stubs, and never renamed. Rebuilds are logically identical, not byte‑identical.

Known Limits

• Recall tuning is ongoing; 85 % on the benchmark is not a universal guarantee.
• Synthesis quality is bounded by agent observation quality – “garbage in, garbage out.” The lint pass helps, but the system is not a judgment engine.
• Currently scoped to a single office; no cross‑office federation.

Demo

A 5‑minute terminal walkthrough records five facts, fires synthesis, shells out to the user’s LLM CLI, and commits the result under Pam’s identity:

https://asciinema.org/a/vUvjJsB5vtUQQ4Eb

The script lives at ./scripts/demo-entity-synthesis.sh.

Context

The wiki ships as part of WUPHF, an open‑source collaborative office for AI agents such as Claude Code, Codex, OpenClaw, and local LLMs via OpenCode. It is MIT‑licensed, self‑hosted, and works with bring‑your‑own keys. You do not have to use the full office to use the wiki layer; if you already have an agent setup, point WUPHF at it and the wiki attaches automatically.

• Source repository:
• Installation:

npx wuphf@latest

Further Discussion

I’m happy to dive deeper into:

• Substrate trade‑offs
• The promotion‑flow state machine
• The BM25‑first retrieval strategy
• Canonical‑ID stability rules

Feel free to ask why not simply use an Obsidian vault with a plugin—happy to address that as well.