Metadata-Version: 2.4
Name: engram-camel-ai
Version: 0.1.0
Summary: Engram (Lumetra) memory recipe for CAMEL-AI — durable chat history backend + in-agent memory tools.
Author-email: Lumetra <hi@lumetra.io>
License: MIT
Project-URL: Homepage, https://lumetra.io
Project-URL: Source, https://github.com/lumetra-io/engram-camel-ai
Keywords: engram,lumetra,camel-ai,camel,memory,agents,multi-agent
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: camel-ai>=0.2.0
Requires-Dist: requests>=2.31
Dynamic: license-file

# engram-camel-ai

Engram ([Lumetra](https://lumetra.io)) memory recipe for [CAMEL-AI](https://github.com/camel-ai/camel).

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
   `FunctionTool`s (`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](https://github.com/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:

```python
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 .`:

```bash
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>):

```bash
export ENGRAM_API_KEY=eng_live_...
```

## Usage

```python
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:

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

## Smoke test

```bash
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:

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

## License

MIT. See [LICENSE](./LICENSE) and [PRIVACY.md](./PRIVACY.md).
