Архітектурні нотатки Obsidian: стек, модель даних, MCP інструменти, деплой, roadmap

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-14 15:09:38 +03:00
parent 7873f0c451
commit 6b8989098a
12 changed files with 331 additions and 0 deletions
@@ -0,0 +1,9 @@
+# Obsidian — локальний стан, не для репозиторію
+.obsidian/workspace.json
+.obsidian/workspace-mobile.json
+.obsidian/cache
+
+# Node.js (фаза 1)
+node_modules/
+dist/
+.env
@@ -0,0 +1 @@
+{}
@@ -0,0 +1 @@
+{}
@@ -0,0 +1,33 @@
+{
+  "file-explorer": true,
+  "global-search": true,
+  "switcher": true,
+  "graph": true,
+  "backlink": true,
+  "canvas": true,
+  "outgoing-link": true,
+  "tag-pane": true,
+  "footnotes": false,
+  "properties": true,
+  "page-preview": true,
+  "daily-notes": true,
+  "templates": true,
+  "note-composer": true,
+  "command-palette": true,
+  "slash-command": false,
+  "editor-status": true,
+  "bookmarks": true,
+  "markdown-importer": false,
+  "zk-prefixer": false,
+  "random-note": false,
+  "outline": true,
+  "word-count": true,
+  "slides": false,
+  "audio-recorder": false,
+  "workspaces": false,
+  "file-recovery": true,
+  "publish": false,
+  "sync": true,
+  "bases": true,
+  "webviewer": false
+}
@@ -0,0 +1,22 @@
+{
+  "collapse-filter": true,
+  "search": "",
+  "showTags": false,
+  "showAttachments": false,
+  "hideUnresolved": false,
+  "showOrphans": true,
+  "collapse-color-groups": true,
+  "colorGroups": [],
+  "collapse-display": true,
+  "showArrow": false,
+  "textFadeMultiplier": 0,
+  "nodeSizeMultiplier": 1,
+  "lineSizeMultiplier": 1,
+  "collapse-forces": true,
+  "centerStrength": 0.518713248970312,
+  "repelStrength": 10,
+  "linkStrength": 1,
+  "linkDistance": 250,
+  "scale": 1,
+  "close": true
+}
@@ -0,0 +1,43 @@
+---
+tags: [архітектура, mcp, api]
+created: 2026-07-14
+---
+
+# MCP інструменти
+
+Транспорт: **Streamable HTTP**. Автентифікація: API-ключ у заголовку (`Authorization: Bearer <key>`).
+
+## Група «Пам'ять»
+
+| Інструмент | Аргументи | Опис |
+|------------|-----------|------|
+| `memory_save` | `type`, `title`, `content`, `projectName?`, `metadata?`, `links?` | Зберігає запис; scope глобальний, якщо проект не вказано |
+| `memory_query` | `query`, `projectName?`, `type?`, `limit?` | Гібридний пошук (фаза 1 — FTS) |
+| `memory_get` | `id` | Повний запис + вихідні/вхідні зв'язки |
+| `memory_update` | `id`, поля для оновлення | Часткове оновлення |
+| `memory_delete` | `id` | Видалення запису та його зв'язків |
+| `memory_link` | `sourceId`, `targetId`, `linkType?` | Створює зв'язок (аналог wiki-посилання) |
+| `memory_graph` | `id`, `depth?` | Обхід графа зв'язків від запису |
+
+## Група «Проекти» (аналог project-agent)
+
+| Інструмент | Аргументи | Опис |
+|------------|-----------|------|
+| `project_list` | — | Список проектів |
+| `project_create` | `projectName`, `summary` | Створення проекту |
+| `project_get_state` | `projectName` | Останній стан сесії + project items |
+| `project_save_state` | `projectName`, `sessionSummary`, `todoJson`, `changes`, `bugs`, `architectureNotes` | Збереження стану сесії |
+
+## Скіли для Claude Code (подібно до наявних)
+
+- `/mem-start` — вибір проекту + відновлення контексту
+- `/mem-save` — збереження стану сесії
+- `/mem-note` — швидке збереження факту/нотатки в пам'ять
+- `/mem-find` — пошук у пам'яті
+
+## Резерв на майбутнє (фаза 2+)
+
+- `memory_embed_backfill` — переіндексація embeddings після підключення Ollama
+- `agent_execute` — делегування задачі локальному виконавцю (Ollama) — див. [[Гібридна схема з Ollama]]
+
+Пов'язане: [[Огляд архітектури]], [[Модель даних]]
@@ -0,0 +1,34 @@
+---
+tags: [план, roadmap]
+created: 2026-07-14
+---
+
+# Roadmap
+
+## Фаза 1 — Сервер пам'яті (поточна)
+
+- [ ] Скелет репозиторію: TypeScript, `@modelcontextprotocol/sdk`, структура src/
+- [ ] Схема БД + міграції ([[Модель даних]])
+- [ ] MCP сервер: Streamable HTTP + API-ключ
+- [ ] Інструменти групи «Пам'ять» (FTS-пошук) ([[MCP інструменти]])
+- [ ] Інструменти групи «Проекти» (аналог project-agent)
+- [ ] Абстракція `EmbeddingProvider` (заглушка `NullEmbeddingProvider`)
+- [ ] Тести (локально, проти dev-БД)
+
+## Фаза 2 — Деплой
+
+- [ ] Датасет `homeLab/portainer/apps/ai-memory-network` ([[Деплой на TrueNAS]])
+- [ ] Portainer stack: ai-memory-server (порт 8767) + ai-memory-db (PostgreSQL 18, `pgvector/pgvector:pg18`)
+- [ ] Ініціалізація бази `ai_memory` + `CREATE EXTENSION vector;`
+- [ ] Підключення Claude Code до endpoint, e2e перевірка
+
+## Фаза 3 — Скіли Claude Code
+
+- [ ] `/mem-start`, `/mem-save`, `/mem-note`, `/mem-find` ([[MCP інструменти]])
+
+## Фаза 4 — Окремий воркфлоу: Ollama (після завершення фаз 1–3)
+
+- [ ] Embeddings `bge-m3` + backfill + гібридний пошук ([[Гібридна схема з Ollama]])
+- [ ] Локальні виконавці (`agent_execute`)
+
+Пов'язане: [[Огляд проекту]]
@@ -0,0 +1,33 @@
+---
+tags: [ollama, embeddings, гібридна-схема, відкладено]
+created: 2026-07-14
+---
+
+# Гібридна схема з Ollama
+
+> [!important] Відкладений воркфлоу
+> Підключення, налаштування та тестування Ollama виконується **окремим воркфлоу ПІСЛЯ завершення реалізації сервера пам'яті**. Ollama розташовано на **іншому сервері** (не TrueNAS).
+
+## Що має реалізувати цей воркфлоу
+
+### 1. Embeddings через Ollama
+- Модель: `bge-m3` (1024 виміри, мультимовна — критично для української)
+- Реалізація `OllamaEmbeddingProvider` за інтерфейсом `EmbeddingProvider` (закладений у фазі 1)
+- Backfill: інструмент `memory_embed_backfill` — переіндексація всіх записів, у яких `embedding IS NULL`
+- Увімкнення гібридного пошуку: FTS + cosine similarity (HNSW-індекс), об'єднання через RRF
+
+### 2. Локальні виконавці (агенти)
+Гібридна схема: **хмарні моделі — диригенти, локальні — виконавці**.
+- Інструмент `agent_execute`: хмарний агент делегує підзадачу локальній моделі через Ollama API
+- Кандидати задач для виконавців: сумаризація записів пам'яті, класифікація/тегування, екстракція фактів із документів, попередня фільтрація результатів пошуку
+- Архітектурно: черга задач + worker у складі ai-memory-server (або окремий контейнер)
+
+### 3. Що з'явиться за потребою
+Схема інструментів та `EmbeddingProvider`/`AgentExecutor` абстракції проєктуються розширюваними — нові можливості додаються без зламу API.
+
+## Передумови (перевірити на старті воркфлоу)
+- [ ] Доступність Ollama API з TrueNAS (мережа, адреса, порт 11434)
+- [ ] Достатньо RAM/VRAM на сервері Ollama для `bge-m3` + моделі-виконавця
+- [ ] `OLLAMA_URL` в env контейнера ai-memory-server
+
+Пов'язане: [[Огляд архітектури]], [[MCP інструменти]], [[Roadmap]]
@@ -0,0 +1,25 @@
+---
+tags: [деплой, truenas, portainer]
+created: 2026-07-14
+---
+
+# Деплой на TrueNAS
+
+Хост: TrueNAS Scale **192.168.0.199**.
+
+## План
+
+1. **Датасет:** `homeLab/portainer/apps/ai-memory-network` (dataset preset = **Apps**) — для конфігів/volumes контейнера.
+2. **Portainer stack** `ai-memory-network` (два сервіси):
+   - контейнер `ai-memory-server` (Node.js 22, образ збирається з репозиторію);
+     порт: HTTP MCP endpoint (напр. `8767`, щоб не конфліктувати з project-agent на `8766`);
+     env: `DATABASE_URL`, `API_KEYS`, `PORT`, пізніше `OLLAMA_URL`;
+   - контейнер `ai-memory-db` — **PostgreSQL 18 як сервіс проекту** (образ `pgvector/pgvector:pg18`, pgvector у комплекті);
+     volume на датасеті проекту; порт назовні не публікуємо (доступ лише всередині stack-мережі).
+3. **БД:** база `ai_memory`, користувач `ai_memory`; `CREATE EXTENSION vector;` — одразу при ініціалізації (embeddings увімкнуться у фазі 2 без змін схеми).
+
+## Відкриті питання
+
+- [ ] Спосіб збирання образу: registry Gitea чи build у Portainer з git-репозиторію
+
+Пов'язане: [[Огляд архітектури]], [[Roadmap]]
@@ -0,0 +1,68 @@
+---
+tags: [архітектура, база-даних, postgresql]
+created: 2026-07-14
+---
+
+# Модель даних
+
+База: `ai_memory` у **PostgreSQL 18, що працює окремим контейнером у stack'у проекту** (образ `pgvector/pgvector:pg18` — розширення pgvector вже в комплекті, лишається `CREATE EXTENSION vector;`). Див. [[Деплой на TrueNAS]].
+
+## Таблиці
+
+### `projects`
+Логіка проектів за аналогією з project-agent.
+
+| Колонка | Тип | Примітка |
+|---------|-----|----------|
+| id | bigserial PK | |
+| name | text UNIQUE | kebab-case |
+| summary | text | опис проекту |
+| status | text | active / archived |
+| metadata | jsonb | розширювані атрибути (repo url тощо) |
+| created_at, updated_at | timestamptz | |
+
+### `memories`
+Універсальні записи пам'яті.
+
+| Колонка | Тип | Примітка |
+|---------|-----|----------|
+| id | bigserial PK | |
+| project_id | bigint FK → projects, NULL | NULL = глобальний scope |
+| type | text | fact / note / session_state / document / entity / … |
+| title | text | |
+| content | text | markdown |
+| content_tsv | tsvector (generated) | FTS-індекс, конфіг simple+ukrainian |
+| embedding | vector(1024), NULL | заповнюється у фазі 2 (bge-m3) |
+| metadata | jsonb | теги, джерело, агент-автор тощо |
+| created_at, updated_at | timestamptz | |
+
+### `memory_links`
+Граф зв'язків — аналог `[[wiki-посилань]]` Obsidian.
+
+| Колонка | Тип | Примітка |
+|---------|-----|----------|
+| source_id | bigint FK → memories | |
+| target_id | bigint FK → memories | |
+| link_type | text | related / parent / derived-from / … |
+| PK | (source_id, target_id, link_type) | |
+
+### `sessions`
+Стан сесій проекту (аналог claude_memory у project-agent).
+
+| Колонка | Тип | Примітка |
+|---------|-----|----------|
+| id | bigserial PK | |
+| project_id | bigint FK → projects | |
+| session_summary | text | |
+| todo_json | jsonb | `{ tasks: [{ task, priority, note }] }` |
+| changes | text | |
+| bugs | text | |
+| architecture_notes | text | |
+| created_at | timestamptz | |
+
+## Пошук
+
+- **Фаза 1:** FTS по `content_tsv` + фільтри (project, type, metadata) + ranking `ts_rank`.
+- **Фаза 2:** гібридний скоринг — cosine similarity (pgvector, HNSW-індекс) + FTS, об'єднання через RRF (Reciprocal Rank Fusion).
+
+Пов'язане: [[Огляд архітектури]], [[MCP інструменти]]
@@ -0,0 +1,40 @@
+---
+tags: [архітектура, mcp]
+created: 2026-07-14
+---
+
+# Огляд архітектури
+
+## Стек
+
+| Компонент | Рішення | Примітка |
+|-----------|---------|----------|
+| Рантайм | Node.js 22 + TypeScript | однорідно з наявним project-agent |
+| MCP SDK | `@modelcontextprotocol/sdk` | Streamable HTTP транспорт з коробки |
+| БД | **PostgreSQL 18 + pgvector — окремий контейнер у stack'у проекту** | образ `pgvector/pgvector:pg18`; база `ai_memory` |
+| Пошук | гібридний: FTS (фаза 1) → FTS + vector (фаза 2) | embeddings відкладені до підключення Ollama |
+| Embeddings | Ollama + `bge-m3` (1024 вим.) | окремий сервер, окремий воркфлоу — [[Гібридна схема з Ollama]] |
+| Хостинг | TrueNAS + Portainer | [[Деплой на TrueNAS]] |
+| Автентифікація | API-ключ у заголовку | єдиний механізм для всіх клієнтів |
+
+## Ключові принципи
+
+1. **Логіка проектів** — сервер підтримує проекти за аналогією з наявним `project-agent`: список проектів, стан сесій (summary, todo, changes, bugs, architecture notes) + подібний набір скілів для Claude Code.
+2. **Пам'ять як граф** — записи пов'язані між собою (`memory_links`), що віддзеркалює `[[wiki-посилання]]` Obsidian: логіка сховища і логіка БД збігаються.
+3. **Розширюваність** — схема інструментів покриває поточні потреби і не блокує майбутні (виконавці на локальних моделях, нові типи пам'яті).
+4. **Відкладені embeddings** — абстракція `EmbeddingProvider`: фаза 1 працює без векторів (FTS-only, колонка `embedding` = NULL), фаза 2 додає Ollama і backfill без зміни API.
+
+## Компоненти
+
+```
+Claude Code / інші ШІ-клієнти
+        │  MCP Streamable HTTP (+ API key)
+        ▼
+ai-memory-server (Node.js, контейнер у Portainer)
+        │                          │
+        ▼                          ▼ (фаза 2)
+PostgreSQL 18 + pgvector      Ollama (окремий сервер)
+(контейнер у тому ж stack'у)  embeddings + локальні виконавці
+```
+
+Пов'язане: [[Модель даних]], [[MCP інструменти]], [[Roadmap]]
@@ -0,0 +1,22 @@
+---
+tags: [проект, mcp, огляд]
+created: 2026-07-14
+---
+
+# ai-memory-network-mcp-server
+
+Мережевий сервер "пам'яті" (MCP) для використання будь-яким застосунком чи ШІ-агентом. Переважне використання — Claude Code, з можливістю інтеграції з іншими ШІ-застосунками та екосистемою локальних моделей (Ollama) у гібридній схемі: **хмарні моделі — диригенти, локальні — виконавці**.
+
+## Нотатки проекту
+
+- [[Огляд архітектури]] — стек, компоненти, ключові рішення
+- [[Модель даних]] — схема БД (PostgreSQL 18 + pgvector)
+- [[MCP інструменти]] — схема інструментів сервера
+- [[Деплой на TrueNAS]] — Portainer stack, датасети, підключення до БД
+- [[Гібридна схема з Ollama]] — відкладений воркфлоу (після реалізації сервера)
+- [[Roadmap]] — фази реалізації
+
+## Посилання
+
+- Gitea repo: http://192.168.0.199:30008/sages/ai-memory-network-mcp-server
+- Стан сесій розробки ведеться через MCP `project-agent` (`save_session_state` / `get_latest_session_state`)