Skip to main content

​
1. Start the server

The fastest way to run Engram locally is Docker Compose: 
git clone https://github.com/Harshitk-cp/engram
cd engram
cp .env.example .env
# Add your OPENAI_API_KEY (or set EMBEDDING_PROVIDER=mock for testing)
docker compose up -d --wait
The server starts on http://localhost:8080. 
curl http://localhost:8080/health
# {"status":"ok"}

​
2. Install the Python SDK

pip install engram.to

​
3. Bootstrap a tenant

from engram import Engram

# Bootstrap creates a tenant and returns an API key (shown once)
client = Engram(base_url="http://localhost:8080", api_key="")
result = client.setup("my-org", setup_token="your-setup-token")
api_key = result.api_key
print(f"Save this key: {api_key}")
The ENGRAM_SETUP_TOKEN in your .env file controls who can create tenants. Change it before deploying to production.

​
4. Create an agent and store memories

from engram import Engram

client = Engram(
    base_url="http://localhost:8080",
    api_key="mk_your_api_key_here",
)

# Create an agent (one per user, bot, or context)
agent = client.agents.create(
    external_id="user-123",
    name="Alice's Assistant",
)

# Store memories — confidence is assigned automatically based on evidence type
client.memories.store(
    agent_id=agent.id,
    content="User prefers dark mode in all interfaces",
    type="preference",
)

client.memories.store(
    agent_id=agent.id,
    content="User is a backend engineer specialising in distributed systems",
    type="fact",
)

client.memories.store(
    agent_id=agent.id,
    content="User's timezone is UTC+5:30 (Mumbai)",
    type="fact",
)

​
5. Recall memories

# Hybrid vector + graph recall
results = client.memories.recall(
    agent_id=agent.id,
    query="What are this user's technical preferences?",
    top_k=5,
)

for memory in results:
    print(f"[{memory.confidence:.2f}] {memory.content}")

# Output:
# [0.92] User prefers dark mode in all interfaces
# [0.88] User is a backend engineer specialising in distributed systems

​
6. See what happens with contradictions

# Store a fact
client.memories.store(
    agent_id=agent.id,
    content="User's primary language is Python",
    type="fact",
)

# Store a contradicting update — Engram detects the tension
client.memories.store(
    agent_id=agent.id,
    content="User recently switched their primary language to Rust",
    type="fact",
)

# The original memory is now archived; the new one has full confidence
results = client.memories.recall(
    agent_id=agent.id,
    query="What programming language does the user use?",
    top_k=3,
)

​
7. Check knowledge health

# See the overall health of the agent's knowledge
from engram import Engram

health = client.cognitive.health()
print(f"Health score: {health.overall_score}")
print(f"Contradictions: {health.contradiction_count}")
print(f"Stale memories: {health.stale_count}")

​
Next steps

Core Concepts

Understand the 4 memory types, confidence scoring, and decay lifecycle.

MCP Server

Use Engram as a memory tool in Claude Desktop, Cursor, and Windsurf.

LangChain Integration

Drop Engram into your LangChain agent as a production-grade memory backend.