# API Documentation

Unified execution model for context-aware inference: deterministic assembly of history, memories, records, state, and prompt layers before model invocation.

## Concepts & Architecture

Before diving into the API, it helps to understand the core concepts that power Mnexium's memory system.

Your agent sends a normal API request to Mnexium, along with a few mnx options. Mnexium automatically retrieves conversation history, relevant long-term memory, agent state, and relevant records — and builds an enriched prompt for the model.

The model returns a response, and Mnexium optionally learns from the interaction (memory extraction and structured record extraction). Every step is visible through logs, traces, and recall events so you can debug exactly what happened.

### Who This Is For

Use Mnexium if you're building AI assistants or agents that must remember users across sessions, resume multi-step tasks, and stay configurable per project, user, or conversation. Mnexium combines long-term memories, structured records, and short-term state so your application can handle both personalized context and deterministic data workflows without custom orchestration.

Works with developers using **ChatGPT (OpenAI)**, **Claude (Anthropic)**, and **Gemini (Google)** — bring your own API key and Mnexium handles routing, context assembly, and optional learning. Memories and records are accessible across providers when you keep the same `subject_id`.

### Chat History, Memory, State & Records

Four distinct but complementary systems for context management:

- **Chat History**: The raw conversation log — every message sent and received within a `chat_id`. Used for context continuity within a single conversation session. Think of it as short-term, session-scoped memory.

Enabled with `history: true`

- **Agent Memory**: Extracted facts, preferences, and context about a `subject_id` (user). Persists across all conversations and sessions. Think of it as long-term, user-scoped memory that the agent "remembers" about someone.

Created with `learn: true`, recalled with `recall: true`

- **Agent State**: Short-term, task-scoped working context for agentic workflows. Tracks task progress, pending actions, and session variables. Think of it as the agent's "scratchpad" for multi-step tasks.

Stored with `PUT /state/:key`, loaded with `state.load: true`

- **Records**: Schema-backed structured entities (for example accounts, deals, tickets, tasks). Records are optimized for deterministic retrieval and updates, complementing unstructured memory recall.

Recalled with `records.recall: true`, extracted with `records.learn: "auto"` or "force"

### Message Assembly Order

For chat completions, Mnexium assembles the final messages array in this order:

1. **Resolved System Prompt** — Project → subject → chat scoped prompt (if `system_prompt` is not false)
2. **Agent State** — Current task context as JSON (if `state.load: true`)
3. **Memories** — Relevant facts about the user (if `recall: true`)
4. **Records** — Relevant structured entities from selected schemas (if `records.recall: true`)
5. **Chat History** — Previous messages from this conversation (if `history: true`)
6. **User Messages** — The messages you provide in the request

Items 1-4 are appended to the system message. Item 5 is prepended to the messages array. Item 6 is your original request.

### Memory Fields

Each memory has metadata that helps with organization, recall, and lifecycle management:

- `status`: string `active` (current, will be recalled) or `superseded` (replaced by newer memory, won't be recalled)
- `kind`: string Category: `fact`, `preference`, `context`, or `note`
- `importance`: number 0-100 score affecting recall priority. Higher = more likely to be included in context.
- `visibility`: string `private` (subject only), `shared` (project-wide), or `public`
- `seen_count`: number How many times this memory has been recalled in conversations.
- `last_seen_at`: timestamp When this memory was last recalled.
- `superseded_by`: string If superseded, the ID of the memory that replaced this one.

### Memory Versioning

When new memories are created, the system automatically handles conflicts using semantic similarity. There are only two status values: `active` and `superseded`.

**Skip**: If a new memory is **very similar** to an existing one (same meaning), the new memory is **not created** to avoid redundancy.

Example: "User likes coffee" → "User enjoys coffee" (new one skipped)

**Supersede**: If a new memory **conflicts** with an existing one (same topic, different value), the old memory's status changes to `superseded` and the new one is created as `active`.

Example: "Favorite fruit is blueberry" → "Favorite fruit is apple" (old becomes superseded)

**Create**: If the memory is about a **different topic**, it's stored as a new `active` memory.

Example: "User likes coffee" + "User works remotely" (both remain active)

Superseded memories are preserved for audit purposes and can be restored via the `POST /memories/:id/restore` endpoint. To disable conflict detection entirely (e.g. for bulk imports), pass `no_supersede: true` when creating memories.

### Memory Decay & Reinforcement

Memories naturally decay over time, similar to human memory. Frequently recalled memories become stronger, while unused memories gradually fade in relevance. This ensures the most important and actively-used information surfaces during recall.

- **Confidence**: How certain the AI was when extracting this memory. Higher confidence memories are prioritized during recall.
- **Reinforcement**: Each time a memory is recalled, it gets reinforced — strengthening its relevance and resetting its decay timer.
- **Temporal**: Some memories are time-sensitive (e.g., "User is traveling next week"). These decay faster than permanent facts.
- **Source**: Memories can be `explicit` (created via API), `inferred` (extracted from conversation), or `corrected` (user corrected an inference).

### The Memory Lifecycle

1. **Extract** — LLM analyzes conversation and identifies memorable facts (`learn: true`). Extraction runs **asynchronously** — it never blocks the response.
2. **Store** — Memory is saved with embedding for semantic search
3. **Recall** — Relevant memories are injected into future conversations (`recall: true`)
4. **Reinforce** — Recalled memories get stronger; unused memories naturally decay
5. **Evolve** — Conflicting memories supersede old ones; duplicates are skipped