engramme 0.1.0

Official Python SDK for the Engramme API

Engramme Python SDK

Official Python SDK for the Engramme API.

The SDK currently supports the tested memory workflow:

• Authenticate with an Engramme API key
• Upload content with memorize
• Retrieve memories with recall
• Check API health
• Trigger feedback enrichment for an existing feedback document

It does not expose ask() and does not submit webapp telemetry feedback.

Installation

pip install engramme

For local development from this repo:

pip install -e ".[dev]"

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.

enrich_feedback(...)

Trigger feature enrichment for an existing feedback document.

client.enrich_feedback(
    feedback_id="feedback_doc_id",
    trace_id="trace_id_from_recall",
)

This maps to POST /v1/feedback/enrich. It does not create user feedback. Rich webapp feedback submission is currently an internal webapp telemetry flow, not a public SDK method.

health_check()

ok = client.health_check()

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

Errors

The SDK raises:

• AuthenticationError
• RateLimitError
• NotFoundError
• ValidationError
• APIError

All inherit from EngrammeError.

Development

pip install -e ".[dev]"
python3 -m pytest

Run integration tests with:

export ENGRAMME_TEST_API_KEY="eng_sk_..."
python3 -m pytest tests/test_integration.py -v

Build and check the package:

python3 -m build
python3 -m twine check dist/*