wiki-substrate

Schema, workflow tooling, and MCP wiring for a personal knowledge vault built on plain markdown.

What this is

This repo contains the typed-schema definition, ingest and migration scripts, and MCP server configuration for a personal second brain: a directory of markdown pages organized into entities, concepts, syntheses, sources, and a memory subtree. Pages carry structured YAML frontmatter (type, status, tags, updated) and follow a consistent H2 section layout (TL;DR, Details, Sources, See also). Agents (Claude Code) read and write these pages according to the schema in CLAUDE.md: ingest drops source files into raw/, writes a sources/ summary page, then creates or updates entity and concept pages with wikilink cross-references. A lint pass checks for contradictions, stale claims, orphan pages, and missing backlinks.

The search backend is qmd, the BM25 + vector hybrid indexer with an LLM reranking layer by Tobi Lutke (@tobilu/qmd, github.com/tobi/qmd). qmd is what makes semantic search across hundreds of pages fast and accurate. This repo does not include qmd; it includes the .mcp.json.example wiring that exposes qmd as an MCP server so Claude Code can call qmd search, vsearch, and query as first-class tools during any session. The schema, directory layout, ingest and migration scripts, and the MCP integration pattern are my own work, built on top of qmd.

What is NOT included

The vault content (entities, concepts, syntheses, sources, memory, raw, and the index/log) is private and is not published here. This repo contains only the schema and tooling, not the knowledge.

Contents

• CLAUDE.md: the full schema (page format, workflows, directory conventions, qmd usage, Obsidian MCP integration, memory subtree layout)
• memory/CLAUDE.md: operational rules for the memory subtree
• scripts/: Python and bash tools for transcript conversion, session digest generation, memory migration, and format upgrades
• .mcp.json.example: MCP server config template for qmd and the Obsidian Local REST API

Setup

1. Install qmd: github.com/tobi/qmd
2. Copy .mcp.json.example to .mcp.json and set OBSIDIAN_API_KEY and OBSIDIAN_HOST in your environment or a local .env
3. Run qmd update in your vault root to build the index
4. Open Claude Code from your vault root; qmd and Obsidian tools become available over MCP

Scripts

• scripts/transcript_to_md.py: convert a Claude Code JSONL session to a wiki markdown page
• scripts/backfill_transcripts.py: batch-convert historical JSONL sessions
• scripts/generate_digest.py: append a daily digest entry from a closed session
• scripts/migrate_memory.sh: one-time consolidation of memory dirs into the vault
• scripts/upgrade_memory_format.py: idempotent upgrade of auto-memory cards to full wiki format