# xyz-wiki

A wiki your LLM writes and keeps up to date itself, with a typed ontology, works with any agent that supports MCP.

You give the model your stuff and it turns it into small linked pages, one concept, entity or claim per page, with
typed relations between them (`is_a`, `part_of`, `contradicts`, ...). Its answers get filed back as pages too, so the
wiki keeps growing as you use it, and a lint pass finds what needs fixing. Search is plain keyword search (BM25) plus a
walk over the ontology graph, no embedding model, no vector database, no GPU needed.

- The only thing you need is Node 22.13+ (the built-in `node:sqlite` with FTS5), the code is three files.
- Pages are just markdown files with OKF-style front matter, the index is a cache rebuilt from them, so it all works
  fine with git.
- It stays quick when it gets big, on our PC a 2,000-page wiki answers a search in under 80 ms and reopens in under a
  tenth of a second, only the files that changed get read again.
- The MCP server (stdio) works with DeepSeek Harness, Claude Desktop/Code, OpenClaw, Cursor, anything that supports MCP.
- The model does the organizing, the server only stores, indexes and retrieves, and `skills/xyz-wiki/SKILL.md` tells
  the agent how to ingest, answer and maintain.

## Install

```sh
git clone https://github.com/xyznq1/xyz-wiki.git && npm install -g ./xyz-wiki   # Node.js 22.13+, no dependencies
cd xyz-wiki && npm test                                                    # optional: the test suite
```

## Connect your agent

The server takes the wiki folder as its argument (or `XYZ_WIKI_DIR`) and creates it on first use.

DeepSeek Harness: `dsh/xyz-wiki.patch.yml` is a ready overlay, it runs the agent on your own OpenAI-compatible model
server (llama.cpp, vLLM, Ollama) with the xyz-wiki MCP server and the skill, telemetry off. Set the endpoint and model
id in the patch, then run:

```sh
export XYZ_WIKI_HOME=/path/to/xyz-wiki XYZ_WIKI_DIR=~/xyz-wiki
dsh web --patch $XYZ_WIKI_HOME/dsh/xyz-wiki.patch.yml             # or: dsh headless --patch ... "learn notes.md"
```

Claude Desktop, Claude Code and Cursor take this MCP config:

```json
{ "mcpServers": { "xyz-wiki": { "command": "xyz-wiki-mcp", "args": ["/path/to/wiki"] } } }
```

OpenClaw: set `mcp.servers.xyz-wiki = { command: "xyz-wiki-mcp", args: ["/path/to/wiki"] }`, then allow the tools
(`xyz-wiki__wiki_search`, ...) in `tools.allow`.

Then give the agent the skill (or paste its steps into the system prompt) and hand it stuff, "learn this", "what do we
know about X", "clean up the wiki".

## Tools

| tool | what it does |
|---|---|
| `wiki_search` | BM25 over title, aliases and body: snippets of the best pages, plus pages one ontology hop away |
| `wiki_read` | one page, front matter and body |
| `wiki_write` | creates or updates a page. A new body replaces the old one; relations, sources and aliases get merged |
| `wiki_relate` | adds one typed edge to an existing page |
| `wiki_neighbors` | typed relations and `[[links]]` around a page, both directions, up to 3 hops |
| `wiki_list` | titles, optionally of one type |
| `wiki_lint` | orphans, dangling links, untyped pages, stale pages, near-duplicate titles, totals |
| `wiki_see` | *optional:* the objects in an image (YOLOv5) and its text (Tesseract OCR), so a text-only model can learn from screenshots, charts and scans |

### Vision (optional)

`wiki_see` shows up when `XYZ_WIKI_PYTHON` points at a Python that has `yolov5` installed. YOLOv5 is AGPL-3.0, so you
install it yourself, we don't bundle it. Reading text needs the Tesseract binary on PATH (or `TESSERACT`), and each
half works without the other.

```sh
python -m venv ~/xyz-vision && ~/xyz-vision/bin/pip install yolov5
~/xyz-vision/bin/yolo settings sync=False                 # Ultralytics analytics off
export XYZ_WIKI_PYTHON=~/xyz-vision/bin/python XYZ_VISION_WEIGHTS=yolov5s.pt   # fetched on first use
```

`XYZ_VISION_CONF` sets the detection threshold (default 0.25). To test it, run `XYZ_WIKI_TEST_IMAGE=photo.jpg npm test`.

## A page

```markdown
---
title: Fair Value Gap
type: concept
status: draft
aliases:
  - FVG
sources:
  - resource: sources/notes-2026-09.md#fvg
relations:
  - is_a: Price Imbalance
  - related_to: Order Block
generated: 2026-09-28
updated: 2026-09-28
verified: unverified
---
A three-candle pattern where the first and third wicks do not overlap: price moved faster than orders filled.
See [[Order Block]].
```

`type` is the only field a reader needs. `status` (draft/stable/deprecated), `sources`, `verified`
(unverified/machine-confirmed/human-reviewed) and `stale_after` follow the Open Knowledge Format (OKF v0.2).

## CLI

```sh
xyz-wiki ./wiki stats | lint | list [type] | search <words> | read <title> | reindex
```

## Why it's built like this

- No embeddings. A small, well-linked wiki the model wrote itself can be searched by the words it uses, and the
  ontology covers what keyword search misses (the `related` block in every search result), so there's no extra
  service to run and nothing to re-embed when pages change.
- The model writes the pages. Searching raw chunks works the same answers out again every time, a wiki that's kept up
  to date keeps them (the "LLM wiki" pattern). Answers get filed as `type: query` pages.
- Tools return snippets and capped page bodies, never the whole thing, so the context cost stays low.

## Credits

What's ours: xyz-wiki itself, the MCP server, the index and the ontology search, the lint, the agent skill, the CLI,
the DeepSeek Harness overlay and the vision tool.

What we built on, and credit to the people who made it:
- Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) idea, the model
  writing and keeping up its own wiki instead of doing RAG over raw files every time.
- Google Cloud's [Open Knowledge Format](https://github.com/GoogleCloudPlatform/open-knowledge-format) (OKF v0.2), the
  front matter the pages use.
- SQLite's FTS5 for the BM25 search, and [YOLOv5](https://github.com/ultralytics/yolov5) by Ultralytics and
  [Tesseract](https://github.com/tesseract-ocr/tesseract) for the optional vision tool.

## License

MIT.

---

For further questions, DM us on Instagram: [@xyz_nq1](https://www.instagram.com/xyz_nq1/)