Obsidian Llm Wiki

---
name: obsidian-llm-wiki
description: "База знаний агента и команды в Obsidian по паттерну Karpathy LLM Wiki: читать базу перед задачей, записывать находки после (ingest с двусторонними ссылками), отвечать из базы с цитатами, искать битые ссылки и дубли, сверять страницы с источниками. Работает через Obsidian MCP, Local REST API или с файлами напрямую. Используй всегда, когда говорят «запомни», «сохрани в базу», «что мы знаем про…», «проверь базу», /wiki. English: knowledge base, second brain, Obsidian, LLM wiki, PKM."
license: MIT
compatibility: "Obsidian vault (markdown). Желательно: Obsidian с плагином Local REST API и MCP-сервер mcp-obsidian. Без них — прямой доступ к файлам vault; для scripts/wiki_lint.py нужен Python 3.8+."
metadata:
  author: KonstantinVCH
  version: "1.0.0"
  language: ru
---

# База знаний: Obsidian + Karpathy LLM Wiki

Скилл превращает агента из забывчивого помощника в ассистента с **долгой памятью**.
Без базы агент каждую сессию начинает с нуля: не помнит архитектуру, прошлые решения
и где что лежит.

Три идеи:

1. **Перед задачей — читай память** (wiki-first). Не трать токены на то, что уже известно.
2. **После задачи — записывай находки** (ingest). Знание живёт в vault, а не умирает с сессией.
3. **Cascade.** Новое знание обновляет все смежные страницы, не только новую.

Паттерн — [LLM Wiki Андрея Карпати](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f):
сырые источники → вики из связанных страниц → schema-документ с правилами для LLM.
Операции ingest / query / lint и журнал `log.md` — из оригинала. Тип страницы `lesson`,
шаг cascade, флаг `reviewed: true`, маркеры `HYPOTHESIS` / `DOC_GAP` и режим audit —
расширения этого скилла. На вопрос «так ли у Карпати» называйте их расширениями.

## Настройка под проект

Путь к vault, раскладка папок, точка входа, тяжёлые файлы, git-репозиторий базы
и соглашения команды — в `references/project-config.md`. По умолчанию скилл ожидает
раскладку из раздела «Структура vault» ниже.

## Режимы — выбираются по смыслу просьбы

Режим определяется явной командой либо смыслом просьбы. В обоих случаях назови вслух,
в каком режиме работаешь: так видно, будет ли запись в базу.

| Команда | Или человек говорит | Режим | Пишет в vault | Подробно |
|---|---|---|---|---|
| `/wiki` | задача началась, контекст может лежать в базе | wiki-first (по умолчанию) | нет | ниже |
| `/wiki-query <вопрос>` | «что знаем про…», «есть инфа по…», вопрос о сервисе, ошибке, термине | query | нет | `references/query.md` |
| `/wiki-ingest` | «запиши», «сохрани», «зафиксируй находки», конец задачи с новыми фактами | ingest | да | `references/ingest.md` |
| `/wiki-lint` | «проверь базу», «битые ссылки», «сироты», «дубли» | lint | правит только явные поломки | `references/lint.md` |
| `/wiki-audit <страница>` | «проверь страницу X», «соответствует ли источникам» | audit | нет, только отчёт | `references/audit.md` |

Неясно, спрашивают или просят записать, — считай, что спрашивают. Если базой пользуется
команда, запись видна всем, поэтому лишнее там дороже одного уточняющего вопроса.

Готовые слэш-команды для Claude Code — `assets/commands/` (скопировать в `.claude/commands/`).

## Доступ к vault

Три способа, по убыванию удобства. Подробности, вызовы и известные ловушки —
`references/access.md`.

1. **Obsidian MCP** (`mcp-obsidian` поверх плагина Local REST API): инструменты
   `obsidian_list_files_in_vault`, `obsidian_simple_search`, `obsidian_get_file_contents`,
   `obsidian_append_content`, `obsidian_patch_content` и др.
2. **Local REST API напрямую** — `curl` на `https://127.0.0.1:27124` с ключом из настроек плагина.
3. **Файлы vault напрямую** — чтение, `grep`, правка markdown обычными средствами.
   Obsidian подхватывает изменения сам.

**Preflight — всегда первым:** проверь, какой способ доступен (`obsidian_list_files_in_vault`,
`GET /vault/` или наличие каталога vault). Ничего не отвечает — сообщи пользователю:
«Vault недоступен. Проверь: 1) Obsidian открыт, 2) плагин Local REST API включён,
3) порт, 4) путь к vault. Работать без памяти?». Молча продолжать без базы нельзя:
пользователь думает, что агент опирается на память.

Способ выбери один на сессию и назови его. Если команда договорилась писать в базу
только через Obsidian (например, ради плагинов, которые ведут индекс), прямую запись
в файлы не используй — это настраивается в `references/project-config.md`.

## Главные принципы

0. **Никаких записей наружу без явного запроса.** Vault — рабочая память, в неё пиши
   свободно. Jira, GitHub, мессенджеры — только черновик и вопрос «публиковать?».
1. **Факты важнее гипотез.** Утверждение = проверяемый источник.
2. **Нет данных → `HYPOTHESIS`.** Не додумывать.
3. **Расхождение документа и реальности = `DOC_GAP`.** Фиксировать явно.
4. **Знание записывается сразу**, при получении, а не «потом»: к концу сессии детали теряются.
5. **Источник истины — реальность** (код, данные, логи). Документ — гипотеза.
6. **Выводы ИИ перепроверять** перед записью в базу. Ошибка в базе размножается
   по всем будущим сессиям.
7. **Findability обязательна** — записал так, чтобы потом нашлось.
8. **Общий vault: чужое правишь только по явной просьбе.** Каждая твоя правка становится
   строками чужого PR и `git pull`, который кто-то будет разбирать. Объём правок — часть
   результата, а не побочный эффект.
9. **`reviewed: true` во frontmatter** — страницу проверил человек. Такую страницу
   только дополняй, не переписывай.

## Режим wiki-first (по умолчанию)

1. Preflight (см. выше).
2. Прочитай точку входа — `wiki/overview.md`: архитектура домена и известные странности.
3. Найди по конкретным терминам задачи: имя сервиса, ключ задачи, код ошибки.
   Ищи узко и по 2–3 формам: рус + англ + аббревиатура.
4. Прочитай найденные entity и concept. По wikilinks переходи на один уровень, не глубже.
5. Работай дальше, опираясь на найденное, и цитируй `[[ссылки]]`, а не общие знания модели.
6. По ходу задачи держи список новых фактов, ловушек и расхождений — это сырьё для ingest.

Большие файлы (индекс, сводные справочники) целиком не читай — только поиском.

## Режимы кратко

**Query** — ответ только из vault, файлы не создаются. Перед выводом «в базе нет»
поищи по синонимам. Пользователь просит «сохрани ответ» — тогда это уже ingest
(`sources/{slug}--query-answer.md`). Подробно — `references/query.md`.

**Ingest** — порядок: проверка дублей → source → entity → concept → lesson (если были
ловушки) → cross-links в обе стороны → cascade по смежным страницам → `wiki/log.md` →
строка в `wiki/index.md`. Шаблоны страниц — `assets/templates/`. Полный порядок
и чеклист — `references/ingest.md`.

**Lint** — запускать каждые 5–10 ingest. Автофикс только очевидного, остальное — отчёт.
Для прямого доступа к файлам есть `scripts/wiki_lint.py` (только отчёт, файлы не правит).
Подробно — `references/lint.md`.

**Audit** — выписать утверждения страницы и сверить каждое с её `sources:`.
Страницу не править без явного «да». Подробно — `references/audit.md`.

## Массовые операции над графом — отдельный жанр

Ingest трогает **страницы своей задачи и их cross-links** — обычно 3–7 файлов. Всё, что
шире, уже не ingest, а обслуживание базы, и оно требует отдельной просьбы.

**Порог остановки: 10 файлов.** Собираешься изменить больше страниц, которых задача не
касается, — остановись и спроси. Даже если правка объективно улучшает граф.

| Операция | Когда делать |
|---|---|
| ingest находок задачи | всегда, это основная работа |
| cascade по смежным страницам | да, но именно по смежным: 2–5 штук, каждая по делу |
| починка битых ссылок по всей базе | только по явной просьбе, отдельной задачей |
| нормализация frontmatter, дедупликация, переписывание индекса | то же самое |
| «заодно причешу, раз уж открыл» | **никогда** |

**Пакетной правкой не трогать никогда:**

| Область | Почему |
|---|---|
| блок `> **Источник: [[...]]**` | цель цитаты — часть факта; подменённая ссылка приписывает цитату чужой странице |
| содержимое внутри `` `код` `` и блоков ```` ``` ```` | там примеры синтаксиса: `[[wiki-link]]` внутри кода — не ссылка |
| frontmatter (`sources`, `aliases`, `tags`) | значения сверяются с источниками вручную |

**Заглушка — не починка.** Страница из одной строки «Stub created by Fix Dead Links»
закрывает битую ссылку, но знания не добавляет: счётчик улучшается, граф — нет. Битая
ссылка честнее.

**Перед добавлением страницы** поищи её под другим написанием имени (`order-service`
против `orderservice`, `OrderService`). Двойник расходится с оригиналом и плодит пары
ссылок с разными целями.

**Если массовая правка всё-таки согласована — три требования:**

1. **Дифф аддитивный.** База команды — основа, твоё дописывается сверху. Перестановка
   и переформатирование дают тысячи удалений, по которым невозможно понять, что
   изменилось по сути. Журнал дополняется в конец, без пересортировки.
2. **Код не трогать** — ни `` `инлайн` ``, ни блоки ```` ``` ````. Автозамена по всему
   файлу ломает примеры синтаксиса, и это находят в первую очередь.
3. **Назвать цену до выдачи:** сколько файлов, сколько добавлений и удалений.
   «Починил ссылки» без чисел — не отчёт.

**Случай, из которого правило.** Нужно было слить две разошедшиеся копии общей базы.
Слияние сделали верно и без потерь, но «заодно» починили 883 ссылки, переписали 1617
описаний индекса и причесали frontmatter. PR вырос до 605 файлов и 11 тысяч удалений,
внутри оказался испорченный пример синтаксиса. Реакция владельца: «я не один ей
пользуюсь, теперь всем нужно будет обновить 1700 файлов». После переделки — 498 файлов
и 1042 удаления вместо 11 291, а суть осталась ровно та же.

## Findability — чтобы знание потом нашлось

Для **каждой созданной страницы**:

- **Отдельная страница:** тема с тремя и более фактами — своя страница, а не кусок
  внутри чужой.
- **`aliases`** покрывают рус + англ + аббревиатуру + варианты с дефисом + синонимы:
  `aliases: ["Сервис заказов", "order-service", "OrderService", "OMS", "заказы"]`.
- **Заголовок** = термин + расшифровка: `# Ключ идемпотентности (Idempotency-Key)`.
- **Двусторонние ссылки** расставлены.
- **Проверка:** поиск по запросу, которым пользователь будет искать, находит страницу.
  Не находит — добавь aliases.

## Структура vault (по умолчанию)

```
wiki/
  overview.md      ← ТОЧКА ВХОДА (читать первым в каждой сессии)
  index.md         ← каталог всех страниц: ссылка + однострочное описание
  log.md           ← журнал операций: ingest / lint / query
  entities/        ← конкретные вещи: сервисы, объекты, люди, задачи
  concepts/        ← абстракции: термины, паттерны, механизмы, конфиги
  schema/config.md ← правила структуры для LLM (шаблоны страниц), если есть
sources/           ← source-файлы по задачам и сессиям ({topic}--summary.md)
lessons/           ← уроки: ловушки, обходные пути, ошибки инструментов
{topic}/           ← рабочие файлы текущей сессии (черновики), обычно вне git
```

У команды своя раскладка — опиши её в `references/project-config.md` и следуй ей.

## Экономия токенов

1. Первым читать `wiki/overview.md`, а не весь vault.
2. Большие файлы (больше ~30 тыс. символов) — только поиском, не целиком.
3. Один файл не читать дважды — использовать контекст сессии.
4. Большие источники (логи, дампы) — отдать субагенту, в базу класть вывод.
5. Нашлось в vault — не дублировать внешним запросом.

## Терминология

| Термин | Определение |
|---|---|
| **Source** | Первоисточник: документ, код, данные, лог; в vault — страница `type: source` |
| **Fact** | Утверждение с проверяемым Source |
| **Hypothesis** | Предположение без Source. Требует проверки |
| **DOC_GAP** | Расхождение документации и реальности |
| **Evidence** | Доказательство: ссылка, результат, цитата |
| **Entity** | Конкретная вещь → `wiki/entities/` |
| **Concept** | Абстракция → `wiki/concepts/` |
| **Lesson** | Ловушка или обходной путь → `lessons/` |
| **Cascade** | Обновление смежных страниц после ingest |

## Связанные скиллы

- `qa-task-testing` — QA-протокол проверки задачи. Для задач тестирования приоритет
  у него: wiki-first уже встроен в его шаги. Этот скилл напрямую — для общих задач
  с базой знаний.