# `:memory-md` — файловое хранилище памяти (JVM-only)

## Что это

Реализация `MemoryStore` поверх обычных файлов в формате [Hermes-style]:

- `~/.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

## 2026-09-14T10:00:00Z — first session
Имя пользователя — Сережа.
Любит короткие ответы.

## 2026-09-15T18:20:00Z — task preferences
Не присылать пустые репро.
```

Каждая запись начинается с заголовка второго уровня и содержит в
первой строке заголовка timestamp и короткое название. Так достигается
уникальность и читаемость через `cat`.

## Тесты

```
./gradlew :memory-md:jvmTest
```

Покрывают: round-trip save/load, фильтрацию по категории,
keyword-search, перезапись, конкурентный доступ (файловая блокировка).

## Чего здесь НЕТ

- Никаких эмбеддингов. Простой keyword-match (простая substring +
  TF-IDF-эвристика на русских/латинских словах).
- Никакого ANN. Для семантического поиска используйте `:memory-vector`.

## Текущий статус

Используется продакшеном. Подходит для долговременного "дневникового"
хранения.