llm-wiki

Karpathy 的 LLM Wiki

将知识构建并维护为相互链接的 Markdown 文件，形成持久、不断累积的知识库。 基于 Andrej Karpathy 的 LLM Wiki 模式。

与传统 RAG（针对每次查询都从头重新发现知识）不同，这个 wiki 只需编译一次知识，并持续更新。交叉引用已就位。 矛盾之处已标记。综合内容涵盖所有已摄取的信息。

分工： 人类负责整理来源并指导分析。Agent 负责总结、交叉引用、归档并维护一致性。

此技能的触发时机

在用户执行以下操作时使用此技能：

• 要求创建、构建或启动 wiki 或知识库
• 要求将某个来源摄取、添加或处理到他们的 wiki 中
• 提出问题，且配置路径下已有 wiki
• 要求检查、审计或进行健康检查
• 在研究场景中提到他们的 wiki、知识库或“笔记”

Wiki 位置

位置： 通过 WIKI_PATH 环境变量设置（例如，在 ${HERMES_HOME:-~/.hermes}/.env 中）。

如果未设置，默认使用 ~/wiki。

WIKI="${WIKI_PATH:-$HOME/wiki}"

wiki 只是一个由 Markdown 文件组成的目录——可用 Obsidian、VS Code 或 任何编辑器打开。无需数据库，也无需特殊工具。

架构：三层结构

wiki/
├── SCHEMA.md           # Conventions, structure rules, domain config
├── index.md            # Sectioned content catalog with one-line summaries
├── log.md              # Chronological action log (append-only, rotated yearly)
├── raw/                # Layer 1: Immutable source material
│   ├── articles/       # Web articles, clippings
│   ├── papers/         # PDFs, arxiv papers
│   ├── transcripts/    # Meeting notes, interviews
│   └── assets/         # Images, diagrams referenced by sources
├── entities/           # Layer 2: Entity pages (people, orgs, products, models)
├── concepts/           # Layer 2: Concept/topic pages
├── comparisons/        # Layer 2: Side-by-side analyses
└── queries/            # Layer 2: Filed query results worth keeping

第 1 层 — 原始来源： 不可变。Agent 可以读取，但绝不修改这些文件。 第 2 层 — Wiki： 由 Agent 管理的 Markdown 文件。由 Agent 创建、更新并 相互交叉引用。 第 3 层 — Schema： SCHEMA.md 定义结构、约定和标签分类体系。

恢复现有 Wiki（关键——每次会话都要执行）

用户已有 wiki 时，务必先了解情况，再做任何操作：

① 阅读 SCHEMA.md — 了解领域、约定和标签分类体系。 ② 阅读 index.md — 了解现有页面及其摘要。 ③ 浏览近期的 log.md — 阅读最后 20-30 条记录，了解近期活动。

WIKI="${WIKI_PATH:-$HOME/wiki}"
# Orientation reads at session start
read_file "$WIKI/SCHEMA.md"
read_file "$WIKI/index.md"
read_file "$WIKI/log.md" offset=<last 30 lines>

完成初步了解后，才能摄取内容、查询或检查。这可以避免：

• 为已有实体创建重复页面
• 遗漏指向现有内容的交叉引用
• 与 Schema 的约定相矛盾
• 重复执行日志中已有记录的工作

对于大型 wiki（100+ 个页面），创建新内容前还要对相关主题快速运行一次 search_files。

初始化新 Wiki

用户要求创建或启动 wiki 时：

1. 确定 wiki 路径（从 $WIKI_PATH 环境变量获取，或询问用户；默认 ~/wiki）
2. 创建上述目录结构
3. 询问用户 wiki 涵盖的领域——要具体
4. 编写针对该领域定制的 SCHEMA.md（参见下方模板）
5. 编写带分节标题的初始 index.md
6. 编写包含创建记录的初始 log.md
7. 确认 wiki 已就绪，并建议可优先摄取的来源

SCHEMA.md 模板

根据用户的领域调整。Schema 会约束 Agent 的行为并确保一致性：

# Wiki Schema

## Domain
[What this wiki covers — e.g., "AI/ML research", "personal health", "startup intelligence"]

## Conventions
- File names: lowercase, hyphens, no spaces (e.g., `transformer-architecture.md`)
- Every wiki page starts with YAML frontmatter (see below)
- Use `[[wikilinks]]` to link between pages (minimum 2 outbound links per page)
- When updating a page, always bump the `updated` date
- Every new page must be added to `index.md` under the correct section
- Every action must be appended to `log.md`
- **Provenance markers:** On pages that synthesize 3+ sources, append `^[raw/articles/source-file.md]`
  at the end of paragraphs whose claims come from a specific source. This lets a reader trace each
  claim back without re-reading the whole raw file. Optional on single-source pages where the
  `sources:` frontmatter is enough.

## Frontmatter
  ```yaml
  ---
  title: Page Title
  created: YYYY-MM-DD
  updated: YYYY-MM-DD
  type: entity | concept | comparison | query | summary
  tags: [from taxonomy below]
  sources: [raw/articles/source-name.md]
  # Optional quality signals:
  confidence: high | medium | low        # how well-supported the claims are
  contested: true                        # set when the page has unresolved contradictions
  contradictions: [other-page-slug]      # pages this one conflicts with
  ---

对于观点较多或变化较快的主题，confidence 和 contested 是可选字段，但建议使用。Lint 会将 contested: true 和 confidence: low 的页面列出以供审核，避免薄弱的主张悄然固化为 wiki 中公认的事实。

raw/ 前置元数据

原始来源也要添加一个简短的前置元数据块，以便重新摄取时检测内容是否发生变化：

---
source_url: https://example.com/article   # original URL, if applicable
ingested: YYYY-MM-DD
sha256: <hex digest of the raw content below the frontmatter>
---

sha256: 让未来重新摄取相同 URL 时，若内容未变化即可跳过处理；若内容已变化，则可标记出差异。仅对正文计算哈希（即结束的 --- 之后的所有内容），不要包含前置元数据本身。

标签分类

[为本领域定义 10-20 个一级标签。使用新标签前，先在此处添加。]

AI/ML 示例：

• 模型：模型、架构、基准测试、训练
• 人员/组织：人员、公司、实验室、开源
• 技术：优化、微调、推理、对齐、数据
• 元信息：对比、时间线、争议、预测

规则：页面上的每个标签都必须出现在此分类中。如需新标签， 请先在此处添加，然后再使用。这可防止标签泛滥。

页面阈值

• 创建页面，当一个实体/概念出现在 2 个或更多来源中，或是某个来源的核心内容时
• 添加到现有页面，当某个来源提到了已经涵盖的内容时
• 不要为顺带提及、次要细节或领域外的内容创建页面
• 拆分页面，当其超过约 200 行时——拆分为子主题，并添加交叉链接
• 归档页面，当其内容已被完全取代时——移至 _archive/，并从索引中移除

实体页面

每个重要实体一个页面。包含：

• 概述/它是什么
• 关键事实和日期
• 与其他实体的关系（[[wikilinks]]）
• 来源引用

概念页面

每个概念或主题一个页面。包含：

• 定义/解释
• 当前知识状态
• 开放问题或争论
• 相关概念（[[wikilinks]]）

对比页面

并排分析。包含：

• 对比对象及对比原因
• 对比维度（优先使用表格格式）
• 结论或综合分析
• 来源

更新策略

当新信息与现有内容冲突时：

1. 检查日期——通常较新的来源会取代较旧的来源
2. 如果确实存在矛盾，请注明双方立场及其日期和来源
3. 在前置元数据中标记矛盾：contradictions: [page-name]
4. 在 lint 报告中标记，供用户审查

### index.md Template

The index is sectioned by type. Each entry is one line: wikilink + summary.

```markdown
# Wiki Index

> Content catalog. Every wiki page listed under its type with a one-line summary.
> Read this first to find relevant pages for any query.
> Last updated: YYYY-MM-DD | Total pages: N

## Entities


## Concepts

## Comparisons

## Queries

**扩展规则：**当任何部分超过 50 个条目时，按首字母或子领域 将其拆分为子部分。当索引总条目数超过 200 个时，创建一个 _meta/topic-map.md，按主题对页面进行分组，以便更快导航。

log.md 模板

# Wiki Log

> Chronological record of all wiki actions. Append-only.
> Format: `## [YYYY-MM-DD] action | subject`
> Actions: ingest, update, query, lint, create, archive, delete
> When this file exceeds 500 entries, rotate: rename to log-YYYY.md, start fresh.

## [YYYY-MM-DD] create | Wiki initialized
- Domain: [domain]
- Structure created with SCHEMA.md, index.md, log.md

核心操作

1. 摄取

当用户提供来源（URL、文件、粘贴的文本）时，将其整合到 Wiki 中：

① 保存原始来源：

• URL → 使用 web_extract 获取 Markdown，并保存到 raw/articles/
• PDF → 使用 web_extract（可处理 PDF），并保存到 raw/papers/
• 粘贴的文本 → 保存到合适的 raw/ 子目录
• 使用描述性文件名：raw/articles/karpathy-llm-wiki-2026.md
• 添加原始内容的 frontmatter（source_url、ingested、正文的 sha256）。 重新摄取相同 URL 时：重新计算 sha256，并与存储的值比较 — 如果相同则跳过；如果不同，则标记内容变更并更新。每次重新摄取都执行此操作，成本很低， 还能捕捉到未明确通知的来源变更。

② 与用户讨论要点 — 哪些内容有意思，哪些对该领域很重要。（在自动化／cron 场景中跳过此步骤 — 直接继续。）

③ 检查现有内容 — 搜索 index.md，并使用 search_files 查找提及的实体／概念对应的现有页面。这正是不断扩充的 Wiki 与一堆重复内容之间的区别。

④ 编写或更新 Wiki 页面：

• 新实体／概念： 只有符合 SCHEMA.md 中页面收录标准的才创建页面（在 2 个或更多来源中提及，或是某个来源的核心内容）
• 现有页面： 添加新信息、更新事实并更新 updated 日期。如果新信息与现有内容矛盾，请遵循更新政策。
• 交叉引用： 每个新建或更新的页面都必须通过 [[wikilinks]] 链接到至少 2 个其他页面。检查现有页面是否也有反向链接。
• 标签： 只能使用 SCHEMA.md 分类体系中的标签
• 来源追溯： 对于综合 3 个或更多来源的页面，在相关段落后添加 ^[raw/articles/source.md] 标记，注明其中可追溯到特定来源的论述。
• 置信度： 对于以观点为主、变化迅速或仅基于单一来源的论述，在 frontmatter 中设置 confidence: medium 或 low。除非论述得到多个来源的充分支持，否则不要标记为 high。

⑤ 更新导航：

• 将新页面按字母顺序添加到 index.md 的正确章节下
• 更新 index 页眉中的“页面总数”和“最后更新”日期
• 在 log.md 中追加：## [YYYY-MM-DD] ingest | Source Title
• 在日志条目中列出所有新建或更新的文件

⑥ 报告变更内容 — 列出所有新建或更新的文件。

单个来源可能会触发对 5-15 个 Wiki 页面的更新。这很正常，也是我们希望看到的 — 这正是知识累积的效果。

2. 查询

当用户询问 Wiki 所涉领域的问题时：

① 阅读 index.md，找出相关页面。 ② 对于包含 100 个或更多页面的 Wiki，还要使用 search_files 在所有 .md 文件中搜索关键词 — 仅靠索引可能会遗漏相关内容。 ③ 使用 read_file 阅读相关页面。 ④ 根据汇总的知识综合回答。注明参考的 Wiki 页面：“根据 [[page-a]] 和 [[page-b]]……” ⑤ 将有价值的答案归档 — 如果答案是深入比较、深度分析或新颖的综合结论，就在 queries/ 或 comparisons/ 中创建页面。不要归档简单查询结果 — 只归档那些难以重新推导的答案。 ⑥ 在 log.md 中更新查询记录，并注明是否已归档。

3. 检查

当用户要求检查、健康检查或审计 wiki 时：

① 孤立页面： 查找没有其他页面的 [[wikilinks]] 指向它们的页面。

# Use execute_code for this — programmatic scan across all wiki pages
import os, re
from collections import defaultdict
wiki = "<WIKI_PATH>"
# Scan all .md files in entities/, concepts/, comparisons/, queries/
# Extract all [[wikilinks]] — build inbound link map
# Pages with zero inbound links are orphans

② 损坏的 wikilinks： 查找指向不存在页面的 [[links]]。

③ 索引完整性： 每个 wiki 页面都应出现在 index.md 中。对照文件系统检查索引条目。

④ Frontmatter 验证： 每个 wiki 页面都必须包含所有必需字段（title、created、updated、type、tags、sources）。标签必须符合分类体系。

⑤ 内容过时： 页面 updated 日期比提及相同实体的最新来源早 90 天以上。

⑥ 矛盾： 查找同一主题下存在相互冲突说法的页面。检查标签或实体相同但陈述事实不同的页面。列出所有 frontmatter 中含有 contested: true 或 contradictions: 的页面，供用户审核。

⑦ 质量信号： 列出 confidence: low 的页面，以及仅引用单一来源但未设置 confidence 字段的页面——这些页面可考虑寻找佐证，或将置信度降为 confidence: medium。

⑧ 来源漂移： 对 raw/ 中 frontmatter 含有 sha256: 的每个文件重新计算哈希，并标记不匹配项。不匹配表示 raw 文件已被编辑（不应发生——raw/ 是不可变的），或文件来自 URL，而该 URL 的内容之后发生了变化。这不是严重错误，但值得报告。

⑨ 页面大小： 标记超过 200 行的页面——这些页面可考虑拆分。

⑩ 标签审计： 列出所有正在使用的标签，并标记不在 SCHEMA.md 分类体系中的标签。

⑪ 日志轮转： 如果 log.md 超过 500 条记录，则进行轮转。

⑫ 报告发现的问题，列出具体文件路径和建议操作，并按严重程度分组（损坏的链接 > 孤立页面 > 来源漂移 > 有争议的页面 > 过时内容 > 风格问题）。

⑬ 追加到 log.md： ## [YYYY-MM-DD] lint | N issues found

使用 Wiki

搜索

# Find pages by content
search_files "transformer" path="$WIKI" file_glob="*.md"

# Find pages by filename
search_files "*.md" target="files" path="$WIKI"

# Find pages by tag
search_files "tags:.*alignment" path="$WIKI" file_glob="*.md"

# Recent activity
read_file "$WIKI/log.md" offset=<last 20 lines>

批量导入

一次导入多个来源时，分批更新：

1. 先读取所有来源
2. 识别所有来源中的实体和概念
3. 检查所有相关现有页面（一次搜索，而非 N 次）
4. 一次性创建/更新页面（避免重复更新）
5. 最后更新一次 index.md
6. 添加一条涵盖整个批次的日志记录

归档

当内容已被完全取代或领域范围发生变化时：

1. 如果 _archive/ 目录不存在，则创建该目录
2. 将页面连同其原始路径移至 _archive/（例如，_archive/entities/old-page.md）
3. 从 index.md 中移除
4. 更新所有链接到该页面的页面——将 wikilink 替换为纯文本并加上“（已归档）”
5. 记录归档操作

Obsidian 集成

Wiki 目录开箱即用，可作为 Obsidian 库：

• [[wikilinks]] 会呈现为可点击的链接
• 图谱视图可视化知识网络
• YAML frontmatter 支持 Dataview 查询
• raw/assets/ 文件夹存放通过 ![[image.png]] 引用的图片

为获得最佳效果：

• 将 Obsidian 的附件文件夹设为 raw/assets/
• 在 Obsidian 设置中启用“Wikilinks”（通常默认开启）
• 安装 Dataview 插件，以运行 TABLE tags FROM "entities" WHERE contains(tags, "company") 等查询

如果同时使用 Obsidian 技能，请将 OBSIDIAN_VAULT_PATH 设置为与 wiki 路径相同的目录。

Obsidian Headless（服务端和无头机器）

在没有显示器的机器上，请使用 obsidian-headless，而不是桌面应用。 它通过 Obsidian Sync 同步库，无需图形界面——非常适合在服务端运行、向 wiki 写入内容的 Agent，同时在另一台设备上通过 Obsidian 桌面端读取内容。

设置：

# Requires Node.js 22+
npm install -g obsidian-headless

# Login (requires Obsidian account with Sync subscription)
ob login --email <email> --password '<password>'

# Create a remote vault for the wiki
ob sync-create-remote --name "LLM Wiki"

# Connect the wiki directory to the vault
cd ~/wiki
ob sync-setup --vault "<vault-id>"

# Initial sync
ob sync

# Continuous sync (foreground — use systemd for background)
ob sync --continuous

通过 systemd 持续后台同步：

# ~/.config/systemd/user/obsidian-wiki-sync.service
[Unit]
Description=Obsidian LLM Wiki Sync
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/path/to/ob sync --continuous
WorkingDirectory=%h/wiki
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now obsidian-wiki-sync
# Enable linger so sync survives logout:
sudo loginctl enable-linger $USER

这样，Agent 可以在服务端向 ~/wiki 写入内容，而你可以在笔记本电脑/手机上的 Obsidian 中浏览同一个库——更改会在几秒内显示。

常见陷阱

• 切勿修改 raw/ 中的文件 — 来源不可变。更正应写入 Wiki 页面。
• 务必先了解整体情况 — 新会话中进行任何操作前，先阅读 SCHEMA、索引和最近的日志。 跳过这一步会导致重复内容和遗漏交叉引用。
• 务必更新 index.md 和 log.md — 跳过这一步会使 Wiki 逐渐失效。二者是 导航的骨干。
• 不要为顺带提及创建页面 — 遵循 SCHEMA.md 中的页面创建阈值。某个名称 仅在脚注中出现一次，不足以为其创建实体页面。
• 不要创建没有交叉引用的页面 — 孤立页面无法被发现。每个页面必须 链接到至少 2 个其他页面。
• 必须包含前置元数据 — 它支持搜索、筛选和过期检测。
• 标签必须来自分类体系 — 自由格式的标签最终会变成噪声。先将新标签添加到 SCHEMA.md， 然后再使用。
• 保持页面便于速览 — Wiki 页面应能在 30 秒内读完。将超过 200 行的页面拆分。将详细分析移至专门的深度分析页面。
• 批量更新前先询问 — 如果一次导入会触及 10 个以上现有页面，请先向用户确认 范围。
• 轮换日志 — 当 log.md 超过 500 条记录时，将其重命名为 log-YYYY.md 并重新开始。 Agent 应在执行 lint 时检查日志大小。
• 明确处理矛盾 — 不要静默覆盖。记录两种说法及其日期， 在前置元数据中标记，并提示用户审查。

相关工具

llm-wiki-compiler 是一个 Node.js 命令行工具，用于 将来源编译为概念 Wiki，其设计同样受到 Karpathy 启发。它兼容 Obsidian， 因此，希望使用定时/命令行驱动编译流水线的用户，可以让其指向此 技能维护的同一仓库。权衡如下：页面生成由它负责（取代 Agent 对页面创建的判断），并且 专为小型语料库调优。希望由 Agent 参与整个整理流程时， 使用此技能；希望批量编译源目录时，使用 llmwiki。