Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.engramme.com/llms.txt

Use this file to discover all available pages before exploring further.

The engramme package is the official Python SDK for the Engramme API. Use it from notebooks, scripts, backend services, and internal tools.

Installation

pip install engramme
The latest PyPI package is engramme, currently published as 0.1.1.

Quick Start

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 processing started; the content may not be immediately recallable.

Authentication

from engramme import Engramme

client = Engramme(api_key="eng_sk_...")
API key resolution order:
  1. Explicit api_key passed to Engramme(...)
  2. ENGRAMME_API_KEY
  3. Active profile in ~/.engramme/config.yaml
You can also save and manage a local key with the CLI:
engramme login
engramme whoami
engramme profiles
engramme logout
Local credentials are stored in ~/.engramme/config.yaml. Override that path with ENGRAMME_CONFIG_PATH.

Methods

Engramme(...)

client = Engramme(
    api_key=None,
    profile=None,
    base_url="https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev",
    timeout=30,
)
api_key
str
API key to use directly. If omitted, the SDK checks environment variables and local profiles.
profile
str
Local profile name from ~/.engramme/config.yaml.
base_url
str
API base URL.
timeout
int
default:"30"
Request timeout in seconds.

memorize(...)

Upload a document for memory extraction.
# From file path
result = client.memorize(
    file="notes.txt",
    user_name="Sanket",
    source_type="text",
)

# From bytes
result = client.memorize(
    file=b"Some text",
    user_name="Sanket",
    source_type="text",
    filename="note.txt",
)
file
str | pathlib.Path | bytes
required
File path, pathlib.Path, or raw bytes to upload.
user_name
str
Name associated with the memories.
source_type
str
default:"text"
Type of content, such as text, email, pdf, github, or google_meets.
item_id
str
Optional stable identifier for the uploaded item.
filename
str
Filename to send when file is bytes.

recall(...)

Retrieve memories by semantic similarity.
results = client.recall(
    "meetings about roadmap planning",
    source="text",
    enable_trace=True,
    alpha=0.5,
)
text
str
required
Query text, max 1,000 characters.
source
str
Optional source filter.
enable_trace
bool
Include trace metadata when the API supports it.
alpha
float
Optional hybrid search weight between 0.0 and 1.0.

health_check()

Check API status.
ok = client.health_check()
Returns True when GET /v1/health returns HTTP 200.

Error Handling

from engramme import Engramme, EngrammeError, AuthenticationError

client = Engramme()

try:
    client.recall("team meetings")
except AuthenticationError:
    print("Invalid API key")
except EngrammeError as e:
    print(f"Error: {e}")
ExceptionCause
AuthenticationErrorInvalid API key
RateLimitErrorToo many requests
NotFoundErrorResource not found
ValidationErrorInvalid parameters
APIErrorOther API errors

Next Steps

API Reference

Full REST API documentation.

Authentication

API key best practices.