llm-notes

English | 简体中文

llm-notes is a lightweight knowledge base workflow for Claude Code. It turns a directory of notes, papers, code, screenshots, and other mixed source material into an LLM-maintained Markdown wiki. Q&A outputs, indexes, and health reports remain local files, making the system easy to inspect, version, and browse in Obsidian.

This project is inspired by Andrej Karpathy's idea. See: LLM Knowledge Bases

Overview

llm-notes treats the knowledge base root itself as the source root. Original files stay directly in the KB root, wiki/ stores LLM-compiled articles, indexes, and glossary pages, and outputs/ stores generated artifacts such as answers, slides, and images.

Unlike workflows that require a raw/ + wiki/ layout, the current implementation of llm-notes does not require a separate raw/ directory. If a directory already contains files, /kb-init treats those files as the canonical source material and initializes the derived wiki structure around them.

Core Capabilities

Command	Purpose
/kb-init	Initialize a knowledge base directory, create wiki/, outputs/, CLAUDE.md, and starter indexes, and auto-compile existing material when present
/kb-ingest	Import external material into the KB through one add entrypoint: fetch web pages into imports/web/, copy local files into imports/files/, or save pasted text into imports/text/
/kb-compile	Read source material from the KB root, compute a deterministic source/article plan, create or update structured wiki articles, and maintain _index.md, _glossary.md, and _recent.md
/kb-chat	Run a multi-turn KB conversation, keep the transcript in outputs/sessions/, continue follow-up questions inside one session, and stage stable conclusions for filing into answers/wiki
/kb-qa	Answer questions against the wiki, use dual-layer retrieval across both the compiled wiki and raw source files when needed, extend the local knowledge network through related concepts, save answers to outputs/answers/, and optionally file insights back into the wiki
/kb-lint	Run health checks, identify orphan articles, broken wikilinks, stale content, and uncovered sources, save a report to outputs/lint-report.md, and auto-fix safe issues
/kb-slides	Generate Marp-format slide decks from wiki content, save to outputs/slides/, viewable in Obsidian with the Marp plugin
/kb-viz	Generate matplotlib charts and diagrams from wiki data, save to outputs/images/, embeddable in wiki articles
/kb-search	Full-text search across the wiki using a TF-IDF inverted index, usable directly or as a retrieval accelerator for /kb-qa and larger LLM queries

Design Principles

• Markdown-first: important knowledge lives in local files you can inspect and version.
• Source-first: original files are authoritative; wiki articles are derived and regenerable.
• LLM-maintained: summaries, indexes, backlinks, glossary entries, and filed-back insights are maintained by the LLM.
• Obsidian-friendly: the output structure and link style are designed to work well as a local Obsidian vault.
• Minimal infrastructure: no database, service layer, or mandatory vector store is required to get started.

Use Cases

• Research vaults for papers, archived web articles, screenshots, reading notes, and mixed source material
• Codebase understanding, architecture notes, and navigable documentation for existing repositories
• Long-running topic investigations where each query should accumulate back into the knowledge base
• Local-first knowledge management where important outputs remain inspectable as Markdown files

Requirements

• Claude Code
• A directory that already contains source material, or an empty directory you want to turn into a knowledge base
• Obsidian if you want the best browsing experience

Installation

git clone https://github.com/Joshmomel/llm-notes.git
cd llm-notes
./install.sh

install.sh symlinks the skills in this repository into ~/.claude/skills/ and installs the local llm_notes Python helper package in editable mode. That package now backs stable search, manifest, source/article compile-planning, and wiki/index helpers, so core KB behavior can move out of ad hoc skill text and into versioned local code.

Quick Start

After installation, open any directory you want to use as a knowledge base in Claude Code and run:

# inside Claude Code
/kb-init .
/kb-ingest "https://example.com/article"
/kb-chat "Let's explore the main themes here and keep the follow-ups in one session"
/kb-qa "What are the main themes in this knowledge base?"
/kb-lint

If the directory already contains files, /kb-init will initialize the KB structure and auto-compile the existing material.

If the directory is empty, /kb-init will create the KB structure first. After you add source files into that directory, run:

# inside Claude Code
/kb-compile
/kb-qa "What key concepts have been established so far?"

Typical Workflows

Existing Notes Or Repository

Use this when you already have documents, code, or research material in a directory:

# inside Claude Code
/kb-init .
/kb-chat "Summarize the main themes and structure here, then stay open for follow-ups"
/kb-lint

Start From An Empty Directory

Use this when you want to build a new knowledge base from scratch:

# inside Claude Code
/kb-init .
# add notes, code, PDFs, images, or other source files into this directory
# or import them directly:
/kb-ingest "https://example.com/article"
# or paste text directly:
pbpaste | /kb-ingest --title "Copied note"
/kb-compile
/kb-qa "What topics have emerged in the knowledge base so far?"

Stay In A KB Chat Session

Use this when you expect multiple follow-up questions on the same topic:

/kb-chat "Compare dense attention and retrieval here"
# -> transcript accumulates in outputs/sessions/YYYY-MM-DD-*.md
# -> stable conclusions can still be distilled into outputs/answers/
# -> the assistant can then ask whether it should file them back into wiki/

Generate Slides From Wiki Content

/kb-slides "Introduction to Transformer Architecture"
# -> outputs/slides/2026-04-11-intro-transformers.md (Marp format)
# View in Obsidian with Marp plugin, or export: marp --pdf outputs/slides/*.md

Visualize Data From Wiki

/kb-viz "Compare parameter counts across model architectures"
# -> outputs/images/2026-04-11-model-params.png
# Embed in wiki: ![[outputs/images/2026-04-11-model-params.png]]

Search The Wiki

/kb-search "attention mechanism"
# -> Ranked results with TF-IDF scoring and snippet previews
# -> The same index can be reused by /kb-qa to narrow the reading set before synthesis

Full Research Loop

A complete workflow combining all skills:

/kb-init .                           # Initialize and auto-compile
/kb-ingest "https://example.com/article"  # Bring a web article into imports/web/
/kb-chat "Work through the open research questions"  # Keep a transcript-backed session
/kb-qa "What are the key findings?"  # Ask questions, file answers back
/kb-slides "Summary of findings"     # Generate a presentation
/kb-viz "Timeline of key events"     # Create a visualization
/kb-lint                             # Check health, get exploration suggestions
/kb-compile                          # Re-compile after adding new material

Generated Knowledge Base Layout

your-kb/
├── CLAUDE.md             # LLM operating instructions for this KB
├── <source files...>     # Canonical source material stays in the KB root
├── imports/
│   ├── files/
│   ├── text/
│   └── web/
├── wiki/
│   ├── _index.md
│   ├── _glossary.md
│   ├── _recent.md
│   └── <category>/
│       ├── _index.md
│       └── <article>.md
└── outputs/
    ├── _manifest.json
    ├── answers/
    ├── images/
    ├── sessions/
    └── slides/

Important detail: in the current implementation, source files live directly in the KB root. llm-notes does not require a separate raw/ directory.

outputs/_manifest.json now tracks both sides of compilation state:

• sources records source digests, mtimes, destination wiki articles, and stable article_targets hints for future planning
• articles records article title/category/slug plus the source refs and source digests used for the last compile

That lets /kb-compile reason about not just which source files changed, but which existing articles are impacted and which new article targets are the default next step.

outputs/KB_REPORT.md is the dashboard-style homepage for the KB. It rolls up the current snapshot, pending filing recommendations, semantic hotspots, active sessions, and next actions into one file so both humans and agents can orient quickly before reading deeper artifacts.

/kb-ingest is the optional front door for external material. It does not replace the current source-root model; it just gives you a standardized way to bring URLs, local files, or pasted text into the KB under imports/ before compiling them. In interactive agent workflows, importing and compiling do not have to be the same step: after /kb-ingest, it is usually better for the assistant to ask whether it should run /kb-compile now.

Repository Layout

llm-notes/
├── llm_notes/
│   ├── chat.py
│   ├── compile.py
│   ├── manifest.py
│   ├── search.py
│   └── wiki.py
├── skills/
│   ├── kb-ingest/
│   ├── kb-chat/
│   ├── kb-init/
│   ├── kb-compile/
│   ├── kb-qa/
│   ├── kb-lint/
│   ├── kb-slides/
│   ├── kb-viz/
│   └── kb-search/
├── tests/
│   ├── test_compile.py
│   ├── test_manifest.py
│   ├── test_search.py
│   └── test_wiki.py
├── pyproject.toml
├── install.sh
├── README.md
└── README.zh-CN.md

Scope And Limitations

• This is a prompt-and-files workflow, not a hard-coded indexing engine.
• Knowledge quality depends on the quality of the source material and on the LLM consistently following the KB conventions.
• The wiki/ layer becomes more valuable over time as more material is compiled, more answers are filed back, and more lint issues are resolved.
• The current approach is especially well suited to small and medium-sized knowledge bases that can be navigated effectively through summaries and indexes.

References

• LLM Knowledge Bases
• graphify README
• WikiLLM README