К основному содержанию
команда CX Codex

obsidian-retrieval-eval — команда для Claude Code: установка

Команда obsidian-retrieval-eval оценивает качество поиска по хранилищу Obsidian метриками recall@k и MRR. Помогает проверить алгоритм ранжирования на реальных вопросах до внедрения векторных баз.

MIT ★ 5 412 обновлён 2026-10-24

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add eugeniughelbur/obsidian-second-brain
/plugin install obsidian-second-brain@obsidian-second-brain
Открыть на GitHub

Что делает obsidian-retrieval-eval

Команда тестирует поисковый движок хранилища Obsidian из integrations/obsidian-mcp-server/vault_ops.py. Она генерирует или берёт готовые тестовые вопросы из scripts/eval/retrieval_cases.jsonl, ищет нужные заметки и рассчитывает метрики recall@1, recall@3, recall@5, recall@10 и MRR. В отчёте видно заметки, которые не попали в топ-10 или опустились ниже третьей строки из-за шума вроде длинных файлов log.md и папки raw/.

Тестовые примеры запускаются через скрипт scripts/eval/retrieval_eval.py с помощью uv run. Без заданного ключа XAI_API_KEY генератор фраз скатывается к буквальным совпадениям предложений вместо перефразирования. Аргумент report сохраняет базовый отчёт прямо в хранилище по пути wiki/concepts/.

Какие задачи решает

  • измерить точность поиска в Obsidian метриками recall и MRR
  • выявить шумные заметки и логи, перебивающие канонические документы
  • проверить влияние правок ранжирования на реальных тестовых вопросах
  • сохранить базовый отчёт оценки качества в папку wiki

Примеры запросов агенту

  • /obsidian-retrieval-eval
  • Запусти /obsidian-retrieval-eval 30 для проверки поиска
  • Сохрани метрики поиска через /obsidian-retrieval-eval report

Как установить obsidian-retrieval-eval

1Через маркетплейс плагинов

/plugin marketplace add eugeniughelbur/obsidian-second-brain
/plugin install obsidian-second-brain@obsidian-second-brain

2Вручную: положить файлы

.claude/commands/obsidian-retrieval-eval.md

Вызов — /obsidian-retrieval-eval. Для всех проектов — ~/.claude/commands/

Вопросы об obsidian-retrieval-eval

Как установить obsidian-retrieval-eval в Claude Code?

Выполните по очереди две команды: сначала /plugin marketplace add eugeniughelbur/obsidian-second-brain, затем /plugin install obsidian-second-brain@obsidian-second-brain.

Что делает команда obsidian-retrieval-eval?

Она проверяет качество поиска по хранилищу заметок Obsidian, вычисляет метрики recall@k и MRR и показывает конкретные ошибки ранжирования.

Что требуется для генерации синтетических запросов?

Необходим инструмент uv для запуска тестового скрипта и переменная XAI_API_KEY. Без ключа скрипт генерирует фразы по буквальным выдержкам из предложений.

Исходный текст

obsidian-retrieval-eval.md · MIT
---
description: Measure how well vault search finds the right note for a natural-language question - recall@k and MRR, with the concrete failures
category: meta
triggers_en: ["evaluate retrieval", "how good is my vault search", "retrieval eval", "test vault search quality", "measure find quality"]
triggers_de: ["Abrufqualität bewerten", "wie gut ist meine Vault-Suche", "Retrieval-Evaluierung", "Qualität der Vault-Suche testen", "Suchqualität messen"]
triggers_es: ["evalúa la búsqueda", "qué tal funciona la búsqueda de mi vault", "evaluación de recuperación", "prueba la calidad de la búsqueda", "comprueba si encuentra bien mis notas"]
triggers_pt: ["avalie a recuperação", "quão boa é a busca do meu vault", "avaliação de recuperação", "teste a qualidade da busca do vault", "meça a qualidade da busca"]
triggers_zh: ["测试知识库搜索效果", "评估检索质量", "看看我的笔记好不好找", "测量语义搜索召回率", "检查搜索能不能找到正确笔记"]
---

Use the obsidian-second-brain skill. Execute `/obsidian-retrieval-eval $ARGUMENTS`:

You cannot improve retrieval you have not measured. This scores the vault's REAL search (the term-frequency, title-weighted ranking in `integrations/obsidian-mcp-server/vault_ops.py`, the same engine behind `/obsidian-find` and the MCP connector) against natural-language questions whose correct answer note is known - so "should I add a vector index / better ranking?" becomes a number and a list of failures, not a hunch.

The optional argument is a number of cases to (re)generate first (without `XAI_API_KEY` the generator silently falls back to verbatim-sentence heuristics - fine for keyword-style cases, weak for paraphrase-style) (e.g. `30`), or `report` to also write the result to the vault. No argument: evaluate the existing cases.

1. Read `_CLAUDE.md` first if it exists in the vault root.

2. If the user asked to generate (or no cases file exists yet at `scripts/eval/retrieval_cases.jsonl`), bootstrap the eval set from the vault. Run from the skill root (its absolute path was given at session start as **Skill root**; substitute it for `SKILL_ROOT`):
   ```bash
   uv run --directory "SKILL_ROOT" python scripts/eval/retrieval_eval.py --generate 30
   ```
   This samples real notes and, for each, has an LLM write a question whose answer is in that note while AVOIDING the note's title words (so it tests retrieval, not string match). The note's path is the gold answer. Cases are gitignored - they contain private note paths.

3. Run the evaluation (from the same skill root):
   ```bash
   uv run --directory "SKILL_ROOT" python scripts/eval/retrieval_eval.py --json
   ```
   It prints recall@1/3/5/10, MRR, and per-case results: misses (gold note never in the top 10) and buried cases (gold ranked below #3, usually because a noisy high-mention note or a `raw/` transcript outscored the canonical note).

4. Interpret the numbers for the user in plain language: what fraction of natural-language questions surface the right note, and the dominant failure pattern (e.g. long `raw/` sources and `log.md` outranking short canonical notes; title-weighting helping only when the query reuses title words). Name the specific notes that wrongly ranked #1 from the JSON.

5. Turn failures into concrete, testable retrieval fixes ranked by leverage - e.g. exclude `raw/` and `log.md` from search, boost notes by `type:` (canonical concept/entity/project over transcripts), add alias/heading indexing, or add semantic matching. Each fix is a hypothesis: re-run this eval on the SAME cases after the change to confirm it actually raised recall, never assume.

6. If the user passed `report` (or asks to save), write an AI-first baseline note to `wiki/concepts/` (resolve per `references/folder-map.md`), `type: synthesis`, tagged `[retrieval, eval]`, linked from a retrieval-quality project note if one exists: record the engine, the case count, the recall@k / MRR numbers with the date as a recency marker, the top failure patterns with example notes, and the ranked fix hypotheses. This is the before-number every future retrieval change is measured against.

Measure, change one thing, measure again. That loop - not a guess about vector databases - is how retrieval actually improves.

---

**AI-first rule:** Every note created or updated by this command MUST follow `references/ai-first-rules.md` - `## For future agent` preamble, rich frontmatter (`type`, `date`, `tags`, `ai-first: true`, plus type-specific fields), recency markers per external claim, mandatory `[[wikilinks]]` for every person/project/concept referenced, sources preserved verbatim with URLs inline, and confidence levels where applicable. If that path does not resolve from your working directory, search upward for it; if you still cannot read it, say so before writing rather than producing a note that silently skips the rule. The vault is for future agent retrieval - not human reading.

**Anti-fabrication:** Report the eval numbers exactly as the harness emits them - never round a miss into a hit or invent a recall figure. If the cases are few or the gold labels look weak, say so rather than overclaiming. See the anti-fabrication and search-completeness hard rules in `references/ai-first-rules.md`.

© Eugeniu Ghelbur · MIT · eugeniughelbur/obsidian-second-brain

Похожие слэш-команды

Все слэш-команды по теме «Заметки, задачи и проекты» →
Obsidian Turbocharged The-40-Thieves MCP-сервер Obsidian Turbocharged, через который агент читает и правит хранилище Obsidian: поиск, память и проверка опасных операций в одном канале. CX Codex +1 ★ 13звёзд репо Obsidian Hybrid Search flowing-abyss MCP-сервер Obsidian Hybrid Search даёт агенту доступ к хранилищу Obsidian: ищет заметки по смыслу, заголовку и связям, читает их и отдаёт цитаты из ваших файлов. CX Codex +1 ★ 126звёзд репо obsidian-cli kepano Скилл obsidian-cli для Claude Code управляет заметками и поиском в хранилище Obsidian через CLI. Также помогает разрабатывать и отлаживать плагины и темы. CX Codex +1 83 700установок prior-work-retrieval daymade Скилл prior-work-retrieval для Claude Code находит и проверяет уже существующие наработки в проекте до написания нового кода. Запускается по прямому запросу о повторном использовании. CX Codex +1 218установок wiki-query AgriciDaniel Скилл wiki-query отвечает на вопрос по выбранному хранилищу Obsidian и не меняет в нём ни одного файла. Полезен, когда источником доказательств назначена сама вики. CX Codex +1 512установок obsidian-canvas-creator axtonliu Скилл obsidian-canvas-creator для Claude Code, Cursor, Codex и других агентов: превращает текст в файл Obsidian Canvas с раскладкой MindMap или произвольной сеткой. Агент строит JSON-граф прямо в чате — готовый к импорту в Obsidian. CX Codex +1 2 000установок

Из того же набора51

Весь набор →
obsidian-decide Команда obsidian-decide для Claude Code достаёт решения из разговора и пишет их в заметки Obsidian: строкой с датой или полной записью ADR с флагом --formal. CX Codex +1 ★ 5 412звёзд репо obsidian-save Команда obsidian-save для Claude Code, Codex, GitHub Copilot и Gemini CLI сканирует диалог с Claude Code и распределяет решения, задачи, идеи и контакты по заметкам Obsidian. Фиксирует итоги рабочей сессии. CX Codex +1 ★ 5 412звёзд репо obsidian-learn Команда obsidian-learn собирает уроки из vault Obsidian, отделяет актуальные выводы от устаревших и предлагает кандидатов для _CLAUDE.md. CX Codex +1 ★ 5 412звёзд репо obsidian-catchup Команда obsidian-catchup для разбора всего, что вы накидали в Telegram-бот журнала на ходу: голосовые, текст, изображения, PDF, ссылки. Вы вытягиваете очередь, когда вернулись к ноутбуку, и интегрируете в vault вместе с Claude Code. CX Codex +1 ★ 5 412звёзд репо obsidian-projects Команда obsidian-projects для Claude Code собирает статус проектов из заметок Obsidian, Git и локальных документов. Она запускается по запросу обзора проектов или статуса конкретного проекта. CX Codex +1 ★ 5 412звёзд репо obsidian-brainstorm Команда obsidian-brainstorm для многоходового интервью об идее: агент задаёт вопросы по одному, пока идея не сойдётся, потом пишет дизайн-ноту с вариантами и рекомендацией. Подходит, если нужно продумать концепцию вместе, а не одним ударом. CX Codex +1 ★ 5 412звёзд репо podcast Команда podcast извлекает метаданные, расшифровку и саммари эпизода подкаста, сохраняя готовую заметку в хранилище Obsidian. CX Codex +1 ★ 5 412звёзд репо youtube Извлекает расшифровку, метаданные и популярные комментарии YouTube, затем сохраняет сводку в Obsidian. Флаг --visual добавляет анализ кадров. CX Codex +1 ★ 5 412звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой