Wiki

---
name: wiki
description: LLM Wiki — persistent markdown knowledge base under .omd/wiki that compounds across sessions (Karpathy model), maintained with plain file tools
when-to-use: The user wants to store, query, or groom durable project/session knowledge ("wiki this", "wiki add", "wiki query", "wiki lint"), or significant discoveries should be captured as wiki pages instead of being lost at session end.
---

# wiki — persistent markdown knowledge base

A persistent, self-maintained markdown knowledge base for project and session knowledge (Karpathy's LLM Wiki concept): pages compound across sessions instead of evaporating with the context window.

**Port mapping (OMC → dsh).** OMC backed this skill with seven `wiki_*` MCP tools (ingest/query/lint/add/list/read/delete). omd ships **no wiki MCP server** (spec: wiki tooling is an explicit phase-2 item) — the same operations are executed with plain file tools against `.omd/wiki/`. The methodology (categories, cross-references, lint checks, git-ignored storage) is unchanged.

## Storage layout

```
.omd/wiki/
├── index.md            # catalog of all pages (maintained on every write)
├── log.md              # append-only operation chronicle
└── <category>/
    └── <page-slug>.md  # markdown with YAML frontmatter
```

Page frontmatter:

```markdown
---
title: Auth Architecture
category: architecture
tags: [auth, architecture]
updated: <ISO-8601>
---
```

## Operations (file-tool equivalents of the OMC wiki_* tools)

| Operation | How (dsh file tools) |
|---|---|
| **Ingest** | Decompose the knowledge into one or more pages; `write` each page, then update `index.md` and append to `log.md`. One ingest may touch multiple pages — prefer updating an existing page over creating a near-duplicate. |
| **Add** | Single-page quick ingest: `write` one page + index + log entries. |
| **Query** | `grep` over `.omd/wiki/` for keywords, filter by `category`/`tags` from frontmatter; read the matching pages and **synthesize the answer yourself with citations** (page names) — there is no search engine, you are it. |
| **List / Read** | Read `index.md` / read the specific page file. |
| **Delete** | Remove the page file, update `index.md`, append a log entry. Confirm with the user first. |
| **Lint** | Health-check pass: orphan pages (not in `index.md`), stale content (old `updated` vs recent project changes), broken `[[cross-references]]`, oversized pages (split candidates), structural contradictions between pages. Report findings; fix only after user confirms. |

## Categories

`architecture`, `decision`, `pattern`, `debugging`, `environment`, `session-log`

## Cross-references

Use `[[page-slug]]` wiki-link syntax between pages. Keep slugs stable — a rename must update every inbound link (lint catches misses).

## Hard constraints

- **No vector embeddings** — query is keyword + tag matching only (grep-driven).
- Wiki pages are git-ignored by default: `.omd/` (including `.omd/wiki/`) is project-local operational state.
- Prefer updating pages over proliferating them; the wiki compounds by accretion, not duplication.

## Session-boundary checklists (explicit mount/persist — replaces OMC's wiki session hooks)

dsh has no session-start / session-end hooks, so wiki "auto-mount on start, auto-persist on end" never happens by itself. Use these two **model-driven explicit checklists** instead (run them the moment something significant is learned — do not wait for session end):

**At session start / task orientation (mount)**:
1. Read `.omd/wiki/index.md` for categories/pages relevant to the task.
2. On hits → `grep` tags/keywords, read the relevant pages, carry existing conclusions into the current work — do not reinvent them.
3. No wiki directory → skip (do not create an empty wiki just for mounting).

**When a significant discovery lands / before session close (persist)**:
1. Is the discovery useful across sessions? Yes → wiki-add/ingest it per the Operations table (prefer updating existing pages).
2. Every write also maintains `index.md` and `log.md`.
3. When nothing qualifies, say so explicitly — never skip silently.

Deterministic hook-based auto-capture remains a phase-2 item (depends on the host exposing a session-event surface); until then these two checklists ARE the capture mechanism.

## State Contract (状态契约)

wiki **holds no omd mode state**: no `state_write`/`state_clear`. Its entire state is the `.omd/wiki/` content it maintains. For short-lived working notes prefer the notepad MCP tools (`mcp__omd-state__notepad_*`); the wiki is for knowledge meant to compound.