aiwiki

A typed, schema-validated knowledge base for research + software development — that compounds over time.

aiwiki gives a Claude Code project a small, durable knowledge layer: typed markdown pages for decisions, gotchas, conventions, architecture, sources, and sessions, plus free-form notes. Every page is validated against a schema on write, code citations are checked for drift, and a background "dream" step consolidates the wiki (merging duplicates, promoting notes, pruning stale entries) into proposals you review and accept from the terminal.

It's extracted from the aiwiki/ layer of forge, with none of the SDLC machinery — just the knowledge base.

Install

npx @jamie-tam/aiwiki init

Run from the root of your project. Requires Node.js 18+ and Claude Code. That single command:

• installs the skills, commands, agents, and hooks into .claude/
• scaffolds the aiwiki/ knowledge base (typed-page directories + schemas + usage rules)
• adds an @aiwiki/CLAUDE.md import to your project CLAUDE.md so the usage rules load every session
• gitignores the .aiwiki/ state directory

No global dependencies — not even jq. Everything runs on Node + Bash.

Then open the project in Claude Code. /note, /wrap, /dream, and lint-on-write are ready immediately.

Page types

| Type | Directory | Answers | |---|---|---| | Decision (ADR) | aiwiki/decisions/ | "Why was this chosen?" | | Gotcha | aiwiki/gotchas/ | "Have we hit this failure before?" | | Convention | aiwiki/conventions/ | "How does this codebase do X?" | | Architecture | aiwiki/architecture/ | "What is the shape of this system?" | | Source | aiwiki/sources/ | "What did we read about X, and what did we take from it?" | | Session | aiwiki/sessions/ | "What happened last session, and where do I pick up?" | | Raw | aiwiki/raw/ | Free-form notes (/note) — promoted to typed pages by dream |

Each type's schema lives in aiwiki/schemas/{type}.md and defines its required frontmatter, sections, and line caps.

Capture (in Claude Code)

| Command | What it does | |---|---| | /note <text> | Append a timestamped research note to aiwiki/raw/{date}.md — zero friction | | /wrap [focus] | Finalize the session: writes Files touched / Decisions / Gotchas / Open questions / Next steps into a session handoff file | | /dream [scope] | Consolidate the wiki — merge duplicates, promote raw → typed, prune stale. Output is a reviewable proposal, never applied directly |

Claude also writes typed pages directly when content earns it (a hard-to-reverse decision, a reproducible gotcha, an established convention), governed by the rules in aiwiki/CLAUDE.md.

Lint

Every write to aiwiki/** is validated against its schema by a PostToolUse hook: required frontmatter and sections, line caps, and citation hashes. Code citations use file:line@<sha7> form; the hash is auto-filled on first save and flagged when the cited code drifts.

Re-lint the whole wiki any time:

aiwiki relint

Review dream proposals

Dream output lands in aiwiki/proposed/{dream_id}/ and is never auto-applied. Review and resolve from the terminal:

aiwiki status                       # list pending proposals
aiwiki show <dream_id>              # summary, operations, and per-file diffs
aiwiki accept <dream_id>            # atomic swap into aiwiki/ (originals archived to .aiwiki/history/)
aiwiki reject <dream_id> --reason "..."

Accept performs a per-file swap and refuses if the wiki changed since the proposal was created (so you never silently overwrite a concurrent edit).

Update / uninstall

aiwiki update            # sync assets to the latest version (your edits are preserved)
aiwiki update --dry-run  # preview

aiwiki uninstall            # remove aiwiki; your aiwiki/ knowledge base is KEPT
aiwiki uninstall --purge    # also remove the .aiwiki/ state dir
aiwiki uninstall --dry-run  # preview

Update detects files you've modified and preserves them. Uninstall removes only aiwiki-managed files and strips its hook entries and CLAUDE.md import — your knowledge base in aiwiki/ is never deleted automatically.

How it works

• aiwiki/ is plain markdown you can read, edit, grep, and commit. The wiki is the source of durable knowledge; it cites the code rather than duplicating it.
• .claude/ holds the skills (support-wiki-lint, support-dream, support-gotcha, support-wiki-bootstrap), the dreamer agent, the /note /dream /wrap commands, and three hooks (lint-on-write, session-handoff at session start, optional dream directive before compaction).
• .aiwiki/ (gitignored) holds operational state: the install manifest, the dream history log, and the archive of pages replaced by accepted dreams.

License

MIT