Skip to content

Ґайд міграції для AI-агента: як перенести будь-який Obsidian Vault у структуру P.O.W.E.R.

Цільова аудиторія: AI-агенти (Claude, GPT, Gemini, OpenCode) з MCP-доступом до P.O.W.E.R.

Мета: Перетворити будь-який неструктурований Obsidian Vault на P.O.W.E.R.-сумісну базу знань з валідованими OKF-метаданими, P.A.R.A. структурою папок та ієрархічними індексами — повністю автономно.

Огляд

Цей протокол дозволяє будь-якому LLM-агенту виконати міграцію, комбінуючи:

  • MCP-інструменти — ingest_note, lint_vault, generate_index, read_sub_index, search_vault_tool
  • Доступ до файлової системи — читання .md файлів, переміщення старих файлів
  • Інтелект LLM — класифікація нотаток за категоріями P.A.R.A., визначення тайтлів, генерація описів

Агент виконує 6 фаз. Кожна фаза має чіткі критерії успіху.

Фаза 1: Дослідження (Discovery)

Мета: Зрозуміти поточний стан Vault.

Кроки

  1. Проскануйте директорію Vault — знайдіть всі .md файли рекурсивно, виключаючи .git/, node_modules/, __pycache__/, .venv/.

  2. Прочитайте кожен .md файл — захопіть повний вміст. Зверніть увагу:

  3. Чи є вже YAML frontmatter?
  4. Чи є поля type, title, description?

  5. Яка поточна структура папок?

  6. Визначте існуючі патерни — знайдіть:

  7. Теги (#tag в тексті або tags: у frontmatter)
  8. Вікіпосилання ([[Назва Нотатки]])
  9. Вкладені файли (![[image.png]])

  10. Назви папок, що натякають на категорії (наприклад, "Projects", "Archives")

  11. Запустіть lint_vault(vault_path) — базова перевірка здоров'я. Запишіть скільки нотаток не мають метаданих та скільки битих посилань.

Критерій успіху: Ви маєте повний інвентар всіх нотаток та їх поточного стану.

Фаза 2: Класифікація

Мета: Проаналізувати кожну нотатку та визначити її категорію P.A.R.A. + OKF-метадані.

Правила

Кожна нотатка отримує рівно один type:

Type P.A.R.A. Папка Коли використовувати
Project 01_Projects/ Активна робота з дедлайном або результатом
Area 02_Areas/ Постійна відповідальність без фіксованого дедлайну
Resource 03_Resources/ Довідкові матеріали, гайди, зовнішні посилання
Archive 04_Archive/ Завершені або застарілі проекти
Daily Log 06_Daily_Logs/ Часозалежні записи, сесійні логи, щоденники
System Guide PROTOCOLS/ Інструкції для AI-агентів, операційні протоколи

Для кожної нотатки визначте:

  1. title — заголовок H1 або ім'я файлу (1-200 символів)
  2. description — опис в один рядок (1-150 символів)
  3. type — категорія P.A.R.A. (див. таблицю)
  4. tags — релевантні ключові слова (опціонально, список рядків)
  5. resource — якщо нотатка посилається на зовнішній URL (опціонально)

Евристики класифікації

  • Використовуйте назву папки як підказку: old_projects/ → ймовірно Archive або Project
  • Аналізуйте вміст: щоденниковий стиль → Daily Log; довідковий → Resource
  • Перевіряйте внутрішні посилання: якщо багато посилань з інших нотаток → активне → Area або Project
  • Якщо не впевнені — за замовчуванням Resource

Критерій успіху: Кожна нотатка має чернетку (type, title, description, tags).

Фаза 3: Міграція

Мета: Створити кожну нотатку у відповідній папці P.A.R.A. з валідованим OKF frontmatter.

Крок 3a: Підготуйте скелет Vault (якщо потрібно)

Якщо Vault ще не має папок P.A.R.A., запустіть:

power init /шлях/до/vault

Або створіть структуру папок вручну:

00_Inbox/
01_Projects/
02_Areas/
03_Resources/
04_Archive/
05_Templates/
06_Daily_Logs/
PROTOCOLS/

Крок 3b: Інгест кожної нотатки

Для кожної класифікованої нотатки викличте MCP-інструмент ingest_note:

{
  "name": "01_Projects/My-Project",           // P.A.R.A. шлях + ім'я файлу (без .md)
  "note_type": "Project",                     // З NoteType enum
  "title": "My Project",                      // Людський заголовок
  "description": "Будуємо наступну велику річ", // 1-150 символів
  "content": "<повний вміст markdown>",       // Оригінальний вміст
  "tags": ["active", "dev"],                  // Опціонально
  "resource": "https://github.com/..."        // Опціонально
}

Важливі правила:

  • name включає префікс папки P.A.R.A. + ім'я файлу (підкреслення, без пробілів)
  • note_type має відповідати папці: 01_Projects/ → type: Project
  • content — це повний оригінальний markdown — спочатку видаліть старий YAML frontmatter
  • Інструмент ingest_note автоматично:
  • Валідує всі метадані через Pydantic v2
  • Записує файл з правильним OKF frontmatter
  • Перебудовує ієрархічний індекс
  • Додає запис у log.md
  • Запускає перевірку lint

Крок 3c: Пакетна ефективність

Для великих Vault (>50 нотаток) групуйте інгести за категоріями. Спочатку Resource, потім Area, потім Project і т.д. Це робить перебудову індексу передбачуваною.

Критерій успіху: Всі нотатки перестворено в папках P.A.R.A. з валідним OKF frontmatter. Індекс актуальний.

Фаза 4: Верифікація

Мета: Підтвердити, що Vault повністю здоровий.

Кроки

  1. Запустіть lint_vault(vault_path) — очікуйте: 

    ✅ OKF Metadata: 0 помилок
✅ Internal Links: 0 битих
✅ Orphans: 0 (або очікувані в Daily Logs)

  2. Вибірково перевірте файли — прочитайте 3-5 випадкових нотаток, щоб переконатися, що frontmatter правильний і вміст цілий.

  3. Перевірте ієрархічний індекс — викличте read_sub_index(category="01_Projects", vault_path=...) і переконайтеся, що повертається валідний sub-index.

  4. Перевірте пошук — викличте search_vault_tool(query="test", vault_path=...) і переконайтеся, що результати коректні.

Критерій успіху: Lint проходить з нульовими помилками. Вибіркова перевірка проходить.

Фаза 5: Прибирання (Опціонально)

Мета: Видалити старий, неструктурований файли після верифікації міграції.

Кроки

  1. Знайдіть файли, що залишилися поза папками P.A.R.A.
  2. Для кожного:
  3. Якщо успішно мігровано (вміст існує в папці P.A.R.A.) — видаліть
  4. Якщо не мігровано — дослідіть і класифікуйте
  5. Після всіх видалень запустіть generate_index(vault_path) для оновлення
  6. Виконайте фінальний lint_vault(vault_path)

⚠️ Увага: Видаляйте файли тільки після повної верифікації. Для безпеки краще переміщувати в 04_Archive/, ніж видаляти.

Фаза 6: Післяміграційне самопідтримання та Синхронізація (Post-Migration Maintenance & Sync)

Мета: Гарантувати постійне збереження здоров'я бази знань між сесіями роботи AI-агентів, а також синхронізувати зміни із віддаленим сховищем.

Крок 6a: Встановлення P.O.W.E.R. Framework для AI-агентів

Для автономної роботи агента на цільовому хості встановіть інструментарій P.O.W.E.R. глобально або у віртуальне середовище проєкту:

pip install git+https://github.com/weby-homelab/power-framework.git

Налаштуйте інтеграцію MCP-сервера у вашому клієнті AI-агента або конфігураційному файлі IDE (наприклад, cline_config.json, opencode.jsonc, налаштуваннях Cursor/Windsurf тощо):

"mcpServers": {
  "power": {
    "command": "python",
    "args": ["-m", "power_framework.mcp"],
    "enabled": true
  }
}

Це надає вашому агенту доступ до інструментів валідації (lint_vault), автоматичного індексування (generate_index, read_sub_index) та пошуку (search_vault_tool).

Крок 6b: Оптимізація контексту (Файли ігнорування)

Для запобігання переповненню контексту AI-агента зайвими файлами (бінарними файлами, кешами, системними папками Git) створіть файл конфігурації ігнорування (наприклад, .geminiignore, .cursorignore або .gitignore залежно від вашого IDE) у корені робочого простору:

.git/
.gitignore
.geminiignore
.cursorignore
__pycache__/
*.pyc
.venv/
venv/
node_modules/
*.db
*.key
*.pem
*.crt
*.log

Крок 6c: Конфігурація інструкцій та правил для AI-агентів

Налаштуйте передачу правил проєкту вашому агенту через системні файли правил (наприклад, .clinerules, .cursorrules, .windsurfrules) або секцію інструкцій у конфігурації клієнта. Приклад структури файлів інструкцій: - RULES.md / INSTRUCTIONS.md — загальні правила поведінки агента. - MASTER-LESSONS-LEARNED.md — журнал засвоєних уроків та edge-cases для запобігання повторенню помилок. - power/SKILL.md — правила роботи з методологією P.A.R.A.

Крок 6d: Виправлення внутрішніх вікіпосилань

Оскільки файли переміщуються у папки P.A.R.A. (01_Projects/, 02_Areas/ тощо), старі прямі вікіпосилання стають недійсними. AI-агент має перевірити та оновити посилання [[Назва нотатки]] на релевантний відносний шлях у форматі [[P.A.R.A. папка/Назва нотатки|Аліас]]. P.O.W.E.R. Linter автоматично перевіряє биті посилання, а оновлення виконується через скрипт автокорекції або інструменти редагування коду.

Крок 6e: Автоматичне оновлення індексів (_index.md)

Файли _index.md для кожної папки P.A.R.A. є обов'язковими навігаційними картами. Вони генеруються автоматично через команду power index. Правило для агента: Після будь-якої зміни структури нотаток (додавання, переміщення, видалення) завжди виконуйте регенерацію індексів за допомогою MCP-інструменту generate_index або CLI power index.

Крок 6f: Виключення системних папок

Переконайтеся, що валідатор та генератор індексу ігнорують приховані та системні папки (наприклад, .git/, .obsidian/), щоб уникновувати помилкових попереджень про відсутність метаданих або битих посилань у тимчасових файлах.

Крок 6g: Щоденний протокол обслуговування (Daily Maintenance)

Сесія роботи з базою знань має завершуватися циклом самопідтримання: 1. Збереження логу сесії — створення нотатки в 06_Daily_Logs/ (тип: Daily Log) з описом виконаної роботи. 2. Перебудова індексу — виконання power index для оновлення index.md та _index.md. 3. Оновлення журналу змін — додавання стислого запису в загальний log.md. 4. Валідація стану (Lint) — запуск power lint для підтвердження відсутності регресій.

Крок 6h: Чек-лист безперервності між сесіями

Перед початком нової робочої сесії AI-агент повинен: 1. Прочитати загальні правила проєкту та інструкції. 2. Ознайомитися з MASTER-LESSONS-LEARNED.md (журналом помилок). 3. Запустити power lint для перевірки поточного стану бази знань. 4. Прочитати навігаційний індекс index.md та історію змін log.md.

Крок 6i: Синхронізація з Git та Публікація (Sync & Publish)

Для збереження історії та спільного доступу до бази знань налаштуйте процес синхронізації: 1. Ідентичність комітера: Налаштуйте user.name та user.email у Git відповідно до вашого профілю розробника. Уникайте комітів від системних користувачів на кшталт root. 2. Конфігурація безпеки: Додайте конфіденційні файли (ключі, паролі, конфігураційні файли, тимчасові файли експорту) у .gitignore. 3. GPG-підпис (за наявності вимог): Налаштуйте підпис комітів (commit.gpgsign=true) за допомогою вашого персонального GPG-ключа. 4. Робочий процес Git (PR Workflow): - Робота над змінами має вестися в окремих гілках (feature/*). - Публікація змін у головну гілку здійснюється через Pull Request після проходження всіх локальних тестів та автоматичних перевірок (CI/CD).

Крок 6j: Повнотекстовий пошук (FTS) на базі SQLite FTS5

Фреймворк P.O.W.E.R. включає вбудовану систему повнотекстового пошуку на базі SQLite FTS5. Вона автоматично створює локальну базу даних .power_search.db у корені Vault та інкрементально синхронізує її при кожному виклику пошуку.

Правила використання пошуку для AI-агентів: 1. Економія токенів: Замість рекурсивного сканування файлової системи (glob **/*.md) або зчитування вмісту файлів для пошуку ключових слів, агенти зобов'язані використовувати MCP-інструмент search_vault_tool(query, max_results=20). Це знижує споживання контексту на 95%+. 2. Синтаксис запитів: - Пошук за фразою: Використовуйте подвійні лапки для пошуку точних фраз, наприклад: search_vault_tool(query='"Docker Compose"'). - Пошук за префіксом: Скрипт автоматично додає зірочку * до кожного слова (наприклад, dock* знайде docker, docking тощо) для гнучкості. - Уникайте спецсимволів: Не передавайте спецсимволи (окрім подвійних лапок), оскільки вони можуть викликати синтаксичну помилку в SQLite FTS5. 3. Безпека: Файл бази даних .power_search.db автоматично додається до .gitignore та .geminiignore (через маску *.db), тому його категорично заборонено комітити в Git.

Приклад: Повний транскрипт міграції

Ось як виглядає повна міграція з точки зору агента:

Agent: Сканую Vault /Users/alice/obsidian...
Agent: Знайдено 47 .md файлів, 12 папок
Agent: 31 мають frontmatter, 16 — сирий markdown
Agent: Запускаю класифікацію всіх нотаток...

Нотатка "Daily Thoughts 2026-06-15" → Daily Log
Нотатка "Project Alpha Requirements" → Project  
Нотатка "Docker Cheatsheet" → Resource
Нотатка "Old Meeting Notes 2024" → Archive
...

Agent: Мігрую через MCP-інструмент ingest_note...
  ✅ 01_Projects/Project-Alpha-Requirements.md
  ✅ 01_Projects/Project-Beta-Plan.md
  ✅ 02_Areas/Health-Routine.md
  ✅ 03_Resources/Docker-Cheatsheet.md
  ✅ 04_Archive/Old-Meeting-Notes-2024.md
  ✅ 06_Daily_Logs/2026-06-15_Daily-Thoughts.md
  ... (всього 47 нотаток)

Agent: Запускаю lint...
  ✅ OKF Metadata: 0 помилок
  ✅ Internal Links: 0 битих
  ✅ Orphans: 3 нотатки (всі в 06_Daily_Logs — виключення)

Agent: Запускаю Фазу 6: Синхронізація та Публікація...
Agent: Імпортую GPG-ключ та налаштовую ідентичність Git
Agent: Створюю підписаний коміт у гілці feature/power-migration
Agent: Надсилаю зміни до GitHub та створюю Pull Request
Agent: Перевіряю статус CI/CD воркфлоу...
  ✅ Збірка MkDocs успішна: https://weby-homelab.github.io/power-framework/

Agent: Міграцію та публікацію успішно завершено. Vault сумісний з P.O.W.E.R.

Вирішення проблем

Проблема Причина Виправлення
ingest_note повертає "Note already exists" Нотатку вже мігровано Пропустіть і йдіть далі
Lint повідомляє про відсутній type Нотатка не має frontmatter Переінгестіть з явним note_type
Бите посилання після міграції [[посилання]] змінили імена файлів Запустіть скрипт авто-ремонту з Кроку 6d
read_sub_index повертає "No notes found" Папка категорії порожня або не проіндексована Спочатку запустіть generate_index(vault_path)
Забагато orphans в 04_Archive/ Архівні нотатки за визначенням мають мало посилань Це очікувано — orphans в архіві нормальні
Lint повідомляє 200+ зайвих нотаток Директорію .git/ не виключено Оновіть лінтер для пропуску прихованих папок (v1.5.0+ робить це)
_index.md не має frontmatter Використовується стара версія фреймворку Оновіться до v1.5.0+ або перезапустіть generate_index
pip install падає з PEP 668 Системний Python блокує пряме встановлення Використовуйте venv: /шлях/до/venv/bin/pip install ...

Додатки

A. Відповідність папок та типів

Папка note_type Типовий вміст
00_Inbox/ Будь-який Необроблені чернетки (агент має класифікувати та перенести)
01_Projects/ Project Активні проекти з результатами
02_Areas/ Area Постійні обов'язки
03_Resources/ Resource Довідники, гайди, зовнішні посилання
04_Archive/ Archive Завершені/мертві проекти
06_Daily_Logs/ Daily Log Часозалежні щоденникові записи
PROTOCOLS/ System Guide Інструкції для агентів, правила

B. Необхідні MCP-інструменти

Інструмент Використовується у фазі
ingest_note(name, note_type, title, description, content, tags?, resource?) Фаза 3
lint_vault(vault_path?) Фаза 1, 4, 5, 6
generate_index(vault_path?) Фаза 5, 6
read_sub_index(category, vault_path?) Фаза 4, 6
search_vault_tool(query, vault_path?) Фаза 4, 6

C. Швидка довідка: поля OKF Frontmatter

---
type: Project | Area | Resource | Daily Log | Archive | System Guide
title: "Людський заголовок (1-200 символів)"
description: "Опис в один рядок (1-150 символів)"
resource: "https://..."          # Опціонально
tags: [tag1, tag2]               # Опціонально
timestamp: 2026-07-03T12:00:00   # Авто-генерується
---

Створено AI-агентами для AI-агентів ⚡
© 2026 Weby Homelab