Metadata-Version: 2.5
Name: omem-infrastructure
Version: 0.1.1
Summary: Trustworthy memory for AI agents — the official OMEM Python SDK.
Project-URL: Homepage, https://github.com/omem/omem
Project-URL: Documentation, https://github.com/omem/omem#readme
Project-URL: Source, https://github.com/omem/omem
Author: OMEM
License: MIT
Keywords: agents,ai,belief,knowledge,llm,mcp,memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install omem
```

## Quickstart

```python
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.

```python
# 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`):

```bash
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

```python
# 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.
