wikix

🇺🇸 English · 🇨🇳 简体中文 · 🇯🇵 日本語 · 🇰🇷 한국어

An LLM-maintained personal wiki — a persistent, compounding second brain you curate while the agent does the bookkeeping.

Based on Karpathy's LLM Wiki pattern (original gist · local copy). You drop sources into raw/, ask questions against the growing wiki, and let the agent turn durable results into structured pages with summaries, concepts, entities, syntheses, saved questions, cross-references, and contradiction notes.

The current architecture uses a dual-input pipeline: raw sources and valuable query sessions both flow through analysis, user alignment, wiki building, and review. This keeps the system simple while making the wiki improve through use, not only through new source ingestion.

Demo

Watch the real workflow walkthrough: How I use my agent to compound knowledge (Bilibili, Chinese).

Quick Start

1. Clone this repo and open it in Claude Code, Codex, OpenCode, Hermes, or OpenClaw.

   Copyable CLI example:

   git clone https://github.com/CaoYuhaoCarl/wikix.git
   cd wikix
   cp USER.md.example USER.md ## Optional: create local preferences (language, response style, terminology); USER.md is gitignored
   
   claude ## Change to codex, opencode, hermes, or openclaw if needed

   The USER.md step is optional. It lets the agent honor your personal preferences — output language, response style, and terminology — without leaking them into shared commits.

2. Drop a source file into raw/ (a markdown article, paper, PDF, transcript, PNG/JPG image, etc.). The directory is committed with a placeholder, but your source files stay local by default.

3. Paste this prompt:

   You're now my LLM wiki agent. Follow the operating schema for this repo.
   If your runtime has not already loaded the full schema, read AGENTS.md.
   Ingest the new file in raw/ following the ingest workflow, then update
   index.md and log.md.
   

4. For useful conversations, run /distill or accept the agent's proposal to save the result. The agent will first create a session packet under wiki/_analysis/sessions/, then ask for alignment before writing formal wiki pages.

5. Browse the generated pages in wiki/. After each ingest or distill, open the repo in Obsidian to inspect the knowledge graph; the smoother path is to install the community Claudian plugin and launch Claude Code, Codex, or OpenCode directly from Obsidian. That lets you ingest, query, and lint while watching the graph update live.

   

Starting from scratch in a different project? Copy AGENTS.md, the runtime shims and agent definitions you need (CLAUDE.md, GEMINI.md, .claude/agents/, .codex/agents/), meta/templates/, USER.md.example, and meta/karpathy-llm-wiki.md into an empty directory, then ask your agent: "Implement this idea file as my second brain. Set up the schema, index.md, log.md, and folder conventions."

Structure

raw/                         # immutable source inputs; only raw/.gitkeep is committed by default
  assets/                    # downloaded assets that belong to raw sources
wiki/                        # LLM-generated knowledge layer; ignored by Git by default
  _analysis/                 # pipeline artifacts, not formal durable wiki knowledge
    sessions/                # /distill query-session packets
    reviews/                 # optional reviewer reports
  sources/                   # one note per ingested raw source
  concepts/                  # reusable topic pages
  entities/                  # people, orgs, projects, tools
  syntheses/                 # cross-source analysis and conclusions
  questions/                 # saved answers to important questions
  attachments/               # wiki-owned or generated assets
docs/                        # user and maintainer documentation
  adr/                       # architecture decision records
  plans/                     # implementation plans and maintenance notes
meta/
  templates/                 # formal wiki page templates
  karpathy-llm-wiki.md       # local copy of the source pattern
assets/                      # README images and public media
.claude/
  agents/                    # Claude analyst/builder/reviewer subagents
  skills/wiki-query/         # project-local query citation helper
.codex/agents/               # Codex analyst/builder/reviewer agent definitions
.obsidian/                   # portable vault settings; workspace/plugin state is ignored
index.md                     # local content catalog; read first on every query
log.md                       # local append-only activity log
AGENTS.md                    # canonical operating schema
CLAUDE.md / GEMINI.md        # runtime compatibility shims -> AGENTS.md
USER.md.example              # optional local preference template; copy to USER.md
README*.md                   # multilingual project documentation

Workflows

The agent follows one shared analyst-builder-reviewer pipeline defined in AGENTS.md:

raw source       ┐
                 ├─> wiki-analyst -> user alignment -> wiki-builder -> wiki-reviewer
query session    ┘

• Ingest — read a new raw/ source, analyze entities, concepts, claims, contradictions, and related pages, then write only after you confirm scope.
• Query — answer a question by reading index.md first, then drilling into relevant wiki pages and raw sources only when needed.
• Distill — turn a valuable conversation into a query-session packet under wiki/_analysis/sessions/, then save durable results to wiki/questions/, wiki/syntheses/, wiki/concepts/, or wiki/entities/.
• Lint — health-check the wiki for orphans, broken links, contradictions, stale claims, and missing pages.
• Mastery — use /mastery only when a distilled question or synthesis deserves heavier SeedX-style learning artifacts. mastery_candidate: true is only a signal, not an automatic generator.

For the architecture rationale and comparison with traditional approaches, see docs/dual-input-wiki-pipeline.md and ADR 0001. Implementation planning notes live under docs/plans/.

Conventions

• Files and folders use lowercase kebab-case.
• Every wiki page has YAML frontmatter (title, type, created, updated, sources, tags).
• Raw sources are immutable. The agent never edits files in raw/.
• wiki/_analysis/ holds pipeline artifacts, not formal durable wiki pages.
• Evidence is labeled by strength: raw/source evidence, existing wiki evidence, user-provided claim, or assistant inference.
• The agent aligns with you on emphasis and scope before writing formal wiki pages.

See AGENTS.md for the full schema, workflow rules, and evidence rules. Page templates live in meta/templates/.

Credits

Pattern by Andrej Karpathy — original gist (local copy at meta/karpathy-llm-wiki.md).

Thanks also to Obsidian for the local knowledge graph experience, and Claudian for making the agent workflow available directly inside Obsidian.

License

MIT — covers the schema, templates, and tooling in this repository (AGENTS.md, CLAUDE.md, GEMINI.md, README*.md, docs/, meta/, etc.).

Note: files you place in raw/ keep their original licenses and are ignored by Git by default; only raw/.gitkeep is committed so the folder exists after cloning. Pages the agent generates in wiki/ are derivative works of those sources and inherit their license obligations. If you publish generated wiki pages, vet the corresponding local sources and license terms accordingly.