docs: per-module README + root navigation hub + CI/release workflows

- README.md в каждом подмодуле: для библиотек — описание проблемы, подключение через maven-central/caffeine, версии в gradle/libs.versions.toml. Для запускаемых модулей — команды запуска + переменные среды с дефолтами. - Корневой README.md переписан как навигационный хаб: что это, где клиенты, где серверы, как собрать, как опубликовать. - build.gradle.kts: per-module POM-description через единую карту в rootProject.extra (порядок важен — нужно ДО apply плагина KMP, поэтому beforeEvaluate в subprojects). - .gitea/workflows/ci.yml (новый): build + jvmTest + shadowJar на PR/push main. - .gitea/workflows/release.yml (обновлён): публикует библиотеки в caffeine Nexus + собирает 3 fatjar'а и крепит их к release как бинарные ассеты.
2026-09-16 16:24:03 +03:00
parent e68db11aaa
commit 0fdc12695e
18 changed files with 1279 additions and 364 deletions
@@ -0,0 +1,72 @@
+# :memory-vector — `pw.binom.agentik.memory.vector`
+
+**Реализация долговременной памяти поверх JVector (ANN-индекс) + SQLite (метаданные) + эмбеддингов.**
+JVM-only (JVector не публикует KMP-таргеты; на Android ART работает через Java 11
+scalar fallback).
+
+## Какую проблему решает
+
+`:memory-md` хорош для малых объёмов и дев-окружения, но при тысячах заметок
+keyword-overlap поиск не справляется. Vector-бэкенд считает **эмбеддинги**
+заметок, складывает в JVector ANN-индекс, ищет по cosine similarity.
+`recency-re-rank` подмешивает свежесть, чтобы новые факты не тонули в старых.
+
+## Архитектура
+
+```
+                ┌───────────────────────┐
+   user-query ─►│  EmbeddingProvider    │ (HTTP /v1/embeddings или SIGLIP2 on-device)
+                └─────────┬─────────────┘
+                          ▼
+                ┌───────────────────────┐
+                │  MemoryVectorStore     │
+                │  ├─ JVector (cosine)   │ ◄── ANN-search
+                │  └─ SQLite (мета)      │ ◄── заметки + lastUsedAt + useCount
+                └───────────────────────┘
+```
+
+Бэкенды эмбеддингов (через `AGENTIK_EMBEDDING_BACKEND`):
+
+- **`HTTP`** — POST на `${OPENAI_BASE_URL}/v1/embeddings`. Семантический поиск
+  через OpenAI-совместимый endpoint (vLLM, OpenAI, LiteLLM-proxy).
+  Кэширование LRU(256) на уровне `EmbeddingHttpProvider` для дедупликации.
+- **`SIGLIP`** — on-device SigLIP2 через ONNX Runtime (768-мерный вектор).
+  Никаких внешних вызовов; модель и токенизатор должны лежать на диске.
+
+## Подключение
+
+```kotlin
+plugins { kotlin("jvm") }
+
+dependencies {
+    implementation("pw.binom.agentik:memory-vector:$version")
+    // Транзитивно: :memory-api + jvector + sqldelight + text-embedding-kmp
+}
+```
+
+`:standalone` инициализирует бэкенд автоматически по `AGENTIK_MEMORY_BACKEND=vector`
+ `AGENTIK_EMBEDDING_BACKEND=…`.
+
+## Размерности
+
+| Backend | Модель | Dim |
+|---|---|---|
+| `HTTP` (OpenAI) | `text-embedding-3-small` (default) | 1536 |
+| `HTTP` (OpenAI) | `text-embedding-3-large` | 3072 |
+| `SIGLIP` | SigLIP2-base | 768 (фиксировано) |
+
+Для `HTTP` размерность управляется через `AGENTIK_EMBEDDING_DIMENSION`; для
+`SIGLIP` — определяется автоматически.
+
+## Где смотреть версии
+
+- `version` из `gradle.properties` (`version=0.1.0`)
+- релизы: `https://git.binom.pw/subochev/agentik/releases`
+
+## Сборка
+
+```bash
+./gradlew :memory-vector:build
+```
+
+JVM-only. Тянет `pw.binom.agentik:memory-api` и `com.github.jvector:jvector:3.0.6`.