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