LLM Wiki

Build and maintain a filesystem-based markdown wiki that compounds over time instead of re-deriving the same knowledge from scratch.

Core Model

Use a three-layer layout:

wiki/
|-- SCHEMA.md
|-- index.md
|-- overview.md
|-- log.md
|-- raw/
|   |-- articles/
|   |-- papers/
|   |-- transcripts/
|   `-- assets/
|-- entities/
|-- concepts/
|-- comparisons/
|-- queries/
`-- todos/

• Treat raw/ as immutable source capture.
• Treat entities/, concepts/, comparisons/, and queries/ as agent-maintained wiki pages.
• Treat SCHEMA.md as the source of truth for naming, taxonomy, and page rules.
• Treat overview.md as the maintained high-level synthesis of what the wiki currently knows.
• Treat todos/ as optional but durable research-planning output for next questions, missing coverage, and follow-up workstreams.

Path Resolution

Resolve the wiki path in this order:

1. Explicit user-provided path
2. LLM_WIKI_PATH environment variable
3. ~/wiki

Use scripts/wiki_tool.py for deterministic structure checks:

# On Windows, prefer `py -3`. Any Python 3.11+ interpreter is fine.
py -3 scripts/wiki_tool.py orient --wiki C:\path\to\wiki
py -3 scripts/wiki_tool.py lint --wiki C:\path\to\wiki
py -3 scripts/wiki_tool.py reindex --wiki C:\path\to\wiki
py -3 scripts/wiki_tool.py init --wiki C:\path\to\wiki --domain "Startup research"

If the machine does not expose py or python, locate another Python 3 interpreter and invoke the script with that executable.

Existing Wiki Workflow

Always orient before doing anything substantive in an existing wiki:

1. Read SCHEMA.md.
2. Read index.md.
3. Read overview.md when it exists.
4. Read the latest entries in log.md.
5. Search existing pages for the topic before creating anything new.

Use the CLI first when available:

py -3 scripts/wiki_tool.py orient --wiki C:\path\to\wiki --lines 25

After orientation:

• Reuse existing pages instead of duplicating entities or concepts.
• Follow the schema taxonomy exactly.
• Keep every new page cross-linked to at least two existing pages when the wiki has enough content to support that.

Shell Command Hygiene

When you emit or run shell commands for wiki work on Windows:

• Always prefer single-line PowerShell-compatible commands.
• Never split a path argument across lines.
• Prefer single-quoted regex patterns when using rg from PowerShell.
• Quote full paths when they may contain spaces.
• Pass each target directory as its own argument instead of relying on shell expansion tricks.

Preferred search shape:

rg -n '(context-hub|himalaya|fish-speech|Dolphin|MiroFish|autoresearch)' .\entities .\concepts .\comparisons .\queries

If rg is unavailable, blocked, or fails to launch, fall back to PowerShell-native search instead of retrying the same command shape:

Get-ChildItem -Path .\entities,.\concepts,.\comparisons,.\queries -Recurse -File | Select-String -Pattern 'context-hub|himalaya|fish-speech|Dolphin|MiroFish|autoresearch'

Do not assume a wrapped command shown in the UI is safe to copy back into PowerShell unchanged.

New Wiki Workflow

When asked to create or start a wiki:

1. Resolve the target path.
2. Ask for the domain only if it is not already clear from the request.
3. Run init.
4. Confirm the wiki structure exists.
5. Explain the role of overview.md and todos/.
6. Suggest the next useful ingest step.

Use the generic schema template in references/schema-template.md. Only specialize the domain, date, and any taxonomy additions that the user explicitly needs.

Ingest Workflow

Use ingest when the user provides a URL, file, PDF, pasted text, transcript, or notes worth preserving.

1. Capture the source into raw/.
2. Orient if this is a fresh session.
3. Search for affected entities/concepts before creating anything.
4. Update existing pages when possible.
5. Create new pages only when the topic is central to the source or clearly deserves persistent coverage.
6. Update overview.md when the new material changes the current high-level picture.
7. Update index.md and log.md every time.

Guardrails:

• Never modify files under raw/ after capture.
• Ask before touching 10 or more existing wiki pages from one ingest.
• If sources conflict, record both claims with dates and sources rather than silently overwriting.
• Use tags already declared in SCHEMA.md; add new tags there first if needed.
• When many new raw files appear at once, cluster them by theme first and ingest in batches instead of treating every file as its own topic.

Use references/page-templates.md when creating new entity, concept, comparison, or query pages.

Query Workflow

When the user asks a domain question and a wiki exists:

1. Read index.md to identify candidate pages.
2. Search the wiki when the topic could span multiple pages.
3. Read the relevant pages.
4. Synthesize from the compiled knowledge, citing the wiki pages used.
5. File the result back into queries/ or comparisons/ only when the answer would be expensive to reconstruct.
6. Append a query entry to log.md if the result is filed.

Prefer answers like: "Based on [[page-a]] and [[page-b]]..."

File results when the output is one of these:

• a durable comparison
• a reusable research brief
• a synthesis that spans multiple pages
• a clarified framing of an open question

Do not file trivial lookups or answers that are obvious from one page.

Plan Workflow

Use planning when the wiki has enough content that the next question is "what should I investigate next?" rather than "what do we know now?"

Typical triggers:

• the user asks for next steps, priorities, gaps, or research direction
• the wiki has accumulated multiple sources in one theme
• a batch ingest reveals thin coverage, disconnected ideas, or missing comparison pages

Planning workflow:

1. Read index.md, overview.md, recent log.md, and any relevant queries/ or comparisons/.
2. Identify where the wiki is thin, repetitive, or missing a useful synthesis page.
3. Group the follow-up work into a small number of workstreams rather than a long flat task list.
4. Write or update markdown files under todos/ only when the plan is likely to remain useful after this session.
5. Keep todo files actionable and scoped. Prefer a few strong tasks over many shallow ones.
6. Reference the relevant wiki pages with [[wikilinks]] so the next work session can jump directly into context.
7. Append a plan entry to log.md when durable planning files are created or materially updated.

Todo files should usually contain:

• a short title
• why this workstream matters
• 3-7 checkbox tasks
• linked pages or source targets where relevant

Do not turn every session into planning. Use todos/ for durable next work, not chat scratch space.

Lint Workflow

Use the CLI for structural checks:

py -3 scripts/wiki_tool.py lint --wiki C:\path\to\wiki
py -3 scripts/wiki_tool.py lint --wiki C:\path\to\wiki --format json

The linter checks:

• broken wikilinks
• orphan pages
• missing index entries
• missing or malformed frontmatter
• unknown tags
• oversize pages
• log rotation threshold

Fix severe issues first:

1. broken links
2. missing frontmatter
3. missing index entries
4. unknown tags
5. orphan pages
6. page size / style issues

Reindex Workflow

Use the CLI whenever manual edits likely left index.md stale:

py -3 scripts/wiki_tool.py reindex --wiki C:\path\to\wiki
py -3 scripts/wiki_tool.py reindex --wiki C:\path\to\wiki --check

reindex rebuilds section listings, total page count, and last-updated metadata from current wiki pages.

Writing Rules

• Use lowercase, hyphenated filenames.
• Include YAML frontmatter on every wiki page.
• Keep summaries scannable.
• Prefer updating an existing page over creating a shallow duplicate.
• Keep log.md append-only except for explicit yearly rotation.
• Keep overview.md concise and high signal. It should summarize the current map of the territory, not duplicate every page.
• Do not introduce extra infrastructure. The wiki is plain markdown on disk.

Deliverables

When you change the wiki, report:

• files created
• files updated
• important contradictions or open questions
• follow-up ingest or cleanup suggestions when useful