OMEM — Trustworthy memory for AI agents

The official Python SDK for OMEM: a temporal, contradiction-aware memory layer for AI agents. Zero third-party dependencies (stdlib only), so it installs instantly and never conflicts.

Install

pip install omem

Quickstart

from omem import Memory

mem = Memory(api_key="omem_sk_...", project="proj_...")

# Remember a grounded fact (auto-creates the agent + entity on first use).
mem.remember(agent="support-agent", about="customer:123",
             claim="prefers_annual_billing")

# Ask the engine what's believed — it resolves contradictions for you.
print(mem.believes(about="customer:123", claim="prefers_annual_billing"))
# -> BELIEVED_TRUE

# Recall everything known about an entity, with provenance.
for m in mem.recall(about="customer:123")["memories"]:
    print(m["proposition"], m["state"])

# Explain WHY something is believed (full provenance chain).
mem.why("a_...")

Cross-agent memory

Memory is private to an agent by default; you choose what to share.

# private to one agent (only agent-a can recall it)
mem.remember(agent="agent-a", about="acme", claim="secret_deal=1",
             scope="agent:agent-a")

# organisation-wide (every agent in the project can recall it)
mem.remember(agent="agent-a", about="acme", claim="tier=enterprise", scope="org")

# a named team
mem.remember(agent="agent-a", about="acme", claim="ae=jane", scope="team:sales")

# promote an existing memory later
mem.share(assertion_id="a_...", scope="org")

Use as an MCP server (any MCP-compatible agent)

Installing the package also gives you an omem-mcp command that speaks MCP over stdio, exposing three safe tools (omem_recall, omem_observe, omem_why):

OMEM_API_KEY=omem_sk_... OMEM_BASE_URL=https://... OMEM_AGENT=support-agent omem-mcp

Point your MCP client (Claude Desktop, etc.) at that command. The agent identity is fixed at the process level, so a model cannot spoof its way into another agent's private memory.

Self-healing

# report a failure and let OMEM's policy-gated recovery loop handle it
mem.healing.report(component="db-pool", error_type="ECONNRESET")
mem.healing.handle(error={"component": "db-pool", "error_type": "ECONNRESET"})
mem.healing.health()   # aggregated component health

Notes

Every verb maps onto a frozen OMEM engine operation or query. The SDK adds authentication, retries on 5xx, typed errors (OmemError.reason_code exposes R_DANGLING etc.), auto-registration of agents/entities, and cross-agent scope control. It introduces no new memory semantics.