# :memory-api — `pw.binom.agentik.memory`

**Интерфейсы долговременной памяти агента: `MemoryStore`, `MemoryNote`,
`MemoryCategory`, `MemoryPrefetcher`, `MemoryReviewer`, `MemoryTools`.**
Без зависимостей от конкретного хранилища.

## Какую проблему решает

LLM не помнит между сессиями. Чтобы агент становился **умнее с каждым
диалогом**, нужна долговременная память: факты о пользователе, мире,
предпочтениях, плюс механизм извлечения (reviewer) и подмешивания (prefetcher)
в контекст. Бэкенды памяти бывают разные (md-файлы, векторный ANN, sqlite,
KV-store), и `:standalone` не должен быть привязан ни к одному из них.

`:memory-api` определяет **контракт**: что умеет любая реализация памяти.
Конкретные бэкенды — `:memory-md` (Hermes-style §-файлы) и `:memory-vector`
(SQLite + JVector + эмбеддинги).

## Что в контракте

```kotlin
interface MemoryStore : AutoCloseable {
    suspend fun upsert(note: MemoryNote)
    suspend fun get(id: String): MemoryNote?
    suspend fun list(category: MemoryCategory?, conversationId: String?, limit, offset): List<MemoryNote>
    suspend fun search(query: MemorySearchQuery): List<MemorySearchResult>
    suspend fun delete(id: String): Boolean
    suspend fun markUsed(ids: List<String>)              // бампит lastUsedAt + useCount
    fun events(): Flow<MemoryStoreEvent>                 // опционально
}

enum class MemoryCategory { USER, WORLD, PREFERENCE }

data class MemoryNote(
    val id: String,
    val conversationId: String?,
    val category: MemoryCategory,
    val title: String,
    val body: String,
    val source: MemorySource,                            // AUTO_REVIEW / USER / MANUAL
    val createdAt: Instant,
    val lastUsedAt: Instant?,
    val useCount: Int,
)
```

`MemoryPrefetcher` — компонент, который **перед** каждым user-ходом выбирает
релевантные заметки (через `search()`) и форматирует `[Memory context…]` блок
в начало user-сообщения. `MemoryReviewer` — компонент, который **после**
assistant-хода извлекает новые факты (через LiteLlm) и вызывает `upsert`.
`MemoryTools` — `memory_save` / `memory_recall` / `memory_list` / `memory_delete`,
которыми модель может пользоваться явно.

## Подключение

```kotlin
commonMain {
    implementation("pw.binom.agentik:memory-api:$version")
    // + выберите реализацию:
    implementation("pw.binom.agentik:memory-md:$version")          // md-файлы
    // или
    implementation("pw.binom.agentik:memory-vector:$version")      // JVector+SQLite
}
```

## Где смотреть версии

- `version` из `gradle.properties` (`version=0.1.0`)
- релизы: `https://git.binom.pw/subochev/agentik/releases`

## Сборка

```bash
./gradlew :memory-api:build
```

KMP-таргеты — полный набор. Зависимостей нет (только `kotlinx-coroutines-core` для `Flow`).