From 6b8989098ad1d40e5851e008133ffb6d49caa044 Mon Sep 17 00:00:00 2001 From: sages-ds Date: Tue, 14 Jul 2026 15:09:38 +0300 Subject: [PATCH] =?UTF-8?q?=D0=90=D1=80=D1=85=D1=96=D1=82=D0=B5=D0=BA?= =?UTF-8?q?=D1=82=D1=83=D1=80=D0=BD=D1=96=20=D0=BD=D0=BE=D1=82=D0=B0=D1=82?= =?UTF-8?q?=D0=BA=D0=B8=20Obsidian:=20=D1=81=D1=82=D0=B5=D0=BA,=20=D0=BC?= =?UTF-8?q?=D0=BE=D0=B4=D0=B5=D0=BB=D1=8C=20=D0=B4=D0=B0=D0=BD=D0=B8=D1=85?= =?UTF-8?q?,=20MCP=20=D1=96=D0=BD=D1=81=D1=82=D1=80=D1=83=D0=BC=D0=B5?= =?UTF-8?q?=D0=BD=D1=82=D0=B8,=20=D0=B4=D0=B5=D0=BF=D0=BB=D0=BE=D0=B9,=20r?= =?UTF-8?q?oadmap?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- .gitignore | 9 +++++ .obsidian/app.json | 1 + .obsidian/appearance.json | 1 + .obsidian/core-plugins.json | 33 ++++++++++++++++++ .obsidian/graph.json | 22 ++++++++++++ MCP інструменти.md | 43 +++++++++++++++++++++++ Roadmap.md | 34 +++++++++++++++++++ Гібридна схема з Ollama.md | 33 ++++++++++++++++++ Деплой на TrueNAS.md | 25 ++++++++++++++ Модель даних.md | 68 +++++++++++++++++++++++++++++++++++++ Огляд архітектури.md | 40 ++++++++++++++++++++++ Огляд проекту.md | 22 ++++++++++++ 12 files changed, 331 insertions(+) create mode 100644 .gitignore create mode 100644 .obsidian/app.json create mode 100644 .obsidian/appearance.json create mode 100644 .obsidian/core-plugins.json create mode 100644 .obsidian/graph.json create mode 100644 MCP інструменти.md create mode 100644 Roadmap.md create mode 100644 Гібридна схема з Ollama.md create mode 100644 Деплой на TrueNAS.md create mode 100644 Модель даних.md create mode 100644 Огляд архітектури.md create mode 100644 Огляд проекту.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f7ec524 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +# Obsidian — локальний стан, не для репозиторію +.obsidian/workspace.json +.obsidian/workspace-mobile.json +.obsidian/cache + +# Node.js (фаза 1) +node_modules/ +dist/ +.env diff --git a/.obsidian/app.json b/.obsidian/app.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/.obsidian/app.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/.obsidian/appearance.json b/.obsidian/appearance.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/.obsidian/appearance.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/.obsidian/core-plugins.json b/.obsidian/core-plugins.json new file mode 100644 index 0000000..639b90d --- /dev/null +++ b/.obsidian/core-plugins.json @@ -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 +} \ No newline at end of file diff --git a/.obsidian/graph.json b/.obsidian/graph.json new file mode 100644 index 0000000..42a46ec --- /dev/null +++ b/.obsidian/graph.json @@ -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 +} \ No newline at end of file diff --git a/MCP інструменти.md b/MCP інструменти.md new file mode 100644 index 0000000..265f80a --- /dev/null +++ b/MCP інструменти.md @@ -0,0 +1,43 @@ +--- +tags: [архітектура, mcp, api] +created: 2026-07-14 +--- + +# MCP інструменти + +Транспорт: **Streamable HTTP**. Автентифікація: API-ключ у заголовку (`Authorization: Bearer `). + +## Група «Пам'ять» + +| Інструмент | Аргументи | Опис | +|------------|-----------|------| +| `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]] + +Пов'язане: [[Огляд архітектури]], [[Модель даних]] diff --git a/Roadmap.md b/Roadmap.md new file mode 100644 index 0000000..ff05df1 --- /dev/null +++ b/Roadmap.md @@ -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`) + +Пов'язане: [[Огляд проекту]] diff --git a/Гібридна схема з Ollama.md b/Гібридна схема з Ollama.md new file mode 100644 index 0000000..874aae0 --- /dev/null +++ b/Гібридна схема з Ollama.md @@ -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]] diff --git a/Деплой на TrueNAS.md b/Деплой на TrueNAS.md new file mode 100644 index 0000000..74a3279 --- /dev/null +++ b/Деплой на TrueNAS.md @@ -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]] diff --git a/Модель даних.md b/Модель даних.md new file mode 100644 index 0000000..cbe67c8 --- /dev/null +++ b/Модель даних.md @@ -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 інструменти]] diff --git a/Огляд архітектури.md b/Огляд архітектури.md new file mode 100644 index 0000000..77a64c6 --- /dev/null +++ b/Огляд архітектури.md @@ -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]] diff --git a/Огляд проекту.md b/Огляд проекту.md new file mode 100644 index 0000000..4f81c62 --- /dev/null +++ b/Огляд проекту.md @@ -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`)