engram-camel-ai 0.1.0

Engram (Lumetra) memory recipe for CAMEL-AI — durable chat history backend + in-agent memory tools.

engram-camel-ai

Engram (Lumetra) memory recipe for CAMEL-AI.

Two integration patterns, designed to be used together:

1. Chat-history persistence via EngramKeyValueStorage, a drop-in BaseKeyValueStorage you slot into CAMEL's own ChatHistoryMemory. The full transcript survives process restarts in an Engram bucket.
2. In-thread memory tools via make_engram_tools(), returning CAMEL FunctionTools (store_memory + query_memory) the agent can call deliberately during a run.

Both layers use the Engram REST API (https://api.lumetra.io) with one ENGRAM_API_KEY.

Also covers OWL

camel-ai/owl (~25k★, #1 GitHub trending Feb 2026) is built on top of CAMEL — OwlRolePlaying is a direct subclass of CAMEL's RolePlaying, and OWL instantiates standard ChatAgent objects via assistant_agent_kwargs / user_agent_kwargs inside construct_society(). Pass EngramKeyValueStorage and make_engram_tools() through those kwargs and your OWL society gets durable memory + recall tools the same way a bare CAMEL agent does:

from engram_camel import EngramKeyValueStorage, make_engram_tools
from camel.memories import ChatHistoryMemory
from owl.utils import construct_society

memory = ChatHistoryMemory(storage=EngramKeyValueStorage(bucket="owl-task"))
tools = make_engram_tools(bucket="owl-task-facts")

society = construct_society(
    task_prompt="...",
    assistant_agent_kwargs={"memory": memory, "tools": tools},
    user_agent_kwargs={"memory": memory},
)

No separate engram-owl package needed.

---

Install

This recipe isn't on PyPI. Clone and pip install -e .:

git clone https://github.com/lumetra-io/engram-camel-ai
cd engram-camel-ai
pip install -e .

You'll also need an Engram API key (sign up at https://lumetra.io):

export ENGRAM_API_KEY=eng_live_...

Usage

from camel.agents import ChatAgent
from camel.memories import ChatHistoryMemory, ScoreBasedContextCreator
from camel.messages import BaseMessage
from camel.models import ModelFactory
from camel.types import ModelPlatformType, ModelType
from camel.utils import OpenAITokenCounter

from engram_camel import EngramKeyValueStorage, make_engram_tools

# 1) Durable chat history (CAMEL's native memory, Engram-backed storage).
memory = ChatHistoryMemory(
    context_creator=ScoreBasedContextCreator(
        token_counter=OpenAITokenCounter(ModelType.GPT_4O_MINI),
        token_limit=4096,
    ),
    storage=EngramKeyValueStorage(bucket="my-agent-history"),
    agent_id="my-agent",
)

# 2) Deliberate fact memory the agent can call as tools.
tools = make_engram_tools(bucket="my-agent-facts")

agent = ChatAgent(
    system_message=BaseMessage.make_assistant_message(
        role_name="Assistant",
        content="You are a helpful assistant with durable memory.",
    ),
    model=ModelFactory.create(
        model_platform=ModelPlatformType.ANTHROPIC,
        model_type=ModelType.CLAUDE_HAIKU_4_5,
    ),
    memory=memory,
    tools=tools,
)

print(agent.step("My name is Jacob — please remember that.").msgs[0].content)

How the two layers differ

	Chat history (storage)	Memory tools
Trigger	Every turn, automatic	Agent decides to call
Granularity	Full transcript blob	One atomic fact per call
Retrieval	Replayed verbatim into context	Hybrid BM25 + vector + graph synthesis
Bucket	One per agent/session	One per project, often shared
Use it for	Resuming conversations	Long-term facts, preferences, decisions

Use them together: history keeps the conversation coherent across restarts, while the tools let the agent surface durable facts from many prior sessions.

Bucket layout

Typical projects use one bucket for chat history per (agent, session) and one shared facts bucket per project:

storage = EngramKeyValueStorage(bucket=f"history-{user_id}-{session_id}")
tools  = make_engram_tools(bucket=f"facts-{project_id}")

Smoke test

export ENGRAM_API_KEY=eng_live_...
export ANTHROPIC_API_KEY=sk-ant-...
python example.py

The script prints the buckets it created and a curl command to verify the memory landed:

curl -s -H "Authorization: Bearer $ENGRAM_API_KEY" \
  https://api.lumetra.io/v1/buckets/<facts-bucket>/memories?limit=10

License

MIT. See LICENSE and PRIVACY.md.