beeai-framework-engram 0.1.0

Engram memory integration for the BeeAI framework — durable, explainable memory for agents.

beeai-framework-engram

Engram memory integration for the BeeAI framework.

EngramMemory is a BaseMemory implementation that persists every chat message your agent sees to Engram — Lumetra's durable, explainable memory service. Messages survive process restarts, are searchable via the Engram API, and can be cleared per-bucket.

Install

pip install beeai-framework-engram

Quick start

import asyncio
import os

from beeai_framework.backend.message import UserMessage, AssistantMessage
from beeai_framework_engram import EngramMemory

os.environ["ENGRAM_API_KEY"] = "eng_live_..."  # or pass api_key=... below

async def main() -> None:
    memory = EngramMemory(bucket="my-agent")
    await memory.add(UserMessage("My favorite color is blue."))
    await memory.add(AssistantMessage("Got it, I'll remember that."))

    # Restart the process — messages are still there.
    fresh = EngramMemory(bucket="my-agent")
    print([m.text for m in fresh.messages])

asyncio.run(main())

With a BeeAI agent

import asyncio
import os

from beeai_framework.agents.react import ReActAgent
from beeai_framework.backend.chat import ChatModel
from beeai_framework.tools.search.duckduckgo import DuckDuckGoSearchTool
from beeai_framework_engram import EngramMemory

async def main() -> None:
    llm = ChatModel.from_name("ollama:granite3.3:8b")
    agent = ReActAgent(
        llm=llm,
        tools=[DuckDuckGoSearchTool()],
        memory=EngramMemory(bucket="my-react-agent"),
    )
    result = await agent.run("What did we talk about last time?")
    print(result.result.text)

asyncio.run(main())

Configuration

Argument	Env var	Default	Notes
bucket	—	"default"	Engram bucket name. Pick one per agent / per user.
api_key	ENGRAM_API_KEY	—	Required.
base_url	ENGRAM_BASE_URL	https://api.lumetra.io	Override for self-hosted.
hydrate	—	True	Load existing memories from the bucket on construction.
hydrate_limit	—	200	Cap on hydrated messages.
timeout	—	30.0	HTTP timeout (seconds).

API reference

EngramMemory implements the full BaseMemory contract: messages, add, delete, reset, add_many, delete_many, splice, is_empty, clone, and as_read_only. It also exposes:

• await memory.query("...") — ask Engram a question over this bucket; returns the raw JSON response ({success, answer, ...}).
• memory.bucket, memory.base_url — read-only accessors.

reset() clears the entire Engram bucket — use a per-agent / per-user bucket name to avoid wiping shared memory.

Privacy

See PRIVACY.md. The integration only talks to the Engram base URL you configured; no other services are contacted.

License

MIT — see LICENSE.