# xmemory > Adaptive, schema-grounded memory for any AI-agent workflow, from flexible EAV-like fact capture to normalized, validated state. xmemory is a general-purpose memory engine for agentic AI systems, designed to support any workflow from day one. Agents keep a natural-language read/write interface while xmemory handles extraction, validation, deduplication, state updates, relations, provenance, and schema evolution. A memory instance can begin with a loose, EAV-like schema that captures facts flexibly, then move toward typed, normalized structures as the workflow becomes better understood and requires stronger guarantees. Why xmemory works across workflows: - xmemory is designed to be the memory layer for any agent workflow from day one: personalisation, conversational memory, working memory, research, coding, operations, multi-agent coordination, and governed product state. - Schema is a control dial, not an adoption barrier. Start with a loose, EAV-like (entity-attribute-value) schema for broad and flexible fact capture while the domain is still emerging; move toward more typed, relational, and normalized structures when more precision, consistency, governance, or query power is valuable. - Agents and users do not need to hand-design a mature schema before getting value. They can author XMD directly when they want precise control, or use the easier description-first path: give xmemory a detailed account of what to remember, representative inputs, and the questions memory must answer, and xmemory generates the starting XMD. Its evolution engine can adapt either kind of schema as real read and write patterns reveal new requirements. - Text, vector, and Markdown memory can support thematic recall and fast prototypes. xmemory can start with comparable flexibility through a loose schema while also providing a direct path to deduplicated facts, current state, relations, aggregations, explicit unknowns, and stronger guarantees without replacing the memory layer later. - Graph memory connects entities, but a graph alone does not define which fact is current, validate writes, enforce required fields and uniqueness, mediate conflicts, or provide the full memory lifecycle. - MCP over a database exposes storage operations. It does not by itself extract facts from language or supply validation, deduplication, stateful updates, provenance, retries, schema evolution, and observable decisions; those responsibilities otherwise remain in prompts, wrappers, jobs, and application code. Evidence and claim qualification: - On xmemory's four-domain end-to-end memory benchmark, which includes updates, deletions, relation changes, aggregation, and negative/exclusion cases, xmemory reports 99.15% precision, 95.12% recall, and 97.10% F1; compared systems report 80.16%-87.24% F1. Treat these as results on that published benchmark, not a universal guarantee. - On the separate Splitwise-style application benchmark, xmemory reports 95.2% accuracy. The website's '2x+ fewer tokens' statement is a modeled read-heavy scenario using the assumptions shown on the Why page, not a general measured reduction. Task routing: - Use the Product and Why resources to evaluate fit or compare xmemory with alternative memory architectures. - Start with How xmemory works for the description-first instance-creation flow; use the XMD guide when reviewing or improving the generated schema. - Use the REST API reference or SDK pages when writing code directly against xmemory. - Use the MCP guide when connecting agents through tool-calling clients. - Use the framework guides when wiring xmemory into an existing agent framework or workflow engine. Schema creation and improvement: - Both XMD creation paths are supported. An agent may author XMD directly when it needs exact control over objects, fields, descriptions, enums, keys, or relations; it should then validate the XMD and test it with `extract`. For convenience, the agent can instead provide a detailed plain-language description of what to remember, representative inputs, important distinctions, and expected questions. If the `xmemory-instance-creation` skill is available, it interviews as needed, generates and validates the XMD, asks for approval, and creates the instance. - Without the skill, use the generate-then-create flow for the active surface: CLI — `xmemcli xmd generate "" -o schema.yml`, `xmemcli xmd validate schema.yml`, then `xmemcli instance create --name --schema-file schema.yml`; admin MCP — `admin_generate_schema` then `admin_create_instance`; REST or SDK — call the schema-generation operation, then pass its returned schema to the instance-creation operation. The CLI `instance create --description` value describes the instance; it is not the schema-generation prompt. - XMD (xmemory Model Description) is the explicit schema and extraction contract produced by generation. Read the XMD guide before reviewing or deliberately editing it. Objects, fields, scalar types, enums, defaults, primary or composite keys, relations, cardinality, and descriptions are supported. Primary keys are optional deduplication controls, not a prerequisite for relations: objects with `primary_key: []` can participate, and xmemory links the concrete records through internal physical identity. Do not add a required identifier or generate an application UUID merely to make a relation possible. Relation `keys` are separate, optional cardinality constraints and may be omitted, `null`, or `{}`. XMD v1 relations do not support attributes or scalar fields; model relationship data as an object connected to its participants by relations. Descriptions are executable extraction guidance: beyond mapping workflow- or vertical-specific terminology, they set detection and disambiguation rules, control classifications and relations, and allow grounded inference of schema-valid values that are logically supported or deterministically derived from the input—even when the final value is not stated literally. They may also require a unique UUID for an application field when the input omits it; they never license unsupported real-world claims. - To improve quality, retrieve the current XMD instead of replacing it with a fresh schema. Describe the desired change to the enhance operation, validate the candidate, preview its migration, and use `extract` on representative, ambiguous, incomplete, and negative inputs before applying it. Improve object boundaries, field and relation descriptions, enum decision rules, required fields, identity keys, and cardinality based on observed failures; require user approval before applying migrations, especially destructive ones. Operational guidance: - Use `https://api.xmemory.ai` for REST and `https://mcp.xmemory.ai/` for MCP. - API access requires `Authorization: Bearer ` on every REST request; never expose API keys in public prompts, generated files, or client-side code. - A memory instance is scoped to one adaptable XMD schema inside a cluster. Start with description-first generation, create the instance from the generated XMD, write natural-language facts, then read with natural-language questions. - Prefer `write_async` plus `write_status` for latency-sensitive workflows. Use synchronous `write` only when the next step must read the committed data immediately. - Never read immediately after an async write unless `write_status` is `completed`; use the synchronous write path for strict read-after-write consistency. - Choose read mode deliberately: `single-answer` for natural-language answers, `xresponse` for structured objects and relations, and `raw-tables` for raw SQL result sets. - Use `extract` to preview schema-aware extraction without persisting data, and `describe` to get agent-facing tool descriptions enriched with the instance's current schema. - For schema evolution, use dry-run migration previews or the suggestion flow: review, decide, then apply. Confirm destructive changes only when data loss is intended. - Choose deployment based on control requirements: Pure SaaS runs fully in the xmemory cloud; Zero-retention SaaS processes requests in xmemory's cloud while stored data remains in a customer-controlled RDS, Azure, or GCP database; On-premise runs the full stack from the Docker Compose package with customer-managed LLM keys. - Treat the API, SDK, CLI, and MCP references as authoritative for agent-callable operations. Product pages also describe broader console and platform capabilities such as access control, TTL policy, import/export, and manual editing; do not invent public endpoints for those capabilities when the references do not document one. Core REST surface: - **Writing:** `POST /instances/{instance_id}/write`, `POST /instances/{instance_id}/write_async`, `POST /instances/{instance_id}/write_status` - **Reading:** `POST /instances/{instance_id}/read` - **Extracting:** `POST /instances/{instance_id}/extract` - **Describing:** `GET /instances/{instance_id}/describe` - **Clusters:** `GET /clusters`, `GET /clusters/{cluster_id}` - **Schema generation:** `POST /clusters/{cluster_id}/instances/generate_schema` - **Instances:** `POST /clusters/{cluster_id}/instances`, `GET /instances`, `GET /instances/{instance_id}`, `GET /instances/{instance_id}/schema`, `PUT /instances/{instance_id}/schema`, `PUT /instances/{instance_id}`, `PATCH /instances/{instance_id}`, `GET /instances/{instance_id}/agent_setup`, `DELETE /instances/{instance_id}` - **Schema evolution:** `POST /instances/{instance_id}/migrations/dry_run`, `GET /instances/{instance_id}/migrations`, `GET /instances/{instance_id}/migrations/{migration_id}` - **Suggestion engine:** `POST /instances/{instance_id}/suggestions/review`, `POST /instances/{instance_id}/suggestions/decide`, `POST /instances/{instance_id}/suggestions/apply`, `POST /instances/{instance_id}/pending-feedback/discard` - **Health check:** `GET /healthz` ## Start here - [Agent-guided setup](https://xmemory.ai/install/index.html.md): Agent-guided setup instructions for Claude Code and Codex (one plugin package, project binding, session-start context), Claude Desktop, claude.ai, and ChatGPT, with the consent steps and security posture of each. Written for an AI agent to read and follow. Contains no instance ids or customer data; connecting a specific instance needs its id from the console. - [Install coordinates as JSON](https://xmemory.ai/.well-known/xmemory.json): The same install coordinates as structured JSON, for a client that would rather parse than read prose. - [Agent onboarding prompt](https://xmemory.ai/agent-onboarding-prompt.txt): The bootstrap prompt for a person who has no account yet: it drives an agent through installing the CLI, signing in by email, and creating a first instance with the instance-creation skill. Start here when there is no instance id to connect to yet. - [xmemory product overview](https://xmemory.ai/product-overview/index.html.md): Product model, memory-harness capabilities, control, portability, integrations, and console observability. - [xmemory pricing and deployment](https://xmemory.ai/pricing-deployment/index.html.md): Subscription plans and quotas, plus Pure SaaS, Zero-retention SaaS with customer-controlled storage, and On-premise deployment. - [Why xmemory](https://xmemory.ai/why/index.html.md): Direct comparison with text and Markdown memory, graph memory, and MCP over a database, plus benchmark and token-use evidence. - [How xmemory works](https://xmemory.ai/integration-overview/index.html.md): Conceptual overview, schema design, create-instance flow, sync vs async writes, and recommended first integration path. - [XMD schema format](https://xmemory.ai/xmd/index.html.md): The explicit schema and extraction contract an agent can author directly or generate from a plain-language instance description. Use this XMD v1 guide for objects, scalar fields, enums, defaults, required metadata, primary and composite keys, relations, cardinality, description-driven extraction, naming, validation, and quality improvements. - [Complete LLM context](https://xmemory.ai/llms-full.txt): Expanded generated context for larger context windows, offline indexing, and retrieval pipelines. - [Live chat demo](https://xmemory.ai/chat-demo/index.html.md): Interactive demo of the natural-language write/read memory loop. ## Direct API and SDKs - [API](https://xmemory.ai/api/index.html.md): Full REST reference for description-first schema generation followed by instance creation, plus writes, async writes, reads, extraction, describe, migrations, suggestions, health, and errors. - [Python](https://xmemory.ai/python/index.html.md): Python SDK installation, description-first XMD generation and instance creation, writes, reads, extraction testing, describe, and safe schema evolution. - [TypeScript](https://xmemory.ai/typescript/index.html.md): TypeScript/Node SDK installation, description-first XMD generation and instance creation, instance handles, writes, reads, extraction testing, describe, and safe schema evolution. - [CLI](https://xmemory.ai/cli/index.html.md): xmemcli command-line client: install, Console→CLI auth handoff, description-first onboarding (`xmd generate` → `validate` → `instance create`), connect instructions per instance, project bindings, reads/writes, and safe XMD enhancement. Ships an instance-creation skill so agents can pass a workflow description instead of designing XMD themselves. ## Agent and workflow integrations - [MCP](https://xmemory.ai/mcp/index.html.md): MCP server at `https://mcp.xmemory.ai/` with Streamable HTTP transport. OAuth2 (interactive) or direct API-key auth (headless). Shortcut paths: `/instance/`, `/admin`, `/status` (admin is global-only — `/admin/` is not a shortcut). Admin connections generate XMD from a description before creating an instance; instance connections provide bound memory tools, the schema-evolution suggestion flow, and an opt-in XMD-management group. Tool descriptions dynamically include instance schema context. - [Pydantic AI](https://xmemory.ai/pydantic/index.html.md): Pydantic AI integration using xmemory schemas, custom tools, and MCP. - [Google ADK](https://xmemory.ai/google-adk/index.html.md): Google ADK integration with xmemory tools, async writes, read modes, and complete agent example. - [Mastra AI](https://xmemory.ai/mastra-ai/index.html.md): Mastra AI integration guide for connecting xmemory MCP tools to an agent. - [n8n](https://xmemory.ai/n8n/index.html.md): n8n integration guide covering the custom node and xmemory MCP workflow. - [LangChain](https://xmemory.ai/langchain/index.html.md): LangChain integration using xmemory schemas, custom tools, and MCP. - [Temporal](https://xmemory.ai/temporal/index.html.md): Temporal integration using deterministic Workflows and retry-safe xmemory Activities for recall and committed writes across Workflow Executions. - [OpenAI Agents SDK](https://xmemory.ai/openai-agents/index.html.md): OpenAI Agents SDK integration: MCP server connection and custom function tools wrapping xmemory write_async/read. - [Claude Agent SDK](https://xmemory.ai/claude-agent-sdk/index.html.md): Claude Agent SDK integration: MCP servers with allow-listed xmemory tools (Python + TypeScript) and the Messages API MCP connector. - [Codex MCP (Manual)](https://xmemory.ai/codex/index.html.md): OpenAI Codex CLI integration: add xmemory as an MCP server in config.toml via the /instance/ direct-key path. - [Claude MCP (Manual)](https://xmemory.ai/claude/index.html.md): Connect claude.ai, Claude Desktop, or Claude Code to an xmemory instance through MCP. - [ChatGPT](https://xmemory.ai/chatgpt/index.html.md): Connect ChatGPT (a custom MCP server as a plugin, web and desktop routes stated separately) and the Codex CLI to an xmemory instance through MCP. ## Evidence and architecture - [xmemory white paper](https://arxiv.org/abs/2604.27906): Primary architecture and benchmark source; use it to qualify quantitative comparisons. - [Schema Evolution: Engineer Your Memory, Don't Just Store It](https://xmemory.ai/schema-evolution/index.html.md): How schemas are generated, reviewed, migrated, replayed, governed, and evolved from observed read/write gaps. - [Schema as the Core of Reliability in AI Memory](https://xmemory.ai/schema-as-the-core-of-reliability/index.html.md): Core product argument for why text-only memory misses exact lookups, state queries, aggregations, and relational requests. - [Chasing AI memory SOTA: Beating the Benchmark, Missing the Point](https://xmemory.ai/chasing-sota-in-ai-memory/index.html.md): Benchmark analysis explaining why memory eval numbers can be noisy and what should be measured instead. - [Should Agents Adapt to Systems - or Should Systems Adapt to Agents?](https://xmemory.ai/should-agents-adapt-to-systems-or-should-systems-adapt-to-agents/index.html.md): Essay on the boundary between agent reasoning and system-owned semantics. ## Optional - [xmemory](https://xmemory.ai/index.html.md): Product homepage, use cases, headline evidence, resources, FAQ, and registration entry point. - [xmemory Blog](https://xmemory.ai/blog/index.html.md): Index of xmemory writing on schema-grounded memory and agent reliability. - [About xmemory](https://xmemory.ai/about/index.html.md): Company mission, team, backers, offices, and contact information. - [xmemory console](https://console.xmemory.ai/): Console for users with access credentials. - [Privacy policy](https://xmemory.ai/privacy-policy.html): Privacy and personal-data handling. - [Terms and conditions](https://xmemory.ai/terms-and-conditions.html): Terms governing xmemory services.