# Memory, Sessions, And Context

## Endpoint Summary

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/memory` | Memory backend summary |
| `POST` | `/v1/memory/search` | Search memory |
| `POST` | `/v1/memory/write` | Write memory |
| `GET` | `/v1/memory/episodes` | List episodes |
| `GET` | `/v1/memory/failures` | List captured failures |
| `POST` | `/v1/memory/ingest` | Ingest content or files |
| `GET` | `/v1/memory/entities` | List extracted entities |
| `POST` | `/v1/memory/jobs/run` | Run a named maintenance job |
| `POST` | `/v1/memory/feedback` | Record memory relevance/quality feedback |
| `POST` | `/v1/memory/speaker-identities/enroll` | Admin-only explicit-consent speaker enrollment |
| `POST` | `/v1/memory/speaker-identities/match` | Admin-only exact-space speaker candidate matching |
| `GET` | `/v1/sessions` | List Omnius task sessions |
| `GET` | `/v1/sessions/{id}` | Get session history |
| `GET` | `/v1/context` | Show current session context |
| `GET` | `/v1/context/window-dumps` | List outbound model context-window dumps |
| `GET` | `/v1/context/window-dumps/{id}` | Fetch a full outbound model context-window dump |
| `POST` | `/v1/context/save` | Save a context entry |
| `GET` | `/v1/context/restore` | Build a restore prompt |
| `POST` | `/v1/context/compact` | Request context compaction |

## Memory Search

Use memory search for persistent knowledge, failures, prior decisions, and scoped context. Public connector surfaces such as Telegram should keep scope explicit so one chat does not pollute another.

## Memory Write

Memory writes require run or admin scope where enforced. Prefer structured, scoped writes over dumping entire transcripts.

## Failures

Failure records let the agent learn from raw observed outputs. The design goal is to pass failure output through as evidence, not convert platform-specific strings into hardcoded policy shortcuts.

## Durable Speaker Identity

Speaker identity is a separate, consent-gated biometric store. It is not part
of general memory search and never compares text, image, acoustic, or semantic
audio vectors with speaker vectors. Both routes require an admin-scoped key.

Enroll only an already-persisted `speaker_identity_embedding` observation with
an explicit self-identification assertion. The vector-space contract must name
the exact embedding set, model, revision, digest, dimensions, and `l2`
normalization. A sender account, uploader, transcript, or session-local
diarization cluster is never consent or biometric proof, and enrollment creates
no `voice_sample_of`, `named_as`, or other graph identity edge.

```json
POST /v1/memory/speaker-identities/enroll
{
  "scope_id": "project:demo",
  "identity": "Alex Example",
  "observation_id": "obs_…",
  "consent": {
    "basis": "explicit_self_identification",
    "asserted_by": "admin:operator-1"
  },
  "space": {
    "embedding_set_slug": "speaker-identity-wespeaker-…-l2",
    "model": "wespeaker-voxceleb-campplus",
    "model_revision": "acf623ad8ca746e50baa432255cf8fc57c669c45",
    "model_digest": "sha256:…",
    "dimensions": 512,
    "normalization": "l2"
  }
}
```

The store retains exemplar IDs and a normalized centroid internally. It does
not return stored vectors. To query, supply an L2-normalized vector with the
same exact contract:

```json
POST /v1/memory/speaker-identities/match
{
  "scope_id": "project:demo",
  "vector": [/* exact speaker vector */],
  "dimensions": 512,
  "space": { "embedding_set_slug": "…", "model": "…", "model_revision": "…", "model_digest": "…", "normalization": "l2" }
}
```

Responses are `provisional`, `ambiguous`, or `no_match`; none creates a
durable identity assignment. Session/file-local diarization labels remain
session-local even if a candidate is returned.

## Context

Context endpoints expose the TUI context stack:

- `GET /v1/context`: current context snapshot.
- `GET /v1/context/window-dumps`: list persisted outbound prompt/tool payload summaries with signal/noise metrics.
- `GET /v1/context/window-dumps/{id}`: fetch a full context-window dump; use `latest` for the newest dump.
- `POST /v1/context/save`: persist a context entry.
- `GET /v1/context/restore`: build a restore prompt.
- `POST /v1/context/compact`: request compaction.

Context-window dumps cover main agents, sub-agents, internal runners, and adversary audits. Use `agent_type`, `session_id`, `limit`, and `include_request=1` query parameters to narrow list output. Set `OMNIUS_CONTEXT_WINDOW_DUMP_DIR` to relocate dumps, or `OMNIUS_DISABLE_CONTEXT_WINDOW_DUMPS=1` to disable them.

## Sessions

Session endpoints expose archived task turns, which can be used by dashboards, replay tooling, or state restoration.