KnowledgeBase

Personal LLM wiki. Raw sources go in, LLM writes wiki pages, lint keeps them honest.

Architecture

KnowledgeBase separates code from data:

• Outer repo (KnowledgeBase/) — Code, lint tools, templates, documentation. Public-safe.
• Generated data export (data/) — Raw sources, wiki pages, handoff documents. Postgres (reached via DATABASE_URL) is the canonical store; data/ is a generated Markdown export. See docs/db-canonical.md.

KnowledgeBase/
├── src/kb/                   CLI tools, FastMCP server (kb-mcp), service layer
├── scripts/
│   └── ingest-github.sh          GitHub source collection
├── .claude/skills/               Runtime workflow contracts + bundled templates
│   ├── wiki-authoring/             Wiki page templates and authoring rules
│   ├── wiki-approval/              review_status lifecycle workflow
│   ├── knowledgebase-initialize/   Setup workflow
│   └── usage-report-setup/         Usage report mode workflow
├── docs/raw/                Raw source frontmatter templates
├── CLAUDE.md                     LLM entry point and project skill map
├── README.md                     This file
└── .gitignore                    Excludes data/

data/                             Generated Markdown export tree (Postgres is canonical; see docs/db-canonical.md)
├── raw/
│   ├── github/                   CLAUDE.md, Issues, PRs
│   ├── conversations/            Desktop Chatbot history
│   ├── calendar/                 Calendar events
│   ├── web/                      Web clippings
│   └── manual/                   Hand-dropped files
├── handoffs/                     Handoff documents
├── wiki/
│   ├── entities/                 Named objects ({subject}/{YYYY-MM}/)
│   ├── concepts/                 Abstract ideas (flat)
│   ├── decisions/                Architecture Decision Records
│   ├── questions/                Saved Q&A
│   ├── improvements/             Open-ended improvements
│   ├── checklists/               Operational checklists
│   └── summaries/                Time/subject rollups
├── rejected/                     Rejected wiki pages (created on reject via kb-mcp/service layer)
└── log.md                        Operation record

Workflows

Project workflows live in .claude/skills/. Use wiki-authoring for source-backed wiki edits, wiki-approval for review lifecycle work, memory-report for daily/weekly/monthly synthesis, and handoff-document for handoffs.

Privacy

data/ is private and must never be pushed to the outer repository or a public remote. Postgres (reached via DATABASE_URL) is the canonical store — see docs/db-canonical.md for the architecture. Markdown under data/ is a generated export.

• Outer .gitignore excludes data/
• All raw sources and wiki pages stay private
• Handoff documents (sensitive decisions) stay private

Quick Start

Install

uv sync

Ingest sources

./scripts/ingest-github.sh owner/repo

Write wiki

Use .claude/skills/wiki-authoring/SKILL.md; read data/raw/ and write source-backed pages to data/wiki/.

Validate

kb-lint

Commit

Writes go through the kb-mcp MCP server tools (or the in-process kb.service layer used by cron CLIs) — Markdown files under data/ are generated exports. Changes to the outer repo (code, docs, skills) are committed as usual.

Files

File	Role
CLAUDE.md	LLM entry point and project skill map
scripts/ingest-github.sh	GitHub source collection
src/kb/cli/lint.py	Wiki + handoff validation
src/kb/cli/db_ttl_sweep.py	Auto-reject stale unprocessed pages
src/kb/mcp/	DB-canonical MCP server (kb-mcp)
src/kb/service/	In-process write path (lint → DB → export)
data/log.md	Operation record
data/raw/	Immutable sources
data/wiki/	LLM-generated pages
data/handoffs/	Handoff documents

Documentation

• Documentation Index — Skill routing and design document map
• Architecture — Repository layout and memory layers
• Frontmatter — Human schema reference; runtime rules live in skills
• Wiki Categories — Human category reference; runtime uses wiki-authoring
• Commands — Full CLI command reference

See CLAUDE.md for the LLM entry point.