# 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:

1. **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`

2. **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`

3. **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`

4. **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.

- **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`.

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

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