Архітектурні нотатки 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`)