# `:memory-api` — контракт долговременной памяти (KMP, jvm + native)

## Что это

Интерфейсы долговременной памяти агента:

- `MemoryStore` — append-only журнал `MemoryNote(id, content, createdAt)`.
- `MemoryCategory` — discriminator (`USER`, `WORLD`, `PREFERENCE`,
  кастомные).
- `MemoryNote` — структурная единица памяти; immutable.
- Прелоадер / ревьювер по контракту, не по реализации.

Решает: как единая абстракция позволяет иметь одновременно файловую
память (`:memory-md`), SQLite + ANN (`:memory-vector`) и тестовую
in-memory (в `:standalone/tests`). Агент работает с `MemoryStore`,
не с конкретным бэкендом.

## Где используется

- `:memory-md` — Hermes-style `§`-файлы (user.md / world.md /
  preference.md).
- `:memory-vector` — SQLite + JVector + LLM-эмбеддинги.
- `:standalone` подключает обе реализации и переключает через
  `AGENTIK_MEMORY_BACKEND=md|vector|off`.

## Как подключить

```kotlin
kotlin {
    sourceSets.commonMain.dependencies {
        api("pw.binom.agentik:memory-api:0.1.0")
    }
}
```

Артефакт публикуется в `caffeine`.

## Версии

`gradle/libs.versions.toml` → `[versions] agentik-memory-api`.

## Что в API

```kotlin
interface MemoryStore {
    suspend fun save(category: MemoryCategory, content: String): MemoryNote
    suspend fun query(category: MemoryCategory?, q: String, limit: Int = 10): List<MemoryNote>
    suspend fun all(category: MemoryCategory? = null): List<MemoryNote>
}

enum class MemoryCategory(val path: String) {
    USER("user"),
    WORLD("world"),
    PREFERENCE("preference");
}

data class MemoryNote(
    val id: String,
    val category: MemoryCategory,
    val content: String,
    val createdAt: Instant,
)
```

## Тесты

```
./gradlew :memory-api:allTests
```

Контрактные тесты на Kotlin Multiplatform (без jvmTest-специфики).

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

- Никаких конкретных storage — это API. Backend-ы в `:memory-md` и
  `:memory-vector`.

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

Используется продакшеном. Контракт стабильный.