agent-framework-engram 0.1.1

Engram (Lumetra) durable memory tools and middleware for the Microsoft Agent Framework.

agent-framework-engram

Durable memory for Microsoft Agent Framework agents, powered by Engram — Lumetra's memory service for AI agents.

Ships two extension points so you can pick whichever fits your architecture:

Extension point	Class	What it does
Tools	EngramTools	Exposes engram_store_memory, engram_query_memory, etc. as first-class @ai_function tools.
Middleware	EngramMiddleware	Transparently recalls relevant memories before each turn and auto-stores the user message after.

The tools path is recommended — it lets the model itself decide when to recall and persist, which is the strength of Agent Framework's function-tool loop.

Heads up: the tools class used to be named EngramSkill. It was renamed to EngramTools to avoid colliding with Microsoft Agent Framework's own Skill primitive (SKILL.md domain-knowledge bundles per the agentskills.io spec). EngramSkill is kept as a deprecated alias and will emit a DeprecationWarning on use; please migrate to EngramTools.

Install

pip install agent-framework-engram

Requires agent-framework>=1.5 and Python 3.10+.

Get an Engram API key at https://lumetra.io. Export it:

export ENGRAM_API_KEY=eng_live_...

Quick start — Tools (recommended)

import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
from agent_framework_engram import EngramTools


async def main() -> None:
    memory = EngramTools(bucket="my-agent")  # ENGRAM_API_KEY from env

    agent = Agent(
        client=OpenAIChatClient(),
        name="assistant",
        instructions=(
            "You have durable memory across conversations via the engram_* "
            "tools. Call engram_query_memory before answering questions "
            "about the user, and engram_store_memory whenever the user "
            "shares a new preference or fact."
        ),
        tools=memory.tools,
    )

    print(await agent.run("Remember that I prefer dark mode and metric units."))
    print(await agent.run("What do you remember about my UI preferences?"))


asyncio.run(main())

Quick start — Middleware (transparent)

import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
from agent_framework_engram import EngramMiddleware


async def main() -> None:
    agent = Agent(
        client=OpenAIChatClient(),
        name="assistant",
        instructions="You are a helpful assistant with long-term memory.",
        middleware=[EngramMiddleware(bucket="my-agent")],
    )

    print(await agent.run("Hi, my name is Jacob."))
    print(await agent.run("What's my name?"))


asyncio.run(main())

Configuration

Argument	Env var	Default
api_key	ENGRAM_API_KEY	required
base_url	ENGRAM_BASE_URL	https://api.lumetra.io
bucket	—	required

For multi-tenant deployments, use one bucket per user (e.g. f"user-{user_id}").

Tools exposed by EngramTools

Tool	Maps to
engram_store_memory	POST /v1/buckets/{bucket}/memories
engram_query_memory	POST /v1/query
engram_list_memories	GET /v1/buckets/{bucket}/memories
engram_delete_memory	DELETE /v1/buckets/{bucket}/memories/{memory_id}
engram_clear_bucket	DELETE /v1/buckets/{bucket}/memories
engram_list_buckets	GET /v1/buckets

Restrict with EngramTools(bucket=..., include=("store_memory", "query_memory")) if you only want recall/persist (no destructive ops).

Migrating from EngramSkill

# Before (still works, emits DeprecationWarning):
from agent_framework_engram import EngramSkill
skill = EngramSkill(bucket="my-agent")

# After:
from agent_framework_engram import EngramTools
memory = EngramTools(bucket="my-agent")

The constructor signature and .tools property are unchanged.

Self-hosted Engram

EngramTools(bucket="x", base_url="https://engram.your-corp.internal")

License

MIT — see LICENSE. Privacy notes in PRIVACY.md.