Input data types

Engram accepts three types of input content when storing memories:

You pass one of these three shapes as the first argument to client.memories.add(). Exactly one content type is used per call.

Send raw text and let Engram's pipeline extract structured memories from it. content is an array, so you can send multiple unrelated strings in one call — each becomes its own pipeline input.

client.memories.add("The user prefers dark mode and uses VS Code.", user_id=test_user_id)

Send multi-turn messages with roles for chat transcripts and agent conversations. The pipeline uses conversation-aware extraction to pull memories from the dialogue.

Messages follow the OpenAI Chat Completions format: role is one of user, assistant, system, tool, or developer. Tool calls (tool_calls, tool_call_id, name) are supported. The server normalizes tool → user and developer → system internally.

client.memories.add(
    [
        {"role": "user", "content": "I just moved to Berlin."},
        {"role": "assistant", "content": "Welcome to Berlin!"},
        {"role": "user", "content": "I prefer specialty coffee."},
    ],
    user_id=test_user_id,
)

Send already-structured items when you've done your own extraction. Each item carries its target topic and bypasses the LLM extraction step — it still flows through the transform and commit stages.

from engram import PreExtractedInput, PreExtractedItem

client.memories.add(
    PreExtractedInput(items=[
        PreExtractedItem(content="User prefers dark mode", topic="UserKnowledge"),
        PreExtractedItem(content="User works in Python", topic="UserKnowledge"),
    ]),
    user_id=test_user_id,
)

Have a question or feedback? Here's how to reach us.