# Agents Database memory contract

This repo uses `agents-database` as the canonical memory store.

## Canonical behavior

- `MemoryService` / `MemoryEngine` own the memory pipeline.
- `ingest()` writes memory records.
- `capture_session()` and `capture_conversation()` create raw source material.
- `process_pending()` extracts episode memories from pending ingestion events.
- `consolidate_candidates(config)` performs dedup, conflict detection, promotion, and optional synthesis.
- `maintenance_jobs` and `maintenance_runs` schedule and audit periodic consolidation.
- `episode` and `inbox` records are candidates, not truth, until consolidated or explicitly promoted.
- `memory_conflicts` and `memory_links` are the right place for contradiction and relation semantics.

## Pi-side rule

`pi-config` may:

- capture session context
- queue analyzer jobs
- ask for promotion candidates
- emit inspection reports

`pi-config` should not:

- reimplement the canonical consolidation pipeline
- invent a parallel truth store
- silently promote memories outside the shared DB contracts