knowledge-wiki

Knowledge Wiki

A system for turning raw source material into a concise, cross-linked, human-readable wiki. raw/ holds what you collect; wiki/ holds what the model curates. Every page is predictable, one-topic, and links to related pages so the knowledge forms a graph.

Core principle

Grow the knowledge base by adding pages, not by growing a page. When a page starts covering more than one topic, split the extra topic into its own page and link to it. This keeps every page concise and scannable.

Directory layout

The wiki root is the folder that contains everything below. When a root isn't given explicitly, it defaults to ~/brain (override with an explicit path or the $BRAIN_DIR environment variable). Pass it to every script, e.g. uv run scripts/lint.py ~/brain.

index.md
log.md
raw/                 # source material — you put content here
  papers/
  articles/
  books/
  notes/
  meetings/
    <dt>-<meeting-name>.md
wiki/                # LLM-curated content
  summaries/         # what a single source says (content page)
  analyses/          # what you make of one or more sources (content page)
  concepts/          # evergreen explanations of an idea (content page)
  dashboards/        # link rollups spanning many pages (content page)
  entities/          # the things: people, orgs, projects, meetings, ...
    <type>/
      <entity>.md            # flat while small, e.g. person/anirudh-aggarwal.md
      <entity>/index.md      # promoted to a folder once it grows (see references/growth.md)

Entities are grouped by type (one folder per type), each instance a flat kebab-case .md file. Keep wiki/ organized but shallow.

Workflow

1. Capture raw material under the right raw/ subfolder, unchanged — manually or with scripts/clip.py for web articles. See references/capture.md.
2. Identify the entities and topics it concerns. Search first (see below) to reuse existing pages instead of duplicating them.
3. Curate or update the matching wiki/ page(s) using the base schema plus the entity's extension (see references below). Overwrite to reflect current understanding — do not append an edit log.
4. Link every page to related pages with relative Markdown links.
5. Lint with scripts/lint.py before considering the work done.

To process new or changed raw files in bulk, run scripts/ingest.py — it detects what changed under raw/ and drives a scoped researcher agent (research + Microsoft 365 WorkIQ tools) through steps 2–5 for each file, then refreshes search. See references/ingest.md.

Tools

Run scripts with uv run so inline dependencies are provided automatically:

Script	Purpose	Reference
scripts/clip.py <url>	Clip a web article into raw/articles/	capture
scripts/ingest.py	Curate changed raw/ files into wiki/	ingest
scripts/index.py	Regenerate the index.md catalog	—
scripts/reindex.py	Refresh the optional qmd search index	search
scripts/lint.py	Validate the wiki against conventions	linting

index.md is the regenerated catalog of every page; log.md is an append-only activity log — add a line like ## [YYYY-MM-DD] ingest | <source title> when you ingest a source.

Search

Search before creating a page (avoid duplicates) and before answering a non-trivial question (ground it). Use the agent's built-in read/search, or the optional qmd keyword + semantic index for better recall over both wiki/ and raw/. qmd is the default search path and degrades gracefully when not installed. See references/search.md.

Supported entities

Track these by default; only add a new type if clearly relevant (ask first).

Type	Reference
person	references/entities/person.md
organization	references/entities/organization.md
location	references/entities/location.md
event	references/entities/event.md
product	references/entities/product.md
project	references/entities/project.md
meeting	references/entities/meeting.md

Read only the reference for the type you are working on. Each reference documents that type's extra frontmatter fields and body layout as deltas from the base schema below.

Content pages

Beyond entities, wiki/ holds four kinds of derived-knowledge pages. Together with raw/ they form a pipeline: raw source → summary (what it says) → analysis (what you make of it) → concept (the durable idea) → dashboard (navigational rollup). Entities are the actors these pages refer to.

Type	Question it answers	Reference
summary	What does this one source say? (neutral, one per source)	references/pages/summary.md
analysis	What do I make of these sources? (synthesis, opinion)	references/pages/analysis.md
concept	What is X, evergreen and reusable?	references/pages/concept.md
dashboard	What's the current state of this area? (link rollup)	references/pages/dashboard.md

Content pages use the same base schema and page rules as entities. The exception is dashboards, which intentionally span topics and are exempt from the page-length limit.

Base schema

Every page — entity or content — starts from this. type is the singular, lowercase page type: an entity (person, project, …) or a content type (summary, analysis, concept, dashboard).

---
name: <name>
type: <entity>
status: <draft|active|archived>
tags: ["#tag", ...]
source: []
---

# Title (H1)

Lead summary of 2–3 sentences, directly under the H1 — no heading of its own.

## Overview
Current best understanding — not an edit history.

## Decisions & Rationale
Why X was chosen over Y.

## Open Questions
What is unknown, and what would resolve it.

## Related
Wiki-style links to other pages or online resources.

Page rules

• One topic per page, no mixed concepts.
• Exactly one H1 (the title); all sections are H2.
• Always start with a 2–3 sentence lead summary (no heading).
• Prefer current understanding over edit history; overwrite instead of appending clutter.
• Grow by adding pages, not by growing a page — see references/growth.md.
• Reference pages (person, organization, location) omit ## Open Questions; track unknowns on the related project or meeting instead.

Link and naming conventions

• Use relative Markdown links, never absolute paths: [Anirudh Aggarwal](../person/anirudh-aggarwal.md).
• Keep filenames stable and kebab-case so links survive in both Obsidian and GitHub Pages (including symlinked folders).
• Frontmatter link fields (orgs, projects, meetings, parent, source, …) also use relative paths.

Linting

Run the linter after any change. Use uv run so PyYAML is provided automatically (the script declares its dependency inline via PEP 723):

uv run scripts/lint.py <wiki-root>

It checks dead/bad links, page length, heading structure, frontmatter validity, and folder-layout rules. See references/linting.md for the full list of checks, severities, and configuration flags. Treat errors as blocking; review warnings and fix or justify them.