[2026-11-18] eagle: personal/knowledge/obsidian/reference/knowledge-lifecycle.md personal/knowledge/obsidian/reference/obsidian-mcp-setup.md personal/knowledge/obsidian/reference/obsidian-mcp-wrapper.md personal/knowledge/obsidian/reference/obsidian-vault-strategy.md personal/knowledge/obsidian/reference/research-queue.md personal/knowledge/obsidian/reference/vault-agent-integration.md personal/knowledge/obsidian/reference/vault-filling-guide.md personal/knowledge/obsidian/reference/vault-namespace.md personal/knowledge/obsidian/reference/wiki-ingest-process.md personal/knowledge/obsidian/reference/wiki-schema.md

This commit is contained in:
Alexey Martemyanov committed 2026-11-18 19:05:28 +06:00
1 parent 80af10ff9d
commit 8da10d04c9
99 files changed
+5376 -24330

No files matched your search

@@ -0,0 +1,82 @@
---
namespace: work
tags:
- agent
- memory
- wiki
- synthesis
- vault
created: '2026-05-19'
updated: '2026-10-14'
type: concept
confidence: 0.9
sources:
- wiki/concepts/agent-memory-architecture.md
- wiki/concepts/vault-strategy.md
- wiki/wiki-ingest-process.md
- wiki/personal-os-self-modification.md
---
# Knowledge Lifecycle — From Session to Permanent Memory
Синтез: как знание движется от рабочей сессии к постоянной памяти в personal-os. Объединяет [[personal/projects/personal-os/agent-memory-architecture]], [[personal/projects/personal-os/obsidian-vault-strategy]] и [[wiki-ingest-process]].
## Общая схема
```
Событие/Разговор
│
▼
Working Memory (контекст сессии, эфемерный)
│ session_search + SHA256 hash
▼
Episodic Memory (SQLite sessions, сжатые саммари)
│ crystallization (wiki-curation cron 02:00)
▼
Semantic Memory (wiki/ pages, постоянное знание)
│ wiki-ingest 22:00 (launchd, claude -p)
│ overflow rule (>150 chars → vault)
▼
Procedural Memory (skills/, workflows)
```
## Три барьера кристаллизации
Не всё знание заслуживает кристаллизации. Барьеры:
| Уровень | Критерий | Место |
|---------|----------|-------|
| Session → Wiki | Painful to re-derive? Fits domain? Contains facts (not conversation)? | `wiki/` |
| Wiki → MEMORY.md | Стабильный факт, ≤150 символов? | `~/.hermes/MEMORY.md` |
| Any → Skills | Пошаговая процедура, повторяемая? | `~/.hermes/skills/` |
**Правило overflow:** MEMORY.md — только короткие стабильные факты. Детали → в wiki с pointer в MEMORY.md: `"media-pipeline питфолы → wiki/tech/media-pipeline-pitfalls.md"`.
## Три задачи vault (не смешивать)
1. **Vault Enrichment** — frontmatter + aliases + wikilinks на `personal/`, `family/`
2. **LLM Wiki** — crystallization sessions → `wiki/` (этот файл про это)
3. **Proactive Research** — агент генерирует гипотезы → `wiki/research-queue.md` → Saturday cron
## Риски деградации
- **Summarization drift:** после 3+ циклов сжатия теряются критические инструкции. Решение: vault как immutable store (не перезаписывать, только аппендить/обновлять dated sections).
- **Repetitive behavior:** без weekly reflection агент деградирует (Generative Agents, 48ч без рефлексии). Фикс: Retrospector каждую пятницу читает corrections_log.
- **Orphaned knowledge:** факт записан, но никогда не читается. Фикс: lint (orphan pages), провалидированные wikilinks.
## Инструменты в personal-os
| Инструмент | Функция |
|-----------|---------|
| wiki-curation cron (02:00) | Crystallization: sessions → wiki |
| wiki-ingest launchd (22:00) | Synthesis: raw/ symlinks → wiki pages |
| `session_search` | Episodic retrieval |
| obsidian MCP | Semantic retrieval |
| MEMORY.md | Fast facts, overflow pointers |
| research-queue.md | Proactive research agenda |
## Связанные страницы
- [[personal/projects/personal-os/agent-memory-architecture]] — когнитивная таксономия памяти (episodic/semantic/procedural)
- [[personal/projects/personal-os/obsidian-vault-strategy]] — три задачи vault: enrichment, LLM wiki, proactive research
- [[wiki-ingest-process]] — hash-based incremental ingest из raw/ symlinks
- [[personal-os-self-modification]] — как система эволюционирует через корректировки
@@ -0,0 +1,216 @@
> [!IMPORTANT] Актуальная конфигурация для Balda (2026-10-09)
> Текущая Balda использует Codex ACP и Streamable HTTP: `type: http`, URL `http://host.docker.internal:3101/mcp`.
> Указания ниже про Balda + SSE или `/sse` относятся к прежним клиентам/развёртываниям. Канонический runbook: [[personal/projects/balda/setup]].
# Obsidian MCP — текущая архитектура
## Факт: что стоит сейчас
**Hermes native MCP client** (встроен в Hermes Agent, не wrapper).
Конфиг в `~/.hermes/config.yaml` (и в `~/.hermes/hermes-whale/config.yaml`):
```yaml
mcp_servers:
obsidian:
command: mcpvault
args:
- /Users/admin/obsidian
```
Пакет: **`@bitbonsai/mcpvault`** v0.12.1 (npm). Команда `mcpvault`.
Hermes на старте:
1. Читает `mcp_servers` из config.yaml
2. Спавнит `mcpvault /Users/admin/obsidian` как subprocess
3. Init + list_tools → регистрирует инструменты как `mcp_obsidian_*`
4. Агент видит инструменты `mcp_obsidian_read_note`, `mcp_obsidian_patch_note`, и т.д.
**Схема:**
```
Hermes (native MCP client) → spawn: mcpvault → reads/writes /Users/admin/obsidian/
```
### Инструменты, доступные через эту связку
`read_note`, `write_note`, `patch_note`, `list_directory`, `delete_note`, `search_notes`, `move_note`, `move_file`, `read_multiple_notes`, `update_frontmatter`, `get_notes_info`, `get_frontmatter`, `manage_tags`, `get_vault_stats`, `list_all_tags`.
## Факт: что такое ~/scripts/obsidian-mcp-wrapper.js и почему он НЕ используется
**Создан** 2026-05-09, когда вместо `mcpvault` стоял `npx obsidian-mcp` (старый пакет, автор Steven, ещё до переименования в `@bitbonsai/mcpvault`). Пакет постоянно падал:
- ZodError на `"id": null` в notifications — `.strict()` валидация
- Race condition при рестарте gateway
- UTF-8 chunk split портил большие JSON
- Зависания без watchdog
Wrapper решал всё это. **Сейчас НЕ используется.** Конфиг в `~/.hermes/config.yaml`:
```yaml
mcp_servers:
obsidian:
command: mcpvault # ← не node wrapper.js
args:
- /Users/admin/obsidian
```
**Почему:** после перехода на `@bitbonsai/mcpvault` (пришёл на смену старому obsidian-mcp), пакет стабильно работает с Hermes native MCP client. Wrapper стал не нужен. Конфиг поменяли, а doc не обновили.
**Файл `~/scripts/obsidian-mcp-wrapper.js`** лежит на диске, не используется. Надо удалить.
## Факт: корень проблем с patch_note
`mcp_obsidian_patch_note` падает с `"String not found"` — это **НЕ проблема транспорта**. Это проблема **самого mcpvault**:
- Файл: `dist/src/filesystem.js`, строка 217
- Механизм: `fullContent.split(oldString).length - 1`
- **Exact string match** — без trim, без fuzzy, без нормализации whitespace
Workaround: использовать Hermes `patch()` (fuzzy matching, 9 стратегий) для сложных строк. `mcp_obsidian_patch_note` — только для простого текста без спецсимволов.
## Fact: Obsidian MCP на Kraken — есть, и это stdio-процесс Hermes
Проверено 2026-09-26. На Kraken MCP-сервер **не является отдельным контейнером** —
его спавнит агент Hermes как дочерний процесс. Первый поиск «нет контейнера →
нет MCP» был **ошибочным**: искать надо было процессы, а не `docker ps`.
```
# на хосте Kraken
ps aux | grep mcpvault
→ UID 10000 1168741 ... node /opt/data/.local/bin/mcpvault /vault
PPID 5039 → /opt/hermes/.venv/bin/hermes gateway (контейнер hermes-kraken)
```
Конфиг (`/opt/data/config.yaml` **внутри** контейнера `hermes-kraken`):
```yaml
mcp_servers:
obsidian:
command: /opt/data/.local/bin/mcpvault
args:
- /vault
```
`mcpvault` там — симлинк на npm-пакет: `/opt/data/.local/lib/node_modules/@bitbonsai/mcpvault/dist/server.js`.
### Волт на Kraken — реальный, не пустой
```
/home/kraken/obsidian -> /srv/dev-disk-by-uuid-49e8f586-…/obsidian
(тот же HDD, что и docker-data)
```
Внутри: `personal/`, `family/`, `.obsidian/`, `.git/`, `_index.md` — полноценная
git-реплика волта Mac. То есть **волт существует в обоих местах**, а не только на Mac.
### Итог: два независимых Obsidian MCP
| Где | Как | Транспорт | Порт |
|---|---|---|---|
| Mac | контейнер `obsidian-mcp` (`mcp-proxy` → `mcpvault`) | SSE | `:3101`, публикуется на `0.0.0.0` |
| Kraken | `mcpvault` как дочерний процесс `hermes-kraken` | **stdio** | нет |
| Kraken (для Балды) | контейнер `obsidian-mcp` — **создан 2026-09-26** | SSE | `:3101`, только внутри `mattermost_mm-net` |
📌 `mcpvault` **не умеет HTTP** — только stdio (`--help` подтверждает: только `[vault-path]`).
Чтобы отдать его по сети, нужен `mcp-proxy` (обёртка stdio → SSE). Именно так сделано
на Mac и повторено на Kraken.
---
## Fact: obsidian-mcp на Kraken для Балды (создан 2026-09-26)
Собрано для шага 5 [[personal/plans/balda-mm-phase4-agents]]: Балде нужен доступ к
волту, чтобы читать документацию при формировании ТЗ.
**Точная копия рабочей схемы с Mac** — пара `mcp-proxy` + `mcpvault`:
| Что | Путь / значение |
|---|---|
| Проект (Mac) | `~/Developer/obsidian-mcp-kraken/` |
| Dockerfile | `node:24-bookworm` + `@bitbonsai/mcpvault@0.11.0` + `mcp-proxy@6.4.4` |
| Образ | `obsidian-mcp-image:0.1.0` (загружен на Kraken) |
| Compose (Kraken) | `/home/kraken/obsidian-mcp/docker-compose.yml` |
| Контейнер | `obsidian-mcp`, сеть `mattermost_mm-net` |
| Волт | `/srv/dev-disk-by-uuid-49e8f586-…/obsidian` → `/vault` **`:ro`** |
| Команда | `mcp-proxy --port 3101 -- mcpvault /vault` |
🔴 **Волт смонтирован только для чтения (`:ro`).** Балда читает документацию, но не
правит её. Запись в волт через Балду — отдельное решение, требует апрува Alex.
```yaml
services:
obsidian-mcp:
image: obsidian-mcp-image:0.1.0
container_name: obsidian-mcp
restart: unless-stopped
command: ["--port", "3101", "--", "mcpvault", "/vault"]
volumes:
- /srv/dev-disk-by-uuid-49e8f586-…/obsidian:/vault:ro
networks:
- mm-net # mattermost_mm-net, external
```
### Питфоллы, пройденные при сборке
| # | Питфолл | Симптом | Фикс |
|---|---|---|---|
| 1 | `--host` у `mcp-proxy` **нет** | контейнер падает на разборе аргументов | только `--port N -- <cmd> <args>`; слушает `0.0.0.0` по умолчанию |
| 2 | Точка монтирования должна существовать в образе | `mkdir -p /vault` в Dockerfile + `WORKDIR /vault` | иначе mcpvault стартует не в том каталоге |
### Проверка
```bash
# /sse отвечает 200 (и локально, и из docker-сети Kraken)
curl -s -o /dev/null -w "%{http_code}\n" http://obsidian-mcp:3101/sse
# ⚠️ Порт именно 3101, НЕ 8080. Проба на 8080 даёт "Connection refused" при живом
# контейнере — mcp-proxy слушает порт из --port.
```
✅ **ПРИМЕНЕНО 2026-09-26.** Конфиг Балды на Kraken теперь содержит оба сервера:
```yaml
runtime:
mcp_servers:
executor-mcp:
type: http # ⚠️ НЕ streamable-http — валидатор: stdio|http|sse
url: "http://balda-executor-mcp:8890/mcp"
obsidian:
type: sse # ⚠️ НЕ http — у obsidian-mcp SSE-транспорт
url: "http://obsidian-mcp:3101/sse"
balda:
mcp_servers:
- executor-mcp
- obsidian
```
🔴 **Тип транспорта — источник двух подряд ошибок.** Obsidian отдаёт **SSE**, поэтому
`type: sse`. Если поставить `type: http`, Балда упадёт с
`failed to init MCP session: … session not found`.
Полная таблица типов — [[personal/tech/balda-executor-mcp]] §10e.
Бэкапы: `config.yaml.bak-obsidian-20260926-214849` (на Kraken, рядом с `config.yaml`).
⚠️ Туннель к Obsidian MCP **не нужен** — Балда ходит по docker-сети по имени
`obsidian-mcp`. Наружу порт не публикуется.
---
## Эволюция Obsidian MCP у нас
| Период | Что было | Проблемы |
|--------|----------|----------|
| До 2026-05-09 | `npx obsidian-mcp` (пакет Steven, прямой) | ZodError, race condition, UTF-8 chunk split, зависания |
| 2026-05-09 → ? | `npx obsidian-mcp` через wrapper | Wrapper решил проблемы |
| Сейчас | `mcpvault` (Hermes native MCP client) | Стабильно. patch_note exact match — единственная боль |
## Рекомендация по замене (2026-06-24)
При проблемах с mcpvault (зависания, память, exact match) — **cyanheads/obsidian-mcp-server**:
- `obsidian_replace_in_note` с regex + flexible whitespace (решает exact match)
- 9.7K dl/week, dual transport (stdio + HTTP), active
- Требует Obsidian Local REST API plugin (Obsidian должен быть открыт)
- Есть Docker support (`ghcr.io/cyanheads/obsidian-mcp-server`)
Подробнее: `personal/tech/obsidian-mcp-ecosystem.md`
## См. также
- `personal/tech/obsidian-mcp-ecosystem.md` — обзор всех 6 реализаций
- ⚠️ `personal/projects/personal-os/obsidian-mcp-wrapper.md` — **УСТАРЕЛ**, не отражает реальность
@@ -0,0 +1,25 @@
---
status: deprecated
superseded_by: personal/projects/personal-os/obsidian-mcp-setup.md
reason: >-
wrapper не используется с 2026-05. Реальность: Hermes native MCP client →
mcpvault
---
# obsidian-mcp-wrapper — УСТАРЕЛ
> **⚠️ Этот документ не отражает реальность.** Wrapper не используется с мая 2026.
> См. `personal/projects/personal-os/obsidian-mcp-setup.md` и
> `personal/tech/obsidian-mcp-ecosystem.md`.
Актуальная архитектура: **Hermes native MCP client → spawn `mcpvault /Users/admin/obsidian`**
(пакет `@bitbonsai/mcpvault` v0.12.1). Конфиг в `~/.hermes/config.yaml` → `mcp_servers.obsidian`.
Wrapper (`~/scripts/obsidian-mcp-wrapper.js`) когда-то решал проблемы старого пакета `obsidian-mcp`
(автор Steven), который падал с ZodError, race condition и UTF-8 chunk split.
После смены пакета на `@bitbonsai/mcpvault` — wrapper стал не нужен.
Корень проблем с `patch_note` (`"String not found"`) — exact string match в самом mcpvault,
**не в транспорте**. Workaround: использовать Hermes `patch()` с fuzzy matching.
Историческая документация по wrapper сохранена ниже для ретроспективы.
@@ -0,0 +1,550 @@
---
title: "Obsidian Vault Strategy & LLM Wiki"
aliases:
- "Vault Strategy"
- "obsidian-vault-strategy"
- "LLM Wiki Plan"
created: '2026-05-15'
updated: '2026-10-14'
tags:
- personal-os
- obsidian
- vault
- strategy
- llm-wiki
status: active
related:
- "[[personal/projects/personal-os/personal-os-architecture]]"
- "[[personal/projects/personal-os/executor-security-analysis]]"
---
# Obsidian Vault Strategy & LLM Wiki Plan
> Deep research 2026-05-15.
> Источники: Karpathy LLM Wiki gist (5000+ stars), LLM Wiki v2 (rohitg00, 1200+ stars), claude-obsidian (PyShine), Ar9av/obsidian-wiki (DeepWiki), Tom Nguyen 6-month report, Nodus Labs knowledge graph extension, mathisgauthey (r/ObsidianMD, 1000+ upvotes), MOC+Dataview guide, Obsidian+Claude Code integration, LifeOS, Obsidian Forum.
---
## Часть 1 — Текущее состояние vault
### Что есть
| Тип контента | Примеры | Где лежит |
|---|---|---|
| Личные списки | Список дел, Фильмы, Книги, Покупки | `personal/documents/`, `family/documents/` |
| Брифы и планы | Daily brief, weekly plan, inbox triage | `work/briefs/` |
| Проектные заметки | executor, media-pipeline, wiki | `personal/projects/`, `family/projects/` |
| How-to документация | HTPC, Кракен, WireGuard | `family/how-to/` |
| Knowledge wiki | Архитектура personal-os, схема БД | `wiki/` |
### Что не работает
- **Граф пустой** — 90% заметок без frontmatter, aliases, wikilinks. Поиск находит только по точному имени файла.
- **Воркер переименовал файлы** без aliases → `✅ Список дел` → `todo-list.md`, поиск сломан.
- **Wiki-curation делает лишнее** — Task 3b (раскладка файлов по папкам) не относится к Karpathy, добавлен ошибочно.
- **Нет накопления знаний** — каждый research-сеанс начинается с нуля. Пример: анализ Obsidian PKM занял 15 минут и 10+ web запросов, которые нужно будет повторять снова.
- **Нет проактивных исследований** — агент реагирует на запросы, не инициирует изучение пробелов.
---
## Часть 2 — Анализ подходов из research
### Karpathy LLM Wiki (оригинал, апрель 2026)
**Суть:** LLM читает сырые источники → строит wiki с entity/concept pages → cross-references → compounding knowledge base. Человек почти не пишет в wiki руками.
**Ключевые цифры:** Karpathy вырастил wiki на одну тему до ~100 статей, 400k слов, не написав ни одной напрямую. Tom Nguyen (6 месяцев в production): 77 wiki pages, 30+ источников, 13 custom skills читают из wiki.
**Три операции:**
1. **Ingest** — дропаешь источник, агент создаёт/обновляет 10-15 wiki pages
2. **Query** — агент читает index.md, находит нужные pages, даёт ответ со ссылками
3. **Lint** — проверка orphan pages, противоречий, stale claims, пробелов
**Применимость к нам:** Wiki для накопления knowledge (техника, workflows, инфраструктура, AI tools) — да. Для личных списков — нет.
---
### LLM Wiki v2 (rohitg00) — production extensions
**Ключевые расширения:**
**4-tier memory pipeline:**
```
Working Memory → сырые наблюдения текущей сессии
Episodic Memory → сжатые саммари сессий
Semantic Memory → кросс-сессионные факты (wiki)
Procedural Memory → паттерны, workflows, skills
```
**Confidence scoring:** каждый факт имеет score (кол-во источников, свежесть, противоречия). Устаревает со временем, усиливается при подтверждении.
**Event-driven automation:**
```
On new source → auto-ingest, extract entities, update graph
On session end → compress session into observations, file insights
On query → check if answer worth filing back
On schedule → periodic lint, consolidation
```
**Кристаллизация:** завершённые debug/research сессии автоматически дистиллируются в wiki pages.
---
### claude-obsidian / Ar9av/obsidian-wiki — автономные skills
Наиболее зрелые production реализации. Ключевые skills:
**`wiki-synthesize`** — сканирует vault, находит concept pairs которые часто co-occur но не имеют synthesis page. Строит `Concept A × Concept B` pages автоматически.
**`wiki-research` (3-round autonomous loop):**
- Round 1: decompose topic → 3-5 angles → broad search
- Round 2: find gaps/contradictions → targeted search
- Round 3: resolve contradictions → synthesis
**`wiki-capture`** — конвертирует AI-human сессии в declarative wiki notes. Эта сессия (анализ Obsidian PKM) должна была бы стать wiki pages автоматически.
**`autoresearch` (claude-obsidian):**
```
/autoresearch topic
→ Round 1: query wiki → identify gaps → ingest sources
→ Round 2: re-query → find remaining gaps → more sources
→ Round 3: synthesis → comprehensive result with citations
```
**Session hooks:**
- `SessionStart` → load hot cache, read schema
- `PostToolUse` → auto-commit if files changed
- `Stop` → save final state, update manifest
---
### Knowledge Graph extension (Nodus Labs)
Добавляет структурную самоосознанность поверх Karpathy:
**Gap detection:** находит disconnected clusters в wiki graph. Там, где два тематических кластера не связаны — это часто место для нового insight или исследования.
**Prompt-to-structure:** вместо "объясни X" → "как A связан с B, учитывая что они в разных кластерах?" → более точные, оригинальные ответы.
---
### Проактивные исследования — PersonalAgent pattern (arxiv 2512.15302)
**Идея:** агент строит user profile → из профиля выводит гипотезы что пользователю может быть интересно → инициирует исследования без запроса.
**Применительно к нам:** агент знает что ты работаешь над personal-os, media-pipeline, executor — и проактивно исследует смежные темы: новые подходы к orchestration, медиа-библиотеки, home automation.
**Реализация:** weekly cron который читает wiki + профиль + последние сессии → формирует список hypothesis → запускает `wiki-research` по каждой → результаты в inbox для review.
---
## Часть 3 — Что реально нужно нам
### Три разных задачи (не смешивать!)
**Задача A: Vault enrichment** — сделать личные заметки searchable и связными
- frontmatter + aliases на существующие файлы
- wikilinks между связанными заметками
- MOC/index files для навигации
**Задача B: LLM Wiki для knowledge accumulation** — накапливать research результаты
- `wiki/` как compounding knowledge base
- Research сессии → wiki pages
- Lint + gap detection
**Задача C: Проактивные автономные исследования** — агент сам генерирует гипотезы и исследует
- User profile → hypothesis generation
- Scheduled research runs
- Results → inbox для review
---
## Часть 4 — План: три проекта
### Проект 1: Vault Enrichment
**Цель:** граф живой, поиск работает по aliases, Dataview агрегирует, файлы связаны по смыслу.
#### Ключевой принцип: topic map как источник правды
`family/index.md` и `personal/index.md` — это не просто каталоги файлов, а **топик-карты vault**.
Карта содержит:
- Топики / кластеры (Алтай, Лаки Парк, Kraken, psychologist-app, …)
- Какие файлы принадлежат каждому кластеру
- Ссылку на hub-note кластера (основную заметку)
**Enrichment воркер читает карту первым делом и работает по ней** — не по хардкоду в промпте. Если находит новый кластер которого в карте нет — добавляет его туда сам. Карта самодополняется.
```
family/index.md (topic map)
├── ## Место: Алтай
│ hub: family/places/altai.md (создать при необходимости)
│ files: altai-shopping, altai-house-inventory
├── ## Место: Лаки Парк (Тайга)
│ hub: family/how-to/truenas-infrastructure.md
│ files: lerua-shopping, fasteners-nomenclature
├── ## Инфраструктура: Kraken
│ hub: family/how-to/kraken-access.md
│ files: kraken-portainer-access, openmediavault-rpi5, …
└── …
```
#### Шаги
1. ✅ Убрать Task 3b из wiki-curation промпта — **сделано 2026-05-16**
2. ✅ Добавить frontmatter + aliases на 24 файла documents/ — **сделано 2026-05-16**
3. ✅ Создать enrichment cron (воскресенье 03:00) — **запущен 2026-05-16**
4. **Пересобрать `family/index.md` и `personal/index.md` как топик-карты** (кластеры вместо плоских списков)
5. **Обновить промпт enrichment воркера**: читать index как карту, линковать по ней, дополнять при находке новых кластеров — **никакого хардкода в промпте**
6. Создать `personal/places/` и `family/places/` hub-notes для физических мест если нужны (Алтай, Лаки Парк)
**Стек:** Hermes cron + obsidian MCP + terminal toolset
**Правило:** воркер **никогда** не хардкодит конкретные файлы или топики в промпте. Карта = единственный источник правды о кластерах.
---
### Проект 2: LLM Wiki — Knowledge Accumulation
**Цель:** каждая research-сессия накапливается. Следующий вопрос про memory architectures → читаю 2 страницы wiki вместо 10 web запросов.
#### Компоненты
**Crystallization** — сессии → wiki pages (ежедневно в wiki-curation-daily)
- Воркер сканирует дневные сессии
- Критерий: знание painful to re-derive + fit wiki domain
- Дистиллирует факты (не разговор), создаёт/обновляет wiki pages
- ✅ Добавлено в wiki-curation-daily промпт (2026-05-16)
**Wiki-Synthesize** — co-occurring concepts → synthesis pages
- Воркер ищет темы из 3+ страниц без synthesis page
- Создаёт `comparisons/A-vs-B.md` или `concepts/A-and-B.md`
- Лимит: 1 страница за прогон
- ✅ Добавлено в wiki-curation-daily промпт (2026-05-16)
**Inbox drop** — быстрый путь добавить knowledge в очередь
- Файл в `wiki/raw/inbox/research-SLUG-YYYYMMDD.md` → обрабатывается следующей ночью
- ✅ Сегодняшняя сессия (vault strategy + memory architecture) заброшена в инбокс
#### Что войдёт в wiki
AI/ML memory architectures, Obsidian PKM patterns, personal-os architecture decisions, Swift/iOS patterns, media pipeline learnings, enrichment patterns.
**Стек:** wiki-curation-daily (расширенный) + inbox mechanism
**Статус:** ✅ Реализован 2026-05-16
---
### Проект 3: Proactive Research Agent
**Цель:** агент сам инициирует исследования исходя из профиля и пробелов в wiki.
#### Архитектура
```
Gap Detector (читает vault, находит темы без wiki-страниц)
↓
research-queue.md (приоритизированный список)
↓
proactive-research cron (суббота 05:00, 1 тема за прогон)
↓
3-round research loop → wiki page
↓
queue item помечается [x], wiki/index.md обновляется
```
#### Компоненты
**research-queue.md** (`wiki/research-queue.md`)
- Живой список тем для исследования
- Воркер берёт top-1 `[ ]` item каждую субботу
- Alex может добавлять вручную
- ✅ Создан с 7 начальными темами (2026-05-16)
**proactive-research cron** (суббота 05:00)
- Gap detection: темы 3+ упоминаний в vault без wiki-страницы → добавляет в queue
- 3-round research loop: broad → deep → synthesis
- Создаёт/обновляет wiki page, обновляет index.md, отмечает queue item
- ✅ Cron создан (job: 41896d17f5fc, 2026-05-16)
**Начальная очередь:**
- Obsidian Bases vs Dataview 2026
- Skip.tools production-readiness
- Home Assistant + Zigbee для RPi5
- AI mental health apps landscape
- Swift Concurrency 2026
- Personal OS orchestration alternatives
- Indie iOS monetization 2026
**Статус:** ✅ Инфраструктура создана 2026-05-16. Первый прогон: 2026-05-23.
---
### Проект 4: Cross-domain Enrichment Agent
**Цель:** vault note + external signal → personalized insight. Два режима: разовое обогащение и регулярный мониторинг.
#### Архитектура
```
Enrichment: Vault note + External (web) → companion note рядом с исходником
Monitoring: External stream → фильтр через user-profile → digest delivered
```
**vault-cross-enrichment cron** (воскресенье 04:00, web+file+terminal toolsets)
- Target discovery: `enrich-me` тег, файлы 30+ дней без обновления, app-ideas
- Enrichment types: app-ideas competitive analysis, wishlists (games/books/movies), travel, home automation
- Profile-aware: всё фильтруется через `wiki/user-profile.md`
- Output isolation: результат в `-enriched.md` companion файле, исходник не трогает
- Monitoring digest: tech stack updates, indie/App Store news, Bishkek local
- ✅ Cron создан (job: f3de00040aac, 2026-05-16)
---
## Часть 5 — Последовательность
```
Сейчас → Проект 1 (enrichment) — быстро, ощутимый результат
↓
Проект 2 (wiki accumulation) — параллельно или после
↓
Проект 3 (proactive research) — когда wiki достаточно наполнена
```
Проект 3 имеет смысл только когда в wiki есть достаточно контента чтобы gap detection давал сигнал. Сначала нужно наполнить wiki (Проект 2).
---
---
## Часть 5a — Паттерн: Personal Context → External Signal → Insight
Это отдельный класс задач — **cross-domain enrichment с внешними данными**. Агент читает личные данные из vault, учитывает профиль пользователя, обогащает внешними сигналами и возвращает персонализированный результат.
**Ключевое отличие от Google:** контекст про тебя уже внутри — агент не ищет абстрактный ответ, а фильтрует под конкретного человека.
### Общий паттерн
```
Заметка/список в vault
+ Связанные заметки (через wikilinks / поиск)
+ User Profile (возраст, интересы, текущий стек, предпочтения)
+ External signal (web, API, RSS, marketplace)
↓
Enrichment Agent (по триггеру или расписанию)
↓
Enriched note в vault (insights + cross-links + источники)
```
### Два режима агента
Примеры выше делятся на два разных паттерна — важно не смешивать:
**Enrichment** — обогащаешь данные один раз (или при изменении)
- Исходная заметка есть, нужно добавить внешний контекст
- Запускается по триггеру (новая запись) или периодически
- Результат стабилен, обновляется редко
- _Примеры: анализ идей приложений, learning path по списку книг, фильтрация игр под профиль_
**Monitoring** — следишь за потоком внешнего мира, фильтруешь через твой контекст
- Внешний мир меняется, vault — точка отсчёта для фильтрации
- Запускается регулярно (ежедневно / еженедельно)
- Результат — дайджест / алерт, не постоянная заметка
- _Примеры: новые заведения в Бишкеке, распродажи билетов под планы поездок, конференции по твоим темам, апдейты инструментов из стека_
```
Enrichment: Vault (данные) + External (контекст) → Enriched note в vault
Monitoring: External (поток) → фильтр через Vault (профиль) → Алерт / Дайджест
```
Оба нужны, но реализуются по-разному: enrichment — разовый агент с obsidian MCP, monitoring — регулярный cron с web toolset и доставкой в inbox/Zulip.
### Иллюстративные примеры (не задачи, а цепочки мышления)
**1. Список идей приложений → конкурентный анализ**
Читает каждую идею → ищет по YC directory / ProductHunt / web по ключевым словам → кто уже делает, funding, незакрытые ниши → сохраняет анализ рядом с идеей
**2. Активности с ребёнком × список игр × профиль ребёнка**
Читает списки активностей + игр → читает профиль (возраст, интересы, темперамент, что работает) → cross-links между файлами → фильтрует игры под совместную игру → ищет новые по интересам → персонализированные рекомендации с обоснованием
**3. Список для чтения → learning path**
Книги/статьи + текущие знания из wiki → определяет prerequisites, оптимальный порядок, находит пробелы в теме
**4. Wishlist путешествий → план поездок**
Список мест + сезонность + текущие проекты (когда реально есть время) → какие места удобно совмещать, оптимизированный план на год
**5. Профили контактов → напоминания о связи**
Список людей с датой последнего общения + интересы → "давно не писал X, вот повод" (вышла статья по его теме, etc.)
**6. Wishlist умного дома → совместимость и реализация**
Хотелки + текущий стек (Zigbee, HA версия) → что реально интегрируется, community-решения, очерёдность
**7. Дневник тренировок → инсайты**
Лог активностей + самочувствие + погода → что коррелирует с хорошими результатами, когда лучше тренироваться
**8. Скетчи музыкальных идей → рыночный контекст**
Заметки по трекам (BPM, настроение, референсы) → Spotify анализ похожих, что в тренде в жанре
**9. Список подарков → актуальные варианты**
Профили близких (интересы, что уже есть) × ближайшие даты → marketplace search с обоснованием почему подходит
**10. Wishlist ресторанов → фильтр по контексту**
Список + предпочтения + что уже посетил → фильтр под конкретный контекст (с ребёнком / романтический / деловой), актуальные часы
**11. Темы для изучения → дайджест новостей**
Список интересующих тем → еженедельный дайджест из HN / arxiv / RSS, отфильтрованный от шума под твои конкретные темы
**12. Финансовый watchlist → контекст для решений**
Список активов/инструментов → агрегация сигналов (не трейдинг, а понимание контекста для своих решений)
**13. Проекты и интересы → конференции, семинары, learning events**
Текущие рабочие и личные проекты + домены интереса → поиск конференций, митапов, онлайн-курсов, воркшопов по теме → дайджест "что скоро, что стоит посетить" с приоритизацией по релевантности
**14. Планы поездок × текущее местоположение → акции на билеты и туры**
Wishlist мест + даты отпуска (если есть) + текущий город → поиск распродаж, горящих туров, пакетов (не только авиа) → алерт когда появляется подходящее предложение
**15. Контакты → дни рождения и поводы**
Профили людей с датами рождения + история общения → заблаговременное напоминание + идея подарка по интересам человека
**16. Проекты и интересы → новые идеи, best practices, апдейты инструментов**
Текущий технический стек + активные проекты → мониторинг HN / changelog / блогов → "вышел X, релевантно для твоего проекта Y", "новый паттерн для Z", "есть решение лучше чем то что ты сейчас используешь"
**17. Место проживания → новые заведения и места**
Текущий город + категории интереса (рестораны, кофейни, etc.) → мониторинг новых открытий → периодический дайджест "что открылось, что стоит попробовать"
### Триггеры обогащения
1. **По изменению** — новая запись в списке → автоматически запускает анализ (git diff)
2. **По расписанию** — раз в неделю проходит по спискам, обновляет что устарело
3. **По запросу** — "проведи анализ по этой теме"
---
### Проект 5: Memory Organizer
**Цель:** память агента актуальна, не переполнена, детальные факты живут в vault а не в MEMORY.md.
#### Контекст
Hermes хранит память в двух файлах (`~/.hermes/memories/`):
| Файл | Назначение | Лимит |
|---|---|---|
| `MEMORY.md` | Факты об окружении, проектах, инструментах | ~3000 chars |
| `USER.md` | Профиль пользователя — предпочтения, стиль | ~1375 chars |
Оба инжектируются в system prompt **как frozen snapshot** при старте сессии. Агент видит их как часть контекста.
**Три уровня памяти** (по когнитивной науке, arXiv 2603.07670):
- **Episodic** — сессионные логи (SQLite, session_search). Уже работает.
- **Semantic** — факты/предпочтения (MEMORY.md + USER.md). Нужна curation.
- **Procedural** — навыки и workflows (skills/). Уже работает.
**Текущие проблемы (2026-05-16):**
- MEMORY.md переполнен — 3164 chars при лимите ~3000
- 8 записей про media-pipeline баги/§9.x/транслит — это детальные технические заметки, а не факты для быстрого доступа. Должны жить в `wiki/tech/` или в project notes.
- Нет механизма устаревания — записи про баги давно пофикшенные продолжают занимать место
- Нет связи memory ↔ vault: детальный контекст дублируется, не синергирует
#### Правило разграничения (что куда)
```
MEMORY.md → короткие стабильные факты: SSH хосты, namespace rules,
активные токены, конфиги. Макс ~150 chars на запись.
USER.md → предпочтения, стиль, ожидания. Не меняется часто.
wiki/tech/ → детальные технические заметки: питфолы, баг-паттерны,
разборы архитектур. Длинные, с контекстом.
personal/projects/ → статус проектов, решения, дебаггинг-логи
skills/ → процедуры и workflows пошагово
```
**Overflow pattern:** если запись в MEMORY.md > 150 chars или содержит пошаговые инструкции → переносим в vault, в MEMORY.md оставляем pointer: `media-pipeline питфолы → wiki/tech/media-pipeline.md`
#### Шаги
**Шаг 0 — One-time audit & purge (сейчас)**
1. Пройти по всем записям MEMORY.md
2. Записи про media-pipeline (bugs, §9.x, транслит, KP rate limit, Docker cmd) → создать `wiki/tech/media-pipeline-pitfalls.md`, в MEMORY.md оставить короткий pointer
3. Удалить записи про пофикшенные баги (они уже в истории сессий)
4. Проверить USER.md — убрать устаревшее
5. После: MEMORY.md < 2000 chars, USER.md < 1100 chars (оставить запас для новых фактов)
**Шаг 1 — Создать `wiki/tech/` как хранилище детальных техфактов**
- `wiki/tech/media-pipeline-pitfalls.md` — все §9.x, транслит, баги
- `wiki/tech/kraken-infra.md` — SSH, WireGuard, Docker deploy паттерны
- `wiki/tech/gitea.md` — токены, repos, API endpoints
- Эти страницы живут в wiki (curation воркер их maintainит)
**Шаг 2 — Memory curation cron (еженедельно, воскресенье 04:00)**
```
Читает ~/.hermes/memories/MEMORY.md и USER.md
↓
Для каждой записи:
- Старше 60 дней И не изменялась → кандидат на архивацию
- > 150 chars → кандидат на перенос в vault
- Противоречит другой записи → флажок для review
↓
Детальные записи → переносит в wiki/tech/ (создаёт/обновляет страницы)
В MEMORY.md → заменяет на pointer (1 строка)
Совсем устаревшие (проект завершён) → удаляет
↓
Репортирует: что удалено, что перенесено, текущий % заполненности
```
**Стек:** Hermes cron + terminal + obsidian MCP
**Оценка:** Шаг 0 — 30 мин сейчас. Шаг 1-2 — 1 день.
---
## Статус проектов (2026-05-16)
| Проект | Статус | Следующий шаг |
|---|---|---|
| Проект 1: Vault Enrichment | 🟡 В процессе | Воскресный прогон по топик-картам |
| Проект 2: LLM Wiki Accumulation | ✅ Готов | crystallization + synthesize + inbox в wiki-curation |
| Проект 3: Proactive Research | ✅ Готов | research-queue.md + cron суббота 05:00 |
| Проект 4: Cross-domain Enrichment | ✅ Готов | vault-cross-enrichment cron воскресенье 04:00 |
| Проект 5: Memory Organizer | 🟡 В процессе | daily cron 04:00; wiki/tech/ частично заполнена |
### Что сделано (2026-05-16)
- Task 3b убран из wiki-curation
- frontmatter + aliases + titles на 24 файла documents/
- Enrichment воркер создан (воскресенье 03:00)
- wiki/tech/media-pipeline-pitfalls.md создан
- MEMORY.md разгружена: 105% → 50%
### Известные долги
- ❗ `wiki/tech/` не отражена в `wiki/index.md` и `wiki/SCHEMA.md`
- ❗ `family/index.md` и `personal/index.md` — плоские списки, не топик-карты
- ❗ Memory curation cron не создан (только описан в плане)
---
## Что НЕ нужно делать
- ❌ Task 3b в wiki-curation (убрать) ✅ сделано 2026-05-16
- ❌ Переименовывать файлы с кириллицей/эмодзи
- ❌ Применять Karpathy-wiki к личным спискам (разные задачи)
- ❌ Глубже вкладывать папки
- ❌ Внешние сервисы (LifeOS plugin, Todoist) — у нас есть Asana + Hermes
- ❌ Хранить в MEMORY.md записи > 150 chars — детали → в vault
---
## Ссылки
- [Karpathy LLM Wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
- [LLM Wiki v2 — rohitg00](https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2)
- [claude-obsidian](https://pyshine.com/2026/04/claude-obsidian-self-organizing-ai-knowledge-engine/)
- [Ar9av/obsidian-wiki skills](https://deepwiki.com/Ar9av/obsidian-wiki/3.5-knowledge-building-skills)
- [Nodus Labs knowledge graph](https://support.noduslabs.com/hc/en-us/articles/26724863249180)
- [mathisgauthey vault template](https://github.com/mathisgauthey/obsidian-workflow-template)
- [MOC + Dataview guide](https://github.com/seqis/ObsidianMOC)
---
## Связанные заметки
- [[personal/projects/personal-os/personal-os-architecture|Personal OS Architecture]]
- [[personal/projects/personal-os/executor-security-analysis|Executor Security Analysis]]
@@ -0,0 +1,20 @@
---
title: Research Queue
updated: '2026-10-14'
type: meta
---
# Research Queue
> Topics detected as gaps in the wiki — mentioned in vault but no wiki page.
> Ordered by priority. Completed items move to ## Completed with link + date.
## Queue
(empty)
## Completed
- [x] WireGuard VPN → [[family/how-to/wireguard-vpn]] (2026-05-23)
- [x] Executor Architecture v2 → [[personal/projects/personal-os/executor-orchestrator-redesign]] (2026-05-19)
- [x] Executor Security Incident → [[personal/projects/personal-os/executor-security-analysis]] (2026-05-22)
@@ -0,0 +1,84 @@
---
title: Vault ↔ Agent Integration
created: '2026-05-23'
updated: '2026-05-23'
type: concept
namespace: work
tags: [vault, obsidian, wiki, ingest, mcp, hermes, system, architecture]
sources: [wiki/obsidian-mcp-wrapper.md, wiki/wiki-ingest-process.md, wiki/personal-os-architecture.md, wiki/vault-filling-guide.md]
confidence: high
---
# Vault ↔ Agent Integration
How Eagle, wiki-ingest, and the obsidian-mcp-wrapper work together as a
unified knowledge layer. Three distinct subsystems each own a slice of
the vault.
## The Three Subsystems
### 1. obsidian-mcp-wrapper (runtime read/write)
A Node.js proxy (`~/scripts/obsidian-mcp-wrapper.js`) wraps `obsidian-mcp`
to fix four production bugs: ZodError on init, race condition at gateway
restart, UTF-8 chunk corruption on large payloads, and a 5-second watchdog
for hung child processes.
Eagle reads the vault through this wrapper via MCP tool calls. It can search,
read, and write notes in real time during conversations.
**Allowed write paths** (Eagle only, with prior draft shown):
- `work/projects/`, `work/decisions/`, `personal/`, `family/`
- Never `wiki/` — that's wiki-ingest territory
### 2. wiki-ingest (nightly synthesis, 22:00 launchd)
A `claude -p` session (not Hermes) that runs nightly. It reads files in
`~/obsidian/raw/` (symlinks to external project files), computes SHA256
hashes, and synthesises wiki pages only when the source has changed.
**Invariants:**
- Output is synthesis, never verbatim copy
- Frontmatter `source` + `content_hash` are the ingestion contract
- Pages with `confidence: 1.0` are immutable
### 3. wiki-curation (daily Hermes cron, 02:00)
A Hermes cron job (this script) that maintains the wiki as a compounding
knowledge base: processes inbox, crystallises session knowledge, creates
synthesis pages, lints orphans and broken links.
## Division of Labour
| Layer | Tool | Vault path | Trigger |
|-------|------|-----------|---------|
| Reactive reads/writes | obsidian-mcp-wrapper | `work/`, `personal/`, `family/` | On-demand |
| Source synthesis | wiki-ingest (claude -p) | `wiki/` ← `raw/` | 22:00 nightly |
| Knowledge curation | wiki-curation (Hermes cron) | `wiki/` | 02:00 daily |
| Vault sync | sync-vault.sh | entire vault | Hourly |
## Why obsidian-mcp Is Wrapped
The wrapper exists because `obsidian-mcp` v1.0.6 had four production-breaking
bugs that would have been too fragile to fix upstream (updates would reintroduce
them). A proxy wrapper is cleaner: it intercepts the MCP protocol stream without
modifying the underlying package.
See [[obsidian-mcp-wrapper]] for the four bugs and their fixes.
## Vault Sync (Eagle ↔ Taiga ↔ Kraken)
All three nodes share a sparse vault via a TrueNAS bare git repo. Eagle has
the full vault; Kraken and Taiga have `personal/` and `family/` only (sparse
checkout). The `sync-vault.sh` cron runs hourly on all three.
```
Eagle (full) ──push/pull──┐
Taiga (sparse) ────────────├── mallexxx.duckdns.org:/mnt/RED_2TB/storage/git/obsidian-vault.git
Kraken (sparse) ───────────┘
```
## See Also
[[obsidian-mcp-wrapper]] [[wiki-ingest-process]] [[vault-filling-guide]]
[[personal-os-architecture]]
@@ -0,0 +1,78 @@
---
namespace: work
tags: [system, vault, guide]
last_synced: 2026-04-27
confidence: 1.0
---
# Vault Filling Guide
How to populate `~/obsidian/`. Eagle can write to any section below except `wiki/` and `raw/`.
## Directory Map
```
~/obsidian/
├── wiki/ ← LLM-generated ONLY (wiki-ingest). Never write here manually.
├── raw/ ← Symlinks to external files ONLY. Never write content here.
├── work/ ← Alex's work notes. Eagle can write with confirmation.
│ ├── projects/ One file per active project.
│ ├── decisions/ Architectural/process decisions with date prefix.
│ └── tech-design/ References to designs, review notes.
├── personal/ ← Alex's personal notes. Eagle can write with confirmation.
│ ├── documents/ WHERE docs live (not the docs themselves).
│ ├── instructions/ Personal how-tos and procedures.
│ └── projects/ Personal side projects.
└── family/ ← Household knowledge. Eagle can write with confirmation.
├── how-to/ Practical guides (devices, home equipment, procedures).
├── documents/ WHERE family documents live.
├── contacts/ Emergency contacts, doctors, services.
└── schedule/ Recurring schedules, school, events.
```
## File Naming
- `work/projects/` → `kebab-case-project-name.md` (e.g. `ios-duck-ai-toggle.md`)
- `work/decisions/` → `YYYY-MM-topic.md` (e.g. `2026-04-personal-os-arch.md`)
- `family/how-to/` → `kebab-case-topic.md` (e.g. `truenas-access.md`, `router-reset.md`)
- `family/contacts/` → `emergency.md`, `doctors.md`, `services.md`
- `family/documents/` → `apartment.md`, `insurance.md`, `passports.md` (location pointers, not the files)
## Frontmatter
Every file should have:
```yaml
---
namespace: work | personal | family
tags: [tag1, tag2]
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
```
## What Goes Where
| Info type | Location |
|-----------|----------|
| Active work project status, decisions, links | `work/projects/SLUG.md` |
| "We decided X because Y" (architectural) | `work/decisions/YYYY-MM-TOPIC.md` |
| Home network / NAS / router config | `family/how-to/DEVICE.md` |
| Where passport/insurance/lease is stored | `family/documents/TOPIC.md` |
| Emergency contacts, doctors | `family/contacts/CATEGORY.md` |
| Recurring events, school schedule | `family/schedule/TOPIC.md` |
| Personal project notes | `personal/projects/SLUG.md` |
| Personal procedures (backups, etc.) | `personal/instructions/TOPIC.md` |
## Eagle Write Protocol
1. Show draft content before writing (never silently create)
2. Confirm namespace (`work` / `personal` / `family`)
3. Write the file
4. Run `cd ~/obsidian && git add -A && git commit -m "..."` to save
## What Eagle Should NOT Do
- Write anything to `wiki/` — that's wiki-ingest's job
- Modify `raw/` — those are symlinks managed manually
- Create files without showing the content first
- Overwrite existing files without showing a diff
@@ -0,0 +1,35 @@
---
title: Vault Namespace Rules
created: '2026-05-23'
updated: '2026-10-14'
type: tech
namespace: personal
tags: [vault, meta, conventions]
related:
- "[[vault-filling-guide]]"
---
# Vault Namespace Rules
Rules for where notes live in the Obsidian vault. See also [[personal/projects/personal-os/wiki-schema]] for
full frontmatter conventions.
## Namespace Assignments
- `personal`: Eagle infra, personal projects, dev tooling
- `family`: Kraken media stack, HTPC, Jellyfin, family content
- `work`: DuckDuckGo / DDG tasks and tooling
## Directory Map
```
wiki/concepts/ — how-it-works explanations
wiki/tech/ — infra how-tos, tool configs, pitfalls
wiki/ideas/ — speculative, not yet decided
personal/projects/ — project status & decisions
family/projects/ — family-shared project status
family/how-to/ — family infra procedures
```
Note: this file was reconstructed from a lost pointer. Extend with actual
rules as they emerge.
@@ -0,0 +1,100 @@
---
source: raw/wiki-ingest-prompt.md
content_hash: 29f6a0914d428cf62eeb2a832d6b3048edf3e1d16aa7714c09f686377394d128
namespace: work
last_synced: 2026-04-27
confidence: 0.9
tags: [wiki, ingest, agent, prompt]
---
# Wiki Ingest Process
The agent prompt that maintains `~/obsidian/wiki/` as a synthesised
knowledge base over external project files exposed via symlinks in
`~/obsidian/raw/`. Run locally by `claude -p` (the launchd job
`run-wiki-ingest.sh` at 22:00) — not via API, because file-system
writes require a local Claude Code session. See
[[personal-os-architecture]] for where this fits in the broader system.
## Discovery loop
For every file in `~/obsidian/raw/`:
1. Read the file (skip if the symlink target is missing).
2. Compute SHA256 with `shasum -a 256`.
3. Look for a wiki page whose frontmatter has `source: raw/<filename>`.
4. If a page exists and its `content_hash` already matches, skip.
5. Otherwise enqueue for synthesis.
If nothing changed, the agent prints
"Wiki is up to date. Nothing to ingest." and exits.
## Synthesis rules
- Wiki pages are named by **topic**, not source filename
(e.g. `personal-os-schema.md`, not `schema.md`).
- Output is a **synthesis**, never a verbatim copy. Extract facts,
decisions, and structure. Hard cap of 800 words per page; split
into linked pages if the topic is larger.
- Use `[[double brackets]]` for cross-references between wiki pages.
## Page format
Frontmatter is the source of truth for incremental ingestion:
```yaml
source: raw/<filename>
content_hash: <sha256>
namespace: work
last_synced: <YYYY-MM-DD>
confidence: 0.8
tags: [tag1, tag2]
```
Body has a title, synthesis prose, a `## Key Points` list, and a
`## Related` line of `[[wiki-links]]`.
## Confidence ladder
- **1.0** — reserved for human-written notes in `work/`, `personal/`,
`family/`. The agent must never edit these files.
- **0.9** — highly structured / authoritative source (e.g. a schema).
- **0.8** — clear single source. Default.
- **0.6** — inferred or partial content.
## Hard rules
- Never copy source files verbatim — always synthesise.
- Never edit any file with `confidence: 1.0`.
- Never process files in `namespace: family` unless explicitly told.
- Always update `content_hash` and `last_synced` after writing a page.
- Skip broken symlinks; do not create a wiki page for them.
## Reporting
After the run, the agent emits a summary:
```
Wiki Ingest — <date>
Processed: N files
Created: N new pages
Updated: N pages
Skipped: N (unchanged)
Pages updated:
- wiki/<filename> (source: raw/<source>)
```
## Key Points
- Hash-based incremental: re-runs are cheap when nothing changed.
- Topic-named pages decouple the wiki from source-file naming.
- Frontmatter `source` + `content_hash` is the ingestion contract;
the [[personal-os-schema]] mirrors the same idea in `wiki_pages`.
- Human-edited (confidence 1.0) pages are immutable to the agent —
the trust boundary between synthesis and curated knowledge.
- Local-only execution: writes to `~/obsidian/` need a real FS,
so the job runs under launchd via `claude -p`, not the API.
## Related
[[personal-os-architecture]] [[personal-os-schema]]
@@ -0,0 +1,125 @@
---
title: Wiki Schema
created: '2026-05-13'
updated: '2026-05-25'
type: meta
---
# Wiki Schema
## Domain
Knowledge base covering Alex's Personal OS ecosystem: the multi-agent
productivity/context system, home infrastructure (Eagle Mac M4, Taiga TrueNAS,
Kraken RPi5), personal projects (Reflect app, etc.), and DuckDuckGo work tooling.
**In scope:** agent architecture, data pipelines, home infra, dev tooling,
personal projects, vault management.
**Out of scope:** raw Asana tasks, family documents, ephemeral briefs.
## Conventions
- File names: lowercase, hyphens, no spaces (e.g., `personal-os-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` or `last_synced` date
- Every new page must be added to `index.md` under the correct section
- Every action must be appended to `log.md`
- Subdirectories: `concepts/` for concept/how-it-works pages,
`tech/` for infra/tool how-tos, `comparisons/` for side-by-side analyses,
`entities/` for people/orgs/projects, `queries/` for filed query results
## Frontmatter
Wiki pages synthesised from `raw/`:
```yaml
---
source: raw/<filename>
content_hash: <sha256>
namespace: work | personal | family
last_synced: YYYY-MM-DD
confidence: 0.8
tags: [tag1, tag2]
---
```
Hand-written or agent-synthesised pages:
```yaml
---
title: Human Readable Title
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: concept | entity | comparison | tech | query
namespace: work | personal | family
tags: [from taxonomy below]
sources: [raw/articles/source.md]
confidence: high | medium | low
---
```
**Confidence ladder:**
- `1.0` / `high` — human-written; agent must never edit these files
- `0.9` — highly structured / authoritative source (schema, infra docs)
- `0.8` / `medium` — single clear source; default for agent synthesis
- `0.6` / `low` — inferred or partial content
Pages with `confidence: 1.0` are immutable to the wiki-curation agent.
## Tag Taxonomy
Personal OS:
- `system` `architecture` `agent` `eagle` `executor` `pipeline` `sync`
- `rules` `self-modification` `meta` `purpose`
Work / DDG:
- `asana` `ddg` `workflow` `task-management`
Infrastructure:
- `infra` `kraken` `taiga` `htpc` `docker` `nas` `raspberry-pi` `vps`
- `obsidian` `vault` `wiki` `ingest`
- `media-pipeline` `arr`
Projects:
- `reflect-app` `psychology` `ios` `android` `skip-tools`
- `project` `startup`
Technical:
- `schema` `postgres` `database` `mcp` `hermes`
- `debugging` `pitfalls` `how-to`
Rule: every tag on a page must appear in this taxonomy. Add new tags HERE
before using them. Avoid tag sprawl.
## Page Thresholds
- **Create a page** when an entity/concept appears in 2+ sources OR is
central to one source
- **Add to existing page** when a source mentions something already covered
- **DON'T create a page** for passing mentions or things outside the domain
- **Split a page** when it exceeds ~200 lines
- **Never edit** pages with `confidence: 1.0`
## Update Policy
When new information conflicts with existing content:
1. Check dates — newer sources generally supersede older ones
2. If genuinely contradictory, note both positions with dates
3. Never silently overwrite — show what changed
## Directory Structure
```
wiki/
├── SCHEMA.md ← this file
├── index.md ← page catalog
├── log.md ← action log (append-only)
├── *.md ← root-level pages (legacy + core)
├── concepts/ ← how-it-works, design rationale
├── tech/ ← infra/tool how-tos (device-specific)
├── comparisons/ ← side-by-side analyses
├── entities/ ← people, projects, products
├── queries/ ← filed query results
└── raw/ ← immutable sources
├── inbox/ ← new files to process
└── inbox/processed/ ← after ingestion
```