engramme 0.1.1

Python SDK for Engramme's human memory API

Engramme Python SDK

Engramme is the API to augment human memory.

Engramme turns documents, notes, transcripts, and other lived context into structured episodic memories. Its Large Memory Models (LMMs) extract who was involved, what happened, when it happened, and how experiences connect, so applications can help people recall relevant memories naturally.

Use the Python SDK to build with Engramme from notebooks, scripts, backend services, and internal tools.

The SDK currently supports the tested public workflow:

• Authenticate with an Engramme API key.
• Upload content with memorize.
• Retrieve raw memories with recall.
• Check API health.

It does not expose ask() or feedback submission yet. Feedback is currently handled by the Engramme webapp while we keep the public SDK contract focused and stable.

Installation

pip install engramme

Authentication

Pass an API key directly:

from engramme import Engramme

client = Engramme(api_key="eng_sk_...")

Or set an environment variable:

export ENGRAMME_API_KEY="eng_sk_..."

Then initialize without arguments:

from engramme import Engramme

client = Engramme()

You can also save a key locally:

engramme login
engramme whoami
engramme profiles
engramme logout

Local credentials are stored in ~/.engramme/config.yaml. Override that path with:

export ENGRAMME_CONFIG_PATH="/path/to/config.yaml"

Quickstart

from engramme import Engramme

client = Engramme()

print(client.health_check())

upload = client.memorize(
    file=b"Meeting notes about the Q4 roadmap and launch timeline.",
    user_name="Sanket",
    source_type="text",
    filename="meeting-notes.txt",
)

print(upload["item_id"])

results = client.recall("Q4 roadmap launch timeline")

for memory in results.get("memories", []):
    print(memory)

Memorization starts asynchronous processing. A successful memorize response means the upload was accepted and a workflow started; the content may not be immediately recallable.

API

Engramme(...)

client = Engramme(
    api_key=None,
    profile=None,
    base_url="https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev",
    timeout=30,
)

API key resolution order:

1. Explicit api_key
2. ENGRAMME_API_KEY
3. Active profile in ~/.engramme/config.yaml

memorize(...)

Upload content for memory extraction and indexing.

client.memorize(
    file="notes.txt",
    user_name="Sanket",
    item_id="optional-stable-id",
    source_type="text",
)

file can be:

• A path string
• A pathlib.Path
• Raw bytes

When passing bytes, use filename if you want a specific uploaded filename:

client.memorize(
    file=b"Some text",
    user_name="Sanket",
    source_type="text",
    filename="note.txt",
)

recall(...)

Retrieve memories by semantic similarity.

results = client.recall(
    "meetings about roadmap planning",
    source="text",
    enable_trace=True,
    alpha=0.5,
)

Arguments:

• text: Query text, max 1000 characters.
• source: Optional source filter.
• enable_trace: Include trace metadata when the API supports it.
• alpha: Optional hybrid search weight between 0.0 and 1.0.

health_check()

ok = client.health_check()

Returns True when GET /v1/health returns HTTP 200.

Feedback

Feedback is not part of the public SDK surface yet.

The Engramme webapp supports rich recall feedback, including overall ratings, memory-level ratings, comments, and issue codes. That flow is currently owned by the webapp backend, not the Core API gateway used by this SDK.

When a stable SDK-facing feedback endpoint exists, the SDK should expose a simple method that lets developers rate recall quality without knowing the webapp telemetry schema.

Errors

The SDK raises:

• AuthenticationError
• RateLimitError
• NotFoundError
• ValidationError
• APIError

All inherit from EngrammeError.