docs: per-module READMEs (run vs library) + root navigation hub
ci / JVM build + tests (pull_request) Failing after 54s

Every subproject now has README.md:
- 3 runnable modules (:standalone, :agentik-cli, :agentik-tui):
  quickstart, env table, parameters, known limits
- 11 library modules: what it is, which problem solves, how to
  wire it in, where versions live

Root README.md is the navigation hub (Quickstart, Modules table,
publish + CI/CD notes).

Also: ci.yml prunes the :memory-vector -x excludes now that
text-embedding-kmp artifacts are published to caffeine.

518 tests green.

Verified publish pipeline: :proto:publish to caffeine produces
pom.module + per-target klibs + sources for all 9 KMP targets.

🤖 Generated with [opencode]
This commit is contained in:
SubochevAV
2026-09-16 20:44:16 +03:00
parent 5ad972767d
commit 8f616f359f
22 changed files with 1125 additions and 890 deletions
+58 -44
View File
@@ -1,63 +1,77 @@
# :memory-md — `pw.binom.agentik.memory.md`
# `:memory-md` — файловое хранилище памяти (JVM-only)
**Hermes-style реализация долговременной памяти поверх обычных markdown-файлов.**
По одной §-секции на заметку, в файлах `user.md` / `world.md` / `preference.md`.
Без внешних зависимостей, без эмбеддингов, без БД.
## Что это
## Какую проблему решает
Реализация `MemoryStore` поверх обычных файлов в формате [Hermes-style]:
Минимально работающая память **без инфраструктуры**: открыл текстовый редактор —
посмотрел, поправил, удалил. Версионируется в git вместе с проектом, бэкапится
как обычные файлы. Полезно для дев-окружения, для одиночных пользователей,
для отладки vector-бэкенда.
- `~/.agentik/memory/user.md`
- `~/.agentik/memory/world.md`
- `~/.agentik/memory/preference.md`
## Формат файла
Каждая секция — это `## <heading>` + содержимое. Ревьювер ищет
по заголовкам/словам по ключевому совпадению. Префетчер лениво
подгружает секции, наиболее вероятно относящиеся к текущему ходу.
Решает: простой, прозрачный, git-дружелюбный формат памяти.
Пользователь может сам `cat ~/.agentik/memory/world.md` и
отредактировать.
## Где используется
- `:standalone` подключает вместо `:memory-vector` когда
`AGENTIK_MEMORY_BACKEND=md`.
- Дефолт, когда ANN-эмбеддинги слишком дороги или не нужны.
## Как подключить
```kotlin
dependencies {
implementation("pw.binom.agentik:memory-md:0.1.0")
implementation("pw.binom.agentik:memory-api:0.1.0") // контракт
}
val memory: MemoryStore = openMdMemorySystem(Path("~/.agentik/memory"))
memory.save(MemoryCategory.USER, "User prefers tasks short.")
memory.query(MemoryCategory.USER, "preferences").forEach(::println)
```
## Версии
`gradle/libs.versions.toml` → `[versions] agentik-memory-md`.
## Как устроен формат
```markdown
# user.md
# agentik-note id=a3f1e2b7 created=2026-09-01 uses=3 last=2026-09-12
Пользователь предпочитает короткие ответы без эмодзи. Не любит вим.
## 2026-09-14T10:00:00Z — first session
Имя пользователя — Сережа.
Любит короткие ответы.
# agentik-note id=b9c4d8e1 created=2026-09-10 uses=1 last=2026-09-12
Дедлайн релиза agentik — 25 сентября.
# preference.md
# agentik-note id=c1d2e3f4 created=2026-09-08 uses=0 last=never
Отвечать по-русски, без жаргона.
## 2026-09-15T18:20:00Z — task preferences
Не присылать пустые репро.
```
Заголовок с метаданными (`# agentik-note id=… created=… uses=… last=…`), пустая
строка, markdown-body. Curator (фоновая корутина) переименовывает «протухшие»
заметки (`useCount=0` и `last > 90 дней назад`) в `.archived.{ts}`.
Каждая запись начинается с заголовка второго уровня и содержит в
первой строке заголовка timestamp и короткое название. Так достигается
уникальность и читаемость через `cat`.
## Подключение
## Тесты
```kotlin
commonMain {
implementation("pw.binom.agentik:memory-md:$version")
// транзитивно: :memory-api + kaml (для YAML-сериализации метаданных)
}
// Использование
val store = MemoryMdStore.fromDirectory(
dir = Path("~/.agentik/memory"),
clock = Clock.System,
)
val search = store.search(MemorySearchQuery(query = "любимый редактор", limit = 5))
```
./gradlew :memory-md:jvmTest
```
## Где смотреть версии
Покрывают: round-trip save/load, фильтрацию по категории,
keyword-search, перезапись, конкурентный доступ (файловая блокировка).
- `version` из `gradle.properties` (`version=0.1.0`)
- релизы: `https://git.binom.pw/subochev/agentik/releases`
## Чего здесь НЕТ
## Сборка
- Никаких эмбеддингов. Простой keyword-match (простая substring +
TF-IDF-эвристика на русских/латинских словах).
- Никакого ANN. Для семантического поиска используйте `:memory-vector`.
```bash
./gradlew :memory-md:build
```
## Текущий статус
KMP-таргеты — полный набор. Зависимости — `:memory-api` + `kaml` (YAML-парсинг
метаданных).
Используется продакшеном. Подходит для долговременного "дневникового"
хранения.