Skip to content

Agent Frameworks

Integrate Engram with LangChain, LlamaIndex, and other frameworks

Agent Frameworks

Integrate Engram Memory into popular AI and web frameworks. All examples use the official SDKs (Python, JavaScript).


LangChain

Custom memory class that gives LangChain agents persistent, semantic memory.

from langchain.memory import BaseMemory
from langchain.schema import BaseMessage, HumanMessage, AIMessage
from engrammemory import Engram
from pydantic import Field


class EngramMemory(BaseMemory):
    """LangChain memory backed by Engram."""

    client: Engram = Field(exclude=True)
    collection: str = "langchain"
    memory_key: str = "history"
    top_k: int = 5

    @property
    def memory_variables(self) -> list[str]:
        return [self.memory_key]

    def load_memory_variables(self, inputs: dict) -> dict:
        query = inputs.get("input", inputs.get("question", ""))
        if not query:
            return {self.memory_key: []}

        results = self.client.search(
            query=query,
            limit=self.top_k,
            collection=self.collection,
        )
        messages = []
        for mem in results.memories:
            if mem.metadata.get("role") == "human":
                messages.append(HumanMessage(content=mem.content))
            else:
                messages.append(AIMessage(content=mem.content))
        return {self.memory_key: messages}

    def save_context(self, inputs: dict, outputs: dict) -> None:
        self.client.store(
            text=inputs.get("input", ""),
            metadata={"role": "human"},
            collection=self.collection,
        )
        self.client.store(
            text=outputs.get("output", ""),
            metadata={"role": "ai"},
            collection=self.collection,
        )

    def clear(self) -> None:
        self.client.forget(query="*", collection=self.collection)

Usage with an agent:

from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from engrammemory import Engram

client = Engram(api_key="pr_live_xxxxx")
memory = EngramMemory(client=client, collection="support-bot")

llm = ChatOpenAI(model="gpt-4o")
agent = create_openai_tools_agent(llm, tools=your_tools, prompt=your_prompt)
executor = AgentExecutor(agent=agent, tools=your_tools, memory=memory)

response = executor.invoke({"input": "What did we discuss about auth?"})

LlamaIndex

Use Engram as a vector store backend for LlamaIndex document retrieval.

from llama_index.core import VectorStoreIndex, StorageContext
from llama_index.core.vector_stores.types import (
    BasePydanticVectorStore,
    VectorStoreQuery,
    VectorStoreQueryResult,
)
from llama_index.core.schema import TextNode
from engrammemory import Engram


class EngramVectorStore(BasePydanticVectorStore):
    """LlamaIndex vector store backed by Engram."""

    stores_text: bool = True
    is_embedding_query: bool = False

    _client: Engram
    _collection: str

    def __init__(self, api_key: str, collection: str = "llamaindex"):
        super().__init__()
        self._client = Engram(api_key=api_key)
        self._collection = collection

    def add(self, nodes: list[TextNode], **kwargs) -> list[str]:
        ids = []
        for node in nodes:
            result = self._client.store(
                text=node.get_content(),
                metadata=node.metadata,
                collection=self._collection,
            )
            ids.append(result.id)
        return ids

    def delete(self, ref_doc_id: str, **kwargs) -> None:
        self._client.forget(memory_id=ref_doc_id, collection=self._collection)

    def query(self, query: VectorStoreQuery, **kwargs) -> VectorStoreQueryResult:
        results = self._client.search(
            query=query.query_str,
            limit=query.similarity_top_k,
            collection=self._collection,
        )
        nodes = []
        scores = []
        ids = []
        for mem in results.memories:
            nodes.append(TextNode(text=mem.content, metadata=mem.metadata))
            scores.append(mem.score)
            ids.append(mem.id)
        return VectorStoreQueryResult(nodes=nodes, similarities=scores, ids=ids)

Usage:

vector_store = EngramVectorStore(api_key="pr_live_xxxxx", collection="docs")
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex([], storage_context=storage_context)

# Add documents
from llama_index.core import Document
index.insert(Document(text="Engram uses proprietary compression for vectors."))

# Query
query_engine = index.as_query_engine()
response = query_engine.query("How does Engram compress vectors?")

FastAPI

Middleware that injects an Engram client into every request.

from fastapi import FastAPI, Request, Depends
from contextlib import asynccontextmanager
from engrammemory import AsyncEngram


@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.engram = AsyncEngram(api_key="pr_live_xxxxx")
    yield


app = FastAPI(lifespan=lifespan)


def get_engram(request: Request) -> AsyncEngram:
    return request.app.state.engram


@app.post("/chat")
async def chat(message: str, engram: AsyncEngram = Depends(get_engram)):
    # Recall relevant context
    context = await engram.search(query=message, limit=5)
    memories = [m.content for m in context.memories]

    # Generate response (your LLM call here)
    response = await generate_response(message, memories)

    # Store the exchange
    await engram.intelligence(
        text=f"User: {message}\nAssistant: {response}",
    )

    return {"response": response, "context_used": len(memories)}


@app.get("/memories")
async def list_memories(
    query: str,
    limit: int = 10,
    engram: AsyncEngram = Depends(get_engram),
):
    results = await engram.search(query=query, limit=limit)
    return {"memories": [m.content for m in results.memories]}

Express.js

Middleware that attaches an Engram client to req.engram.

import express from 'express';
import { Engram } from 'engrammemory-ai';

const app = express();
app.use(express.json());

// Engram middleware
const engram = new Engram({ apiKey: process.env.ENGRAM_API_KEY! });

app.use((req, res, next) => {
  req.engram = engram;
  next();
});

app.post('/chat', async (req, res) => {
  const { message } = req.body;

  // Recall relevant context
  const context = await req.engram.search(message, { limit: 5 });
  const memories = context.memories.map(m => m.content);

  // Generate response (your LLM call here)
  const response = await generateResponse(message, memories);

  // Store the exchange
  await req.engram.intelligence(
    `User: ${message}\nAssistant: ${response}`
  );

  res.json({ response, contextUsed: memories.length });
});

app.listen(3000);

Add the type declaration for TypeScript:

declare global {
  namespace Express {
    interface Request {
      engram: Engram;
    }
  }
}

OpenAI Function Calling

Give any OpenAI-powered agent persistent memory through function calling.

import openai
from engrammemory import Engram
import json

engram = Engram(api_key="pr_live_xxxxx")
oai = openai.OpenAI()

# Define Engram tools for the model
tools = [
    {
        "type": "function",
        "function": {
            "name": "memory_store",
            "description": "Store information for later recall.",
            "parameters": {
                "type": "object",
                "properties": {
                    "text": {"type": "string", "description": "Content to remember"},
                    "category": {"type": "string", "description": "Category label"},
                },
                "required": ["text"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "memory_search",
            "description": "Search stored memories by semantic similarity.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search query"},
                    "limit": {"type": "integer", "description": "Max results"},
                },
                "required": ["query"],
            },
        },
    },
]


def handle_tool_call(name: str, args: dict) -> str:
    if name == "memory_store":
        result = engram.store(text=args["text"], category=args.get("category"))
        return json.dumps({"stored": True, "id": result.id})
    elif name == "memory_search":
        results = engram.search(query=args["query"], limit=args.get("limit", 5))
        return json.dumps([
            {"content": m.content, "score": m.score}
            for m in results.memories
        ])
    return json.dumps({"error": "unknown tool"})


# Conversation loop
messages = [{"role": "user", "content": "Remember that I prefer Python over JS."}]

response = oai.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
)

# Process tool calls
for tool_call in response.choices[0].message.tool_calls or []:
    args = json.loads(tool_call.function.arguments)
    result = handle_tool_call(tool_call.function.name, args)
    messages.append(response.choices[0].message)
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": result,
    })

# Get final response
final = oai.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
print(final.choices[0].message.content)

Next Steps