Python SDK

The official Python SDK for Engram. Sync and async, full type safety, Pydantic v2.

Installation

pip install engram.to

Requirements: Python 3.9+ · View on PyPI

Basic usage

from engram import Engram

client = Engram(
    base_url="http://localhost:8080",  # or set ENGRAM_BASE_URL env var
    api_key="mk_your_key",             # or set ENGRAM_API_KEY env var
)

# Create an agent
agent = client.agents.create(external_id="user-123", name="Alice")

# Store a memory
memory = client.memories.store(
    agent_id=agent.id,
    content="User prefers concise responses",
    type="preference",
)

# Recall
results = client.memories.recall(
    agent_id=agent.id,
    query="What are this user's preferences?",
    top_k=5,
)

for m in results:
    print(f"[{m.confidence:.2f}] {m.content}")

Async client

from engram import AsyncEngram
import asyncio

async def main():
    async with AsyncEngram(base_url="http://localhost:8080", api_key="mk_...") as client:
        agent = await client.agents.create(external_id="user-123", name="Alice")

        await client.memories.store(
            agent_id=agent.id,
            content="User is a backend engineer",
        )

        results = await client.memories.recall(
            agent_id=agent.id,
            query="What does this user do?",
        )

asyncio.run(main())

Environment variables

The client reads from environment variables if not passed explicitly:

export ENGRAM_BASE_URL=http://localhost:8080
export ENGRAM_API_KEY=mk_your_key

# No arguments needed
client = Engram()

Resources

Resource	Description
client.agents	Create, list, delete agents
client.memories	Store, recall, extract, delete memories (with anchor_external_id / session_id)
client.anchors	Subjects — list, get, profile, GDPR purge (scopes guide)
client.sessions	Conversation sessions — create, get, end
client.canon	Tenant-shared org knowledge (admin-scoped)
client.cognitive	Decay, consolidate, health, confidence
client.graph	Graph edges, traversal
client.episodes	Episodic memory management
client.procedures	Procedural memory management
client.schemas	Schema (mental model) access
client.feedback	Explicit feedback recording
client.learning	Learning statistics
client.keys	API key management

Error handling

from engram.exceptions import (
    AuthenticationError,
    NotFoundError,
    ValidationError,
    ConnectionError,
)

try:
    memory = client.memories.get("non-existent-id")
except NotFoundError:
    print("Memory not found")
except AuthenticationError:
    print("Invalid API key")
except ConnectionError as e:
    print(f"Server unreachable: {e}")