# 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. xmemory can generate a useful starting schema from a workflow description, existing systems or sample data, and its evolution engine can adapt that 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 when you need the schema design flow or recommended integration sequence. - 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. 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 schema inside a cluster. Start with a loose generated schema or a stricter domain model, create the instance, 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}`, `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 - [Install xmemory in your agent](https://xmemory.ai/install/index.html.md): Generic install 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. 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. - [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 clusters, instances, schema generation, writes, async writes, reads, extraction, describe, migrations, suggestions, health, and errors. - [Python](https://xmemory.ai/python/index.html.md): Python SDK installation, sync/async clients, schema and instance management, writes, reads, extraction, describe, and schema evolution. - [TypeScript](https://xmemory.ai/typescript/index.html.md): TypeScript/Node SDK installation, zero-dependency client setup, instance handles, writes, reads, extraction, describe, and schema evolution. - [CLI](https://xmemory.ai/cli/index.html.md): xmemcli command-line client: install, Console→CLI auth handoff, onboarding (xmd generate → validate → instance create), connect instructions per instance (instance setup, including the committable project form), project bindings and the session-start context pack, reads/writes against the active instance, and schema evolution. Ships an agent skill installable via the skills CLI. ## 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). Instance connections provide bound memory tools, the schema-evolution suggestion flow, and an opt-in schema-management group; admin connections provide fleet management. 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](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](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 custom apps and 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.