API Documentation

Node SDK Python SDK Download Skill

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:

1Resolved System Prompt — Project → subject → chat scoped prompt (if system_prompt is not false)

2Agent State — Current task context as JSON (if state.load: true)

3Memories — Relevant facts about the user (if recall: true)

4Records — Relevant structured entities from selected schemas (if records.recall: true)

5Chat History — Previous messages from this conversation (if history: true)

6User 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

1Extract — LLM analyzes conversation and identifies memorable facts (learn: true). Extraction runs asynchronously — it never blocks the response.

2Store — Memory is saved with embedding for semantic search

3Recall — Relevant memories are injected into future conversations (recall: true)

4Reinforce — Recalled memories get stronger; unused memories naturally decay

5Evolve — Conflicting memories supersede old ones; duplicates are skipped