Python SDK

pip install oramemory

Requires Python 3.9+.

Initialization

from oramemory import Memory

# Reads ORAMEMORY_API_KEY from env
m = Memory()

# Or pass explicitly
m = Memory(api_key="om_live_...", agent_id="myai")

# Self-hosted / staging
m = Memory(api_key="...", base_url="https://memory.mycompany.internal/api")

Environment variables

Methods

m.add(content, *, agent_id=, user_id=, session_id=,
      tags=[], category=, importance=0.5, layer="l3",
      metadata={}, expire_at=, inferred=False)

m.read(query, *, agent_id=, user_id=, scope="agent",
       top_k=5, threshold=0.0, category=, layer=)

m.list(*, agent_id=, user_id=, layer=, page=1, page_size=50)
m.get(id_memory)
m.update(id_memory, *, content=, tags=, importance=, ...)
m.delete(id_memory)
m.history(id_memory)

m.usage()
m.status()

Helpers

support = m.for_agent("support")    # shallow copy with agent_id default
alice   = m.for_user("alice")       # shallow copy with user_id default

support.add("User prefers curt responses")
# Same as:
m.add("User prefers curt responses", agent_id="support")

Error handling

All exceptions inherit OraMemoryError:

from oramemory import Memory, AuthError, RateLimitError, NotFoundError

try:
    hits = m.read("…", agent_id="myai")
except AuthError:
    ...       # 401 — invalid/missing/revoked key
except RateLimitError as ex:
    ...       # 429 — too many writes; reads are never rate-limited
except NotFoundError:
    ...       # 404

Other subclasses: PlanError (403), ValidationError (400), StorageCapError (507).

Framework patterns

Flask middleware

from flask import Flask, g, request
from oramemory import Memory

app = Memory(api_key="om_live_...")   # app-wide

@app.before_request
def _mem():
    g.memory = app.for_user(request.headers.get("X-User-Id", "anon"))

FastAPI dependency

from fastapi import FastAPI, Depends
from oramemory import Memory

_m = Memory(api_key="om_live_...")

def memory_for(x_user_id: str) -> Memory:
    return _m.for_user(x_user_id)

app = FastAPI()

@app.post("/remember")
def remember(text: str, mem: Memory = Depends(memory_for)):
    return mem.add(text, agent_id="assistant")