xmemory
Python client library for the xmemory API.
Quick start
from xmemory import XmemoryClient, SchemaType
client = XmemoryClient(api_key="xmem_...") # or set XMEM_API_KEY env var
# Create an instance and start using it immediately
schema = """\
objects:
person:
fields:
name:
type: str
required: true
description: full name of the person
role:
type: str
required: false
description: job title or role
location:
type: str
required: false
description: city or location
relations: {}
"""
inst = client.admin.create_instance(
cluster_id="<your-cluster-id>",
name="my-memory",
schema_text=schema,
schema_type=SchemaType.YML,
)
inst.write("Alice is a software engineer based in Berlin.")
result = inst.read("What does Alice do?")
print(result.reader_result)
Bind to an existing instance
inst = client.instance("<your-instance-id>")
inst.write("Bob joined the team as a designer.")
result = inst.read("Who is on the team?")
Async quick start
import asyncio
from xmemory import AsyncXmemoryClient, SchemaType
async def main():
async with AsyncXmemoryClient(api_key="xmem_...") as client:
inst = await client.admin.create_instance(
cluster_id="<cluster-id>",
name="my-memory",
schema_text=schema, # same schema as above
schema_type=SchemaType.YML,
)
await inst.write("Alice is a software engineer based in Berlin.")
result = await inst.read("What does Alice do?")
print(result.reader_result)
asyncio.run(main())
Configuration
| Parameter | Env var | Default | Description |
|---|---|---|---|
url |
XMEM_API_URL |
https://api.xmemory.ai |
Base URL of the xmemory API |
api_key |
XMEM_API_KEY |
None |
API key for authentication |
timeout |
— | 60 |
Default request timeout in seconds |
Deprecation: The legacy term
token(argumenttoken=and env varXMEM_AUTH_TOKEN) is still accepted for backwards compatibility but prints an orange-colored deprecation notice on use. Migrate toapi_key/XMEM_API_KEY. The legacy names will be removed in a future release.
Client structure
The client is organized into two namespaces:
client.admin— cluster management, instance lifecycle, schema and metadata managementclient.instance(id)— instance-bound data operations (read, write, extract)
Admin API (client.admin)
# Clusters
clusters = client.admin.list_clusters()
cluster = client.admin.get_cluster("<cluster-id>")
# Instance lifecycle
inst = client.admin.create_instance(cluster_id, "name", schema, SchemaType.YML)
instances = client.admin.list_instances()
info = client.admin.get_instance("<instance-id>")
client.admin.delete_instance("<instance-id>")
# Schema management
schema = client.admin.get_instance_schema("<instance-id>")
client.admin.update_instance_schema("<instance-id>", new_schema, SchemaType.YML)
# Metadata management
client.admin.update_instance_metadata("<instance-id>", "new-name", "new description")
# Change one field and leave the rest alone
client.admin.patch_instance_metadata("<instance-id>", description="a new description")
# Schema generation
result = client.admin.generate_schema(cluster_id, "People with name, role, and location.")
print(result.data_schema)
create_instance returns an InstanceAPI bound to the new instance, ready for data operations.
list_instances and get_instance return InstanceInfo metadata objects.
Agent-facing instance metadata
An instance can carry metadata that shapes how agents connect to it and what
they do with it. patch_instance_metadata is the way to set the advisory
hints: every argument is independent, omitting one leaves the stored value
untouched, and passing None clears it.
from xmemory import AgentSurface, BindingTier
client.admin.patch_instance_metadata(
"<instance-id>",
# Advisory hints — they seed what a connect flow proposes, and grant nothing.
agent_surfaces=[AgentSurface.CLAUDE_CODE, AgentSurface.CODEX],
agent_default_binding_tier=BindingTier.AUTOLOAD,
agent_engagement_hints=["a convention is learned or corrected"],
)
Concurrent edits to these three are last-writer-wins by design: they only seed
what a connect flow proposes, so the loser of a race re-applies a suggestion.
agent_owner_instructions is not like that — see below.
Reading it back:
info = client.admin.get_instance("<instance-id>")
info.agent_owner_instructions
info.agent_surfaces # e.g. ["claude_code", "codex"]
info.agent_default_binding_tier # e.g. "autoload"
info.agent_engagement_hints
These read as plain strings rather than enums, so a value your server knows and this release does not is returned rather than rejected.
Setting the standing instructions. Use update_instance_metadata for
agent_owner_instructions, not patch_instance_metadata. The field is
rendered to agents verbatim, and a second writer edits it from the same screen,
so a silently lost edit is a rule that stops being enforced. Only
update_instance_metadata carries expected_owner_instructions_epoch: pass
the epoch you read the value at and the server refuses the losing save instead
of applying it.
patch_instance_metadata also accepts the field — it is the only way to set it
without restating the name — but it can carry no guard, so an edit composed
from stale data overwrites a newer one silently. Reach for it only when you are
seeding a value nobody else is editing.
info = client.admin.get_instance("<instance-id>")
client.admin.update_instance_metadata(
"<instance-id>", info.name, info.description,
agent_owner_instructions=(info.agent_owner_instructions or "") + "\nAlso: never paraphrase a rule.",
expected_owner_instructions_epoch=info.agent_owner_instructions_epoch,
)
Instance API (client.instance(id))
inst = client.instance("<instance-id>")
# Read
result = inst.read("Who is on the team?")
print(result.reader_result)
# Write (synchronous)
result = inst.write("Bob joined the team on Monday as a designer.")
print(result.changes) # what the write created / updated / deleted
# Write (async job)
job = inst.write_async("Bob joined the team on Monday as a designer.")
status = inst.write_status(job.write_id)
# Structured write: deterministic, LLM-free create/update/delete mutations
# (mutually exclusive with text; applied in list order)
from xmemory import ObjectCreate, ObjectMutation
result = inst.write(structured_mutations=[
ObjectMutation(
object_type="person",
create=ObjectCreate(key={"name": "Bob"}, values={"role": "designer"}),
),
# Plain dicts in the API wire form work too:
{"object_mutation": {"object_type": "person", "update": {"key": {"name": "Bob"}, "values": {"role": None}}}}, # None clears
])
# Extract (without persisting)
result = inst.extract("Carol is a manager based in Berlin.")
print(result.objects_extracted)
# Describe: agent-facing tool docs, plus what this memory is for
described = inst.describe()
print(described.as_text()) # ready to inject into a system prompt
described.purpose # what the memory is for (the instance description)
described.owner_instructions # the standing preference set for it, verbatim
described.usage_brief # generated from the schema; None until generated
as_text() includes purpose and owner_instructions when the instance has
them. usage_brief is left out of it — it restates the schema summary that is
already there — so read the attribute if you want it.
Both fields are free text set by anyone holding edit permission on the instance,
so as_text() labels each with where it came from rather than presenting it as
the library's own words. Those labels state provenance; they are not a security
boundary. If you inject this into a system prompt you are still handling text you
do not control.
Read modes
from xmemory import ReadMode
result = inst.read("Show people and companies", read_mode=ReadMode.XRESPONSE)
Composite queries
When a query bundles several independent questions, the server may decompose it
into sub-queries and answer each one. reader_result is still the combined
answer (for single-answer mode, a labelled multi-part string); reader_results
holds one TaggedReaderResult (sub_query, reader_result, error) per
sub-query so you can read each answer unambiguously. A single-intent query yields
one entry, and the list is empty against a server without question decomposition.
result = inst.read("Who leads sales, and where is HQ?")
for part in result.reader_results:
print(part.sub_query, "->", part.error or part.reader_result)
Scoped reads
By default a read may draw on any object in the instance. Pass a scope to
restrict it to a specific set of concrete objects — each named by its type
plus its user-defined primary key:
from xmemory import ReadScope, ScopeObject
result = inst.read(
"What do these people do?",
scope=ReadScope(
objects=[
ScopeObject(type="Person", key={"name": "Alice"}),
ScopeObject(type="Person", key={"name": "Bob"}),
],
),
)
Only the listed objects are in scope. To also expose the relations among them,
set relations_scope="all_relations" (the default is "no_relations"):
result = inst.read(
"How are these people connected?",
scope=ReadScope(
objects=[
ScopeObject(type="Person", key={"name": "Alice"}),
ScopeObject(type="Company", key={"name": "Acme"}),
],
relations_scope="all_relations",
),
)
Each ScopeObject is identified by its user-defined primary key (the same
field name(s) used in your schema), not an internal id. key must contain at
least one field. Scoped reads compose with read_mode.
Extraction logic
from xmemory import ExtractionLogic
result = inst.write("...", extraction_logic=ExtractionLogic.FAST)
Schema format
Schemas use the XMD (Xmemory Data Model) format with objects and relations:
objects:
person:
fields:
name:
type: str
required: true
description: full name of the person
role:
type: str
required: false
description: job title or role
company:
fields:
name:
type: str
required: true
description: company name
industry:
type: str
required: false
description: industry or sector
relations:
employment:
objects:
person:
type: person
on_delete: cascade
company:
type: company
on_delete: cascade
description: person works at company
Field types: str, int, float, bool, date, datetime.
Schema evolution
Schemas can change after creation. xmemory supports safe, data-preserving migrations (rename / remove / type change) driven by structured migration ops, plus a suggestion engine that proposes improvements from real read traffic. Both paths are purely additive to this library — existing callers are unaffected.
See the Schema evolution section of the API reference for the conceptual model, and the Python guide for full walkthroughs.
Suggestion-engine flow (review → decide → apply)
The engine surfaces a single rolling proposal per instance. The minimum flow is three calls — review, decide (in bulk), apply:
from xmemory import DecisionInput, XmemoryClient
client = XmemoryClient(api_key="xmem_...")
inst = client.instance("<instance-id>")
# 1. Review — get the consolidated proposal + its concurrency token.
review = inst.review_suggestions()
if review.status == "evolution_in_progress":
print(f"A migration is in flight; retry in {review.retry_after_seconds}s")
else:
proposal = review.proposal
for item in proposal.items:
print(item.item_fingerprint, item.rationale, item.op)
# 2. Decide — accept / reject / defer per item, in one batch.
decided = inst.decide_suggestions(
proposal.proposal_version,
[DecisionInput(item_fingerprint=item.item_fingerprint, decision="accept")
for item in proposal.items],
)
# 3. Apply — commit accepted decisions as one migration.
applied = inst.apply_pending_decisions(decided.next_proposal_version)
print(applied.status, applied.summary) # e.g. "ok" "added 1 field"
review_suggestions() returns a ReviewSuggestionsResult. When
status == "evolution_in_progress", back off for retry_after_seconds and
retry instead of blocking.
Direct migration flow (enhance → dry-run → update)
To drive a migration yourself (e.g. renaming a field), ask the server to enhance the current schema, preview the DDL, then apply it:
import yaml
from xmemory import XmemoryClient
client = XmemoryClient(api_key="xmem_...")
current = client.admin.get_instance_schema("<instance-id>").data_schema
# 1. Enhance — produce the new schema + an executor-ready migration plan.
enhanced = client.admin.enhance_schema(
cluster_id="<cluster-id>",
schema_description="Rename Person.mail to Person.email.",
current_yml_schema=yaml.safe_dump(current),
)
print(enhanced.summary)
for op in enhanced.migration_plan.ops:
print(op)
new_yaml = yaml.safe_dump(enhanced.data_schema)
# 2. Dry-run — preview the DDL without applying anything.
preview = client.admin.dry_run_migration(
"<instance-id>", new_yaml, SchemaType.YML,
migration_plan=enhanced.migration_plan,
)
print(preview.statements)
# 3. Update — apply. confirm_destructive=True is required for ops that drop data.
info = client.admin.update_instance_schema(
"<instance-id>", new_yaml, SchemaType.YML,
migration_plan=enhanced.migration_plan,
confirm_destructive=False,
)
print(info.migration_id, info.prior_version, "->", info.new_version)
Migration history
page = client.admin.list_migrations("<instance-id>", limit=20)
for record in page.items:
print(record.id, record.source, record.prior_version, "->", record.new_version)
detail = client.admin.get_migration("<instance-id>", "<migration-id>", include_yaml=True)
print(detail.yaml_before, detail.yaml_after)
Migration ops are exported as typed models (MigrationPlan, MigrationOp,
AddField, RenameField, RemoveObject, …). ProposalItem.op and
MigrationRecord.ops are kept as raw dicts for forward compatibility — call
parse_migration_op(...) / parse_migration_plan(...) to validate them into
typed ops.
Runnable end-to-end examples live in examples/.
Context managers
Both clients support the context manager protocol and close the underlying HTTP connection on exit.
# sync
with XmemoryClient(api_key="xmem_...") as client:
inst = client.instance("abc")
inst.write("...")
# async
async with AsyncXmemoryClient(api_key="xmem_...") as client:
inst = client.instance("abc")
await inst.write("...")
External HTTP client
You can pass your own httpx.Client (or httpx.AsyncClient). The client will not be closed when
the Xmemory client is closed, giving you full control over its lifecycle.
import httpx
from xmemory import XmemoryClient
http = httpx.Client(base_url="https://api.xmemory.ai", timeout=30)
client = XmemoryClient(http_client=http, api_key="xmem_...")
Health check
from xmemory import XmemoryHealthCheckError
try:
client.check_health()
except XmemoryHealthCheckError as e:
print(f"API is unreachable: {e}")
Error handling
All errors raise XmemoryAPIError (or its subclass XmemoryHealthCheckError for connectivity failures).
XmemoryAPIError carries an optional .status (HTTP status code), .code (structured error code,
when the server returned one), .details (structured error payload), and .retry_after
(the Retry-After response header in seconds, when the server sent one).
from xmemory import XmemoryAPIError
try:
result = client.instance("abc").read("something")
except XmemoryAPIError as e:
print(f"API error (HTTP {e.status}): {e}")
Branch on .code, not on the HTTP status. A single status can carry more
than one meaning, so the structured .code is the discriminator, never the bare
status. Pattern match on .code rather than parsing the message string.
Account / billing & rate-limit codes
| HTTP | .code |
Meaning | Retryable? |
|---|---|---|---|
| 402 | QUOTA_EXCEEDED |
Tenant exhausted its plan's daily/monthly token quota. | No |
| 429 | RATE_LIMITED |
Genuine velocity/rate limit. | Yes — back off and retry, honoring .retry_after. |
For QUOTA_EXCEEDED, details carries {"kind": "daily_quota_exceeded" | "monthly_quota_exceeded", "retry_after_seconds": int | None}, and when the window is resettable the server also
sends a Retry-After header (surfaced as .retry_after).
The library never retries automatically — it only surfaces these values for you to act on.
import time
try:
result = client.instance("abc").write("…")
except XmemoryAPIError as e:
if e.code == "QUOTA_EXCEEDED":
kind = (e.details or {}).get("kind") # daily_quota_exceeded | monthly_quota_exceeded
# Non-retryable: surface to the user; e.retry_after (seconds) hints when the window resets.
raise
elif e.code == "RATE_LIMITED":
# Retryable: back off, honoring e.retry_after if set, then retry.
time.sleep(e.retry_after or 1)
else:
raise
Schema-evolution codes
The schema-evolution endpoints return structured error codes you can pattern
match on via .code rather than parsing the message — for example
stale_proposal_version, dependency_closure_failed,
destructive_confirmation_required, non_additive_change_requires_plan,
stale_schema_version, migration_not_found, instance_not_initialised:
try:
inst.apply_pending_decisions(token)
except XmemoryAPIError as e:
if e.code == "stale_proposal_version":
review = inst.review_suggestions() # re-review and retry
Response types
| Method | Returns |
|---|---|
admin.list_clusters() |
list[ClusterInfo] |
admin.get_cluster() |
ClusterInfo |
admin.create_instance() |
InstanceAPI |
admin.list_instances() |
list[InstanceInfo] |
admin.get_instance() |
InstanceInfo |
admin.get_setup_instructions() |
AgentSetupResult |
admin.get_instance_schema() |
InstanceSchemaInfo |
admin.update_instance_schema() |
InstanceInfo |
admin.update_instance_metadata() |
InstanceInfo |
admin.patch_instance_metadata() |
InstanceInfo |
admin.delete_instance() |
list[str] |
admin.generate_schema() |
GenerateSchemaResult |
admin.enhance_schema() |
EnhanceSchemaResult |
admin.dry_run_migration() |
DryRunResult |
admin.list_migrations() |
ListMigrationsResult |
admin.get_migration() |
MigrationRecord |
inst.read() |
ReadResult |
inst.write() |
WriteResult |
inst.write_async() |
AsyncWriteResult |
inst.write_status() |
WriteStatusResult |
inst.extract() |
ExtractResult |
inst.get_schema() |
InstanceSchemaInfo |
inst.describe() |
DescribeResult |
inst.setup_instructions() |
AgentSetupResult |
inst.review_suggestions() |
ReviewSuggestionsResult |
inst.decide_suggestions() |
DecideSuggestionsResult |
inst.apply_pending_decisions() |
ApplyPendingDecisionsResult |
License
This client library is released under the MIT license. The MIT grant covers this library only — the xmemory service it talks to and the technology behind it are proprietary to xmemory Inc., and using the service is governed by the Terms & Conditions.
Package publishing to pip
python -m pip install --upgrade build twine
python -m build
# test with test.pypi.org (separate account and API key required)
python -m twine upload --repository testpypi dist/*
# publish the real version when ready
python -m twine upload dist/*
# test the package
pip install xmemory-ai
Connecting an instance elsewhere
admin.get_setup_instructions(instance_id) and inst.setup_instructions() both return an
AgentSetupResult: how to reach the same memory from another agent surface, ordered
most-likely-first. Available on either handle, because the MCP instance connection serves
the same tool.
setup = inst.setup_instructions()
for surface in setup.surfaces:
print(surface.label)
for step in surface.steps:
print(" ", step.description, step.command or "")
Two formats. The default, SetupFormat.AGENT, answers what do I run right now, here.
SetupFormat.PROJECT also returns the files a team commits once, so nobody sets the
instance up by hand:
setup = inst.setup_instructions(format=SetupFormat.PROJECT)
if setup.format == SetupFormat.PROJECT and setup.project:
for fragment in setup.project.fragments:
print(fragment.path, fragment.merge) # a merge, never a file to overwrite
Check setup.format rather than assuming. A server older than that parameter ignores
it and still answers 200, so asking for PROJECT is not the same as receiving it.
Nothing returned carries a credential: the steps tell a reader to sign in themselves, out of band, so an instance id stays an identifier rather than a key.
Advisory values — step.kind, fragment.merge, format — arrive as enum members when
this release knows them and as plain strings when it does not, so a value added to the
server later does not make the whole result unparseable. A step.kind you do not
recognise is not something to execute.
Metadata
Release files for xmemory-ai 0.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xmemory_ai-0.14.0.tar.gz | 55.8 kB | Without provenance | Details for xmemory_ai-0.14.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xmemory_ai-0.14.0-py3-none-any.whl | Python 3 | none | any | Details for xmemory_ai-0.14.0-py3-none-any.whl |
Total release size: 94.5 kB
Release files / xmemory_ai-0.14.0.tar.gz
| Download URL | xmemory_ai-0.14.0.tar.gz |
|---|---|
| Size | 55.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
630568543a9b3b1d371138620a121b1746e815e2f4cd5a69b1b3cc2e5b42f477
|
|
BLAKE2b-256 checksum How to use checksums |
915fd14558dc6d418393423c7afb1a048108c4ef899d34f9bd4b9c90c1ebac33
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / xmemory_ai-0.14.0-py3-none-any.whl
| Download URL | xmemory_ai-0.14.0-py3-none-any.whl |
|---|---|
| Size | 38.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55f027e7702db083d1ab92075c516dea6508c660219eacb24e2ddf33c0df0dae
|
|
BLAKE2b-256 checksum How to use checksums |
f5852e8d70fccdaa66cf984cbc2b4a11b878afb655881fc6c5fe7b263bba29bc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for xmemory-ai 0.14.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.