---
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]]