How xmemory works

xmemory is a memory interface with natural-language inputs and outputs, backed by schema under the hood.

That means your agents can write memory in plain text and read memory in plain text, while xmemory still stores information in a structured, governed form. Instead of treating memory as loose context alone, xmemory lets you define what should be remembered, how it should be represented, and what kinds of questions the system needs to answer reliably later.

The schema question

To use xmemory, you first create a memory instance and define the schema for it.

That schema can come from:

an existing project or system of record
a manual definition you write yourself
the xmemory schema generation tool

The schema generation tool is useful when you know the kind of information you want to store, but you do not want to design the schema from scratch. In that case, you describe in detail:

what information the agent will store
what objects, events, or entities matter
what typical questions you expect to ask memory afterwards

From that, xmemory can generate a schema designed for the workflow you are building.

Example schema generation request

Generate a very simple and short xmemory schema for tracking shared office
expenses between colleagues.

It should let us store colleagues, expense records, and debts/obligations so
we can see who owes whom, how much, currency, and what the expense was for.

Include short text fields for names and descriptions, an amount field, a
currency field, a date field for when the expense happened, and relations
linking payer, debtor, and optional related expense.

Example schema in YAML

description: Schema for tracking shared office expenses, who paid, and who owes whom.
objects:
  colleague:
    description: A person participating in shared office expenses.
    fields:
      name:
        description: Full name of the colleague.
        enum: null
        required: true
        type: str
    keys: null
  debt:
    description: A debt or financial obligation between two colleagues.
    fields:
      amount:
        description: Amount owed.
        enum: null
        required: false
        type: float
      currency:
        description: Currency of the debt.
        enum: null
        required: false
        type: str
      note:
        description: Optional note or reason for the debt.
        enum: null
        required: false
        type: str
    keys: null
  expense:
    description: A shared office expense record.
    fields:
      amount:
        description: Total monetary amount of the expense.
        enum: null
        required: false
        type: float
      currency:
        description: Currency code for the expense (e.g. USD, EUR).
        enum: null
        required: false
        type: str
      date:
        description: Date the expense occurred (YYYY-MM-DD).
        enum: null
        required: false
        type: str
      description:
        description: Optional details about what the expense was for.
        enum: null
        required: false
        type: str
      title:
        description: Short label identifying the expense.
        enum: null
        required: true
        type: str
    keys: null
relations:
  debt_record:
    description: Links a debt to the colleague who paid (payer), the colleague who owes (debtor), and optionally the related expense.
    keys:
      primary:
      - debt
    objects:
      debt:
        description: null
        on_delete: cascade
        type: debt
      debtor:
        description: null
        on_delete: cascade
        type: colleague
      expense:
        description: null
        on_delete: nullify
        type: expense
      payer:
        description: null
        on_delete: cascade
        type: colleague
  expense_payer:
    description: Links an expense to the colleague who paid for it.
    keys:
      primary:
      - expense
    objects:
      expense:
        description: null
        on_delete: cascade
        type: expense
      payer:
        description: null
        on_delete: cascade
        type: colleague
title: Office Expense Tracker

Create the memory instance

Once you have the schema, you can use it to create a memory instance.

That instance becomes the memory interface your agent or workflow talks to. From there, the interaction model is simple:

write memory using free-form text requests
read memory by asking questions or describing the data you want to retrieve

In practice, this gives you a memory layer that feels conversational from the outside, but stays structured and queryable underneath.

Sync and async writes

xmemory supports both synchronous and asynchronous writes.

For most production use cases, we strongly recommend asynchronous writes unless you need to read the written data back immediately.

In many workflows, especially conversational ones, the system does not need to pause and verify exactly what was saved before continuing. A chat assistant can often keep the conversation moving while memory is written in the background.

That is why async writes are usually the better default:

lower latency in the user-facing flow
less blocking inside agent loops
easier integration when memory capture does not need to affect the next response immediately

A good example is chat memory. In most chat scenarios, you do not need to inspect the saved memory right away. The system can continue the conversation without waiting to confirm exactly what was stored.

The main exception is form-filling chats or other guided flows where the agent must know what information is still missing before asking the next question. In those cases, synchronous writes are often the better choice because the system benefits from having the updated memory state immediately available.

Typical usage flow

The usual xmemory flow looks like this:

Define or generate a schema.
Create a memory instance from that schema.
Send natural-language writes into xmemory.
Ask natural-language read queries when the agent needs to recover facts, state, or context.

This makes it easy to plug xmemory into agent loops, workflow engines, or multi-agent systems without forcing every integration to work directly with raw structured storage.

Good examples

Chat memory

One common pattern is chat memory.

Important user messages can be sent to xmemory for memorization inside a customer profile schema. That gives the system a durable and structured representation of preferences, facts, identity, goals, and other relevant information that should survive beyond a single conversation.

Agentic working memory

Another strong fit is agentic working memory.

Agents can create schemas and memory instances on the fly to save:

execution steps
task artefacts
state
tool knowledge
intermediate facts
shared knowledge across collaborating agents

This is especially useful in multi-agent systems where several agents need to coordinate around shared state and durable task knowledge.

Integration guides

To integrate xmemory into your workflows, start with one of the guides below.

Manual integrations

MCP - Expose xmemory to agents as tools through the Model Context Protocol.
API - Connect xmemory to your workflows, apps, or UIs over HTTP.
Python - Use xmemory directly inside Python codebases and backend workflows.
TypeScript - Use xmemory inside TypeScript and Node.js applications.

Example integrations

Pydantic AI - Use xmemory as a structured memory layer in pydantic-ai agents.
Google ADK - Add structured memory to agents built with Google’s Agent Development Kit.
Mastra AI - Integrate xmemory into Mastra-based agent workflows.
n8n - Connect xmemory to automations and workflow pipelines in n8n.
LangChain - Use xmemory with LangChain agents through MCP or direct API access.

If you are deciding where to begin, start with the interface that matches how your system already works:

choose MCP if your agent framework is tool-driven
choose API if you want direct application-level control
choose Python or TypeScript if you want the cleanest language-native integration path