# Engram MCP

Give your AI agents a memory they can trust. Engram lets your AI remember past conversations, facts, and decisions, so it feels more like a real teammate.

This repository contains configuration templates for connecting MCP clients to [Engram](https://lumetra.io), a hosted memory service for AI agents.

## What is Engram?

Engram is a **hosted MCP server** that provides reliable, explainable memory for AI agents:

- **Reliable memory**: Agents remember conversations, facts, and decisions, with automatic knowledge graph extraction
- **Explainable retrieval**: Every answer cites the memories and graph edges that justified it
- **Three-engine retrieval**: BM25 + vector search + knowledge graph, fused and reranked
- **Bring your own model**: All LLM calls route through your provider — no inference markup
- **Built-in controls**: Organize memories into buckets, manage retention, and query with natural language

**Free tier**: 10K stored memories and 50K retrievals per month — no credit card required. See [pricing](https://lumetra.io/pricing) for paid tiers.

## Quick Setup

### 1. Get your API key

Sign up at [lumetra.io](https://lumetra.io) to create an account and generate an API key.

> Some clients (Claude.ai web, ChatGPT) use OAuth instead of a pasted key — see those sections below.

### 2. Add Engram to your MCP client

**MCP endpoint:** `https://mcp.lumetra.io/mcp/sse`

#### Claude Code

```bash
claude mcp add-json engram '{"type":"sse","url":"https://mcp.lumetra.io/mcp/sse","headers":{"Authorization":"Bearer <your-api-key>"}}'
```

#### Claude.ai web (OAuth — no key paste)

In Claude settings → Connectors → **Add custom connector**, paste:

```
https://mcp.lumetra.io/mcp/sse
```

You'll be redirected through Lumetra to authorize the connection. No API key required.

#### ChatGPT web (OAuth — Connector-capable plans)

In ChatGPT settings → **Add custom MCP connector**, paste:

```
https://mcp.lumetra.io/mcp/sse
```

Same OAuth flow as Claude.ai.

#### Cursor

`~/.cursor/mcp.json` or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "engram": {
      "url": "https://mcp.lumetra.io/mcp/sse",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```

#### Windsurf

`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "engram": {
      "url": "https://mcp.lumetra.io/mcp/sse",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```

> Windsurf accepts both `url` and `serverUrl` for remote MCP servers. We use `url` here to match the other clients on this page.

#### OpenCode

`opencode.json`:

```json
{
  "mcpServers": {
    "engram": {
      "url": "https://mcp.lumetra.io/mcp/sse",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```

#### OpenClaw

Once the skill is live on [ClawHub](https://github.com/openclaw/clawhub):

```bash
openclaw skill add lumetra-engram
# or
clawhub install lumetra-engram
```

For now, install manually from [`lumetra-io/engram-openclaw-skill`](https://github.com/lumetra-io/engram-openclaw-skill):

```bash
mkdir -p .openclaw/skills
curl -fsSL https://codeload.github.com/lumetra-io/engram-openclaw-skill/tar.gz/refs/heads/main \
  | tar -xz --strip-components=2 -C .openclaw/skills engram-openclaw-skill-main/skills/engram
export ENGRAM_API_KEY="eng_live_..."
```

### 3. Restart your client

Your MCP client will now have access to Engram memory tools.

## Available Tools

Once connected, your agent has these memory tools:

| Tool | Description |
|------|-------------|
| `store_memory(content, bucket?)` | Store a fact or piece of information (defaults to bucket `"default"`) |
| `query_memory(question, bucket?)` | Search memories using natural language, with AI synthesis and per-memory explanations |
| `list_memories(bucket, limit?)` | List memories in a bucket, newest first (`limit` 1–100, default 20) |
| `list_buckets()` | List available memory buckets |
| `delete_memory(memory_id, bucket)` | Delete a specific memory by ID |
| `clear_memories(bucket)` | Clear all memories in a bucket (destructive!) |

> Multi-bucket query fusion (passing several buckets in one call) is available on the REST `/v1/query` endpoint and in the official SDKs. The MCP `query_memory` tool currently accepts a single bucket per call.

## Recommended Agent Prompt

Add this to your agent's system prompt to encourage effective memory usage:

```
You have Engram Memory. Use it proactively to improve continuity and personalization.

Tools:
- store_memory(content, bucket?) - Store a fact or piece of information
- query_memory(question, bucket?) - Search memories using natural language
- list_memories(bucket, limit?) - List memories in a bucket, newest first
- list_buckets() - List available memory buckets
- delete_memory(memory_id, bucket) - Delete a specific memory
- clear_memories(bucket) - Clear all memories in a bucket (destructive!)

Policy:
- Query-first: before answering anything that may rely on prior context, call query_memory. Ground your answers in the results.
- Proactive storing: capture stable preferences, profile facts, project details, decisions, and outcomes. Keep each fact concise (1-2 sentences).
- Use buckets: organize memories by project or context (e.g., "work", "personal", "project-alpha").

Style for stored content: short, declarative, atomic facts.
Examples:
- "User prefers dark mode."
- "User timezone is US/Eastern."
- "Project Alpha deadline is 2026-10-15."
```

## REST API

Engram also provides a REST API for programmatic access from any HTTP client (Vercel AI SDK, LangChain, LlamaIndex, Mastra, CrewAI, AutoGen, n8n, your own scripts).

**Base URL:** `https://api.lumetra.io`

**Authentication:** Include your API key in the Authorization header:

```bash
curl -X POST https://api.lumetra.io/v1/buckets/default/memories \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Alice works at TechCorp"}'
```

**Quick Example:**

```bash
# Store a memory
curl -X POST https://api.lumetra.io/v1/buckets/work/memories \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Bob is the CEO of Acme Inc"}'

# Query your memories
curl -X POST https://api.lumetra.io/v1/query \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Who is the CEO of Acme?", "buckets": ["work"]}'
```

See the [full API documentation](https://lumetra.io/docs) for all available endpoints.

## Use Cases

Teams use Engram for:

- **Support with prior context**: Carry forward last ticket, environment, plan, and promised follow-ups
- **Code reviews with context**: Store ADRs, owner notes, brittle areas, and post-mortems as memories
- **Shared metric definitions**: Keep definitions, approved joins, and SQL snippets in one place
- **On-brand content, consistently**: Centralize voice and approved claims for writers

## About This Repository

This repository contains:

- This README with setup instructions for popular MCP clients
- `server.json` — MCP server manifest following the official schema

The `server.json` file uses the official MCP server schema and can be used by MCP clients that support remote server discovery. For manual configuration, use the client-specific examples above.

The actual Engram service runs at `https://mcp.lumetra.io` (MCP) and `https://api.lumetra.io` (REST) — there's no local installation required.

## Support

- **Product site**: [lumetra.io](https://lumetra.io)
- **Documentation**: [lumetra.io/docs](https://lumetra.io/docs)
- **Pricing**: [lumetra.io/pricing](https://lumetra.io/pricing)
- **Contact**: support@lumetra.io