Python SDK

Install the Z3rno Python SDK and start storing, recalling, and managing agent memories.

Python SDK

The Z3rno Python SDK provides a synchronous and asynchronous client for interacting with the Z3rno memory API.

Installation

pip install z3rno

Requires Python 3.9+.

Client Creation

from z3rno import Z3rnoClient

client = Z3rnoClient(
    base_url="http://localhost:8000",      # or https://api.z3rno.dev
    api_key="z3rno_sk_prod_your_key_here",
)

Parameter	Required	Default	Description
base_url	Yes	—	Z3rno server URL
api_key	Yes	—	Your organisation’s API key
timeout	No	30	Request timeout in seconds
max_retries	No	3	Number of retries on transient failures

Store a Memory

memory = client.store(
    agent_id="agent-1",
    content="User prefers dark mode and uses Python 3.12.",
    memory_type="semantic",              # working | episodic | semantic | procedural
    metadata={"category": "preferences"},
    importance=0.85,                     # Optional: 0.0 - 1.0
)

print(memory.id)          # mem_a1b2c3d4...
print(memory.created_at)  # 2026-04-19T10:30:00Z

Recall Memories

results = client.recall(
    agent_id="agent-1",
    query="What does the user prefer?",
    memory_type="semantic",    # Optional: filter by type
    top_k=5,                   # Max results (default: 10)
)

for r in results:
    print(r.content, "(relevance:", round(r.relevance_score, 2), ")")

Recall with filters

# Temporal filter
results = client.recall(
    agent_id="agent-1",
    query="pricing conversations",
    memory_type="episodic",
    time_range={"start": "2026-03-01", "end": "2026-03-31"},
)

# Point-in-time query
results = client.recall(
    agent_id="agent-1",
    query="user preferences",
    as_of="2026-03-15T12:00:00Z",
)

# Metadata filter
results = client.recall(
    agent_id="agent-1",
    query="preferences",
    metadata_filter={"category": "preferences"},
)

Forget a Memory

Soft delete

Marks the memory as deleted. It no longer appears in recall results but is retained for audit purposes.

client.forget(agent_id="agent-1", memory_id="mem_a1b2c3d4")

Hard delete (GDPR-compliant)

Permanently removes the memory and all associated data from every storage layer.

client.forget(
    agent_id="agent-1",
    memory_id="mem_a1b2c3d4",
    hard=True,
)

Hard deletes are irreversible. The memory content is permanently purged from PostgreSQL, pgvector, Apache AGE, and Valkey.

Bulk delete

# Soft delete all memories for an agent
client.forget_all(agent_id="agent-1")

# Hard delete all memories for an agent
client.forget_all(agent_id="agent-1", hard=True)

Audit Trail

Query the audit log to see the full history of memory operations for an agent.

events = client.audit(
    agent_id="agent-1",
    event_type="store",        # Optional: store | recall | update | forget
    limit=50,
)

for event in events:
    print(event.timestamp, "|", event.event_type, "|", event.memory_id)

Version history

Retrieve the full version history of a specific memory.

history = client.history(memory_id="mem_a1b2c3d4")

for version in history:
    print("v" + str(version.version) + ":", version.content)
    print("  Active:", version.valid_from, "→", version.valid_to or "current")

Session Management

Sessions group related interactions and manage working memory lifecycle.

# Start a session
session = client.start_session(agent_id="agent-1")

# Store working memory within the session
client.store(
    agent_id="agent-1",
    content="User is asking about pricing.",
    memory_type="working",
    session_id=session.id,
)

# End the session — working memories are consolidated into episodic memory
client.end_session(session_id=session.id)

When a session ends, Z3rno automatically consolidates working memories into episodic memories. You do not need to manually manage this transition.

Error Handling

The SDK raises typed exceptions that inherit from Z3rnoError:

from z3rno import Z3rnoError, AuthenticationError, NotFoundError, RateLimitError

try:
    results = client.recall(agent_id="agent-1", query="test")
except AuthenticationError:
    # Invalid or expired API key
    print("Check your API key")
except NotFoundError:
    # Agent or memory not found
    print("Agent does not exist")
except RateLimitError as e:
    # Rate limit exceeded
    print("Rate limited. Retry after", e.retry_after, "seconds")
except Z3rnoError as e:
    # Any other Z3rno error
    print("Z3rno error:", e.message, "(code:", e.code, ")")

Exception hierarchy

Z3rnoError
  ├── AuthenticationError      # 401 — invalid API key
  ├── AuthorisationError       # 403 — insufficient permissions
  ├── NotFoundError            # 404 — resource not found
  ├── ValidationError          # 422 — invalid request parameters
  ├── RateLimitError           # 429 — rate limit exceeded
  ├── ConflictError            # 409 — duplicate or version conflict
  └── ServerError              # 5xx — internal server error

Async Client

For async applications, use AsyncZ3rnoClient. The API is identical — every method is an async coroutine.

from z3rno import AsyncZ3rnoClient

client = AsyncZ3rnoClient(
    base_url="http://localhost:8000",
    api_key="z3rno_sk_prod_your_key_here",
)

# All methods are awaitable
memory = await client.store(
    agent_id="agent-1",
    content="User prefers dark mode.",
    memory_type="semantic",
)

results = await client.recall(
    agent_id="agent-1",
    query="What does the user prefer?",
)

# Don't forget to close the client when done
await client.close()

As a context manager

async with AsyncZ3rnoClient(
    base_url="http://localhost:8000",
    api_key="z3rno_sk_prod_your_key_here",
) as client:
    memory = await client.store(
        agent_id="agent-1",
        content="User prefers dark mode.",
        memory_type="semantic",
    )
    # Client is automatically closed when the block exits

Next Steps

Memory Types

Understand the four memory types and when to use each one.

TypeScript SDK

Using TypeScript? See the TypeScript SDK guide.