forge-wiki

English · 한국어 · 日本語 · 中文

A governed markdown wiki for LLM agents — and the humans they work with.

Most agent-knowledge tools are either fully automatic memory (mem0, Zep, Letta — no approval concept) or human curation services. forge-wiki holds the middle: agents write, humans gate, the index maintains itself.

Three design commitments

1. Content is curated; recency is derived. The AUTO-INDEX block in INDEX.md is regenerated from frontmatter + filename dates — a merge conflict there is resolved by regeneration, not by hand. Verified under concurrent multi-writer simulation (see tests/ — N writers up to 50, corruption injection included).
2. OKF v0.1-compatible. Files are markdown + YAML frontmatter (type, description), reserved index.md, links as edges — readable by any OKF consumer, no lock-in.
3. Scoped writes, gated merges. Each writer owns its files; cross-author changes are proposals (PR/handoff), not silent edits. HITL is the write protocol, not a feature flag. The human gate exists to add taste — personal and organizational judgment — not to catch defects: functional integrity is the machine layer's job, verified by simulation before anything reaches a reviewer.

Quick start

Nothing to install: one Python file, no dependencies beyond python3. Clone it once, keep it anywhere, call it by path.

git clone https://github.com/chrono-meta/forge-wiki.git ~/tools/forge-wiki
alias fw='python3 ~/tools/forge-wiki/bin/fw.py'   # optional — every example below uses `fw`

cd your-knowledge-repo   # the repo that will HOLD your wiki — not the clone above
fw init                  # Phase-0 audit + non-overwriting scaffold (creates signals/)
mkdir -p memory          # add whichever other sections you want; a section is just a directory
# drop markdown files into the section dirs
fw sync --write          # regenerate the recency index + llms.txt
fw doctor                # freshness + stale-pointer report

You succeeded when INDEX.md holds an AUTO-INDEX block listing your files by section and fw check exits 0. doctor is advisory — a non-zero exit from it is a report, not a failed install.

Your repo now looks like:

your-knowledge-repo/
├── INDEX.md      curated pointers on top, generated AUTO-INDEX block below
├── AGENTS.md     wiki-protocol block appended by init — the agent-facing contract
├── llms.txt      generated on every sync --write
├── memory/
└── signals/

On a merge conflict in INDEX.md: take either side, run fw heal --write. Done.

Your org's instance

fw init gives you a working index. It does not tell you what to put in it — that decision is what makes the wiki yours, and no tool can make it for you.

The pairing this is built for: a harness carries method and gates; the wiki carries your org's context. Neither substitutes for the other. A harness with no context landing site re-derives the same organizational facts every session; a wiki with no harness has no gate on what enters it.

A section axis that survived ~2 months of daily operation (981 files — the four largest sections hold 73% of them):

Section	Holds	Enters when
memory/	durable facts that outlive the session that found them	a fact will be needed again and is not derivable from the code
tracks/<project>/	per-project working records, accumulated	work on that project produced something worth re-reading
signals/	an observation or measurement that may matter later	you notice it — recorded before you know whether it pays off
handoff/	state passed between machines, sessions, or people	the next reader is not the current writer
audit/	periodic reviews on a cadence	the cadence fires, not when you feel like it
digests/	recurring external scans	an automated job lands its output

Start with two — memory/ and signals/ — and let a section appear the first time a file genuinely does not fit the existing ones. Adding a directory is cheap; a section nobody writes to is the signal to delete it, not to fill it.

Which of the two? Two questions settle most files. Can this be re-derived from the code? — if yes, it does not belong in memory/. Has a verdict been reached? — if not, it is a signals/ entry, not a decision record.

examples/org-instance/ is a minimal filled-in skeleton. Copy it into a repo you have not init-ed yet — it brings its own INDEX.md, and fw init refuses to overwrite one:

cp -r ~/tools/forge-wiki/examples/org-instance/. your-knowledge-repo/
cd your-knowledge-repo
fw init          # keeps the copied INDEX.md, still appends the AGENTS.md block
fw sync --write

Subcommands

cmd	does	fail direction
init	state-audit + scaffold (never overwrites)	refuses on existing files
sync [--write]	regenerate AUTO-INDEX block	dry-run by default
heal [--write]	collapse conflict markers / duplicate blocks, then sync	curated-region conflicts stay human
lint	frontmatter report	report-only, never rewrites
doctor	freshness + stale-pointer report	advisory
check	index-drift gate	exit 1 on drift (CI-blocking)

Status

v0.1 — extracted from ~2 months of daily operation of a private operator wiki: 981 markdown files, commits on 50 of 57 days, multi-machine (measured 2026-07-21 — git ls-files '*.md' | wc -l; the store itself stays private). The concurrency simulation in tests/ is the regression anchor for every robustness claim; nothing here is asserted that the sim did not measure.

Distribution surfaces

• llms.txt is generated on every sync --write (derived, like the index).
• bin/fw_mcp.py — zero-dependency read-only MCP server (wiki_index / wiki_get / wiki_search). Reads go through MCP; writes go through git + the gate — that asymmetry is the write protocol, not a missing feature. claude mcp add forge-wiki -- python3 <abs>/bin/fw_mcp.py <wiki_root>

See SPEC.md for the full contract.