MCP Server

Use Engram as a memory tool in Claude Desktop, Cursor, Windsurf, and any MCP-compatible host.

Engram ships an MCP (Model Context Protocol) server that exposes memory operations as tools and resources. Any MCP-compatible host — Claude Desktop, Cursor, Windsurf, or your own agent — can use it to give AI sessions persistent memory.

Install

Download the latest binary for your platform from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/Harshitk-cp/engram/releases/latest/download/engram-mcp-darwin-arm64 -o engram-mcp
chmod +x engram-mcp && sudo mv engram-mcp /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/Harshitk-cp/engram/releases/latest/download/engram-mcp-darwin-amd64 -o engram-mcp
chmod +x engram-mcp && sudo mv engram-mcp /usr/local/bin/

# Linux (amd64)
curl -L https://github.com/Harshitk-cp/engram/releases/latest/download/engram-mcp-linux-amd64 -o engram-mcp
chmod +x engram-mcp && sudo mv engram-mcp /usr/local/bin/

You need a running Engram server to connect to. See Docker Compose to start one locally, or point at your production deployment.

---

Configuration

All configuration is via environment variables — there are no --api-key or --agent-id flags:

Variable	Required	Default	Description
ENGRAM_API_KEY	Yes	—	API key (mk_... or rk_...)
ENGRAM_API_URL	No	http://localhost:8080	Engram server URL
ENGRAM_AGENT_ID	No	—	Default agent ID used when a tool call omits agent_id

---

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "engram": {
      "command": "engram-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "ENGRAM_API_URL": "http://localhost:8080",
        "ENGRAM_API_KEY": "mk_your_key_here",
        "ENGRAM_AGENT_ID": "your-agent-id"
      }
    }
  }
}

Restart Claude Desktop. Engram tools will appear in the tool selector.

---

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "engram": {
      "command": "engram-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "ENGRAM_API_URL": "http://localhost:8080",
        "ENGRAM_API_KEY": "mk_your_key_here",
        "ENGRAM_AGENT_ID": "cursor-assistant"
      }
    }
  }
}

---

Available tools

remember

Store a memory for an agent.

Parameters:

Parameter	Type	Required	Description
content	string	Yes	What to remember. Be specific and self-contained — retrieved by semantic similarity.
type	string	No	fact, preference, decision, or constraint. Defaults to fact.
source	string	No	Where this came from: user, agent, tool. Defaults to agent.
confidence	number	No	Certainty 0.0–1.0. See guidance below.
anchor	string	No	Who/what this is about — your own id for a subject (customer/guest/patient). Binds the memory to that subject; auto-created on first use. Omit for the agent’s general memory.
session_id	string	No	Bind to a conversation (UUID). Short-term: decays after the session, promoted to the subject’s durable profile if it recurs.
agent_id	string	No	Agent to store for. Uses ENGRAM_AGENT_ID if omitted.

Confidence guidance (the model should reason about this before storing):

Range	When to use
0.85–1.0	User directly stated or confirmed it
0.50–0.85	Inferred from context — probable but not explicit
0.20–0.50	Speculative, hedged language (“might”, “possibly”)
omit	Let the server assign based on provenance

Response includes: memory ID, content, tier (hot/warm/cold), confidence, tier reason, and whether an existing memory was reinforced.

---

recall

Retrieve memories semantically similar to a query.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Natural language query.
top_k	integer	No	Max results (1–50). Defaults to 10.
anchor	string	No	Restrict recall to one subject (your own customer/guest/patient id). Returns only that subject’s memory + the agent’s private notes + tenant canon — never another subject’s. Omit for the agent’s general memory.
session_id	string	No	Fold a conversation’s short-term memory into recall (UUID). Composes the subject’s durable profile + this session’s recent context.
agent_id	string	No	Agent to recall from. Uses ENGRAM_AGENT_ID if omitted.

Response: ranked list of memories with ID, content, type, confidence, binding (private/anchored/session/canon), and similarity score.

anchor + session_id enable multi-subject memory: one agent can serve thousands of isolated subjects. See Subjects, Sessions & Canon for the full model.

---

recall_graph

Recall using hybrid vector + knowledge graph search. Graph traversal surfaces related memories that pure embedding search misses — useful for “what do I know about this user’s work setup?” style queries where the answer spans multiple connected facts.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Natural language query.
top_k	integer	No	Max results (1–50). Defaults to 10.
graph_weight	number	No	Weight of graph vs. vector search (0–1). Defaults to 0.4.
agent_id	string	No	Agent to recall from. Uses ENGRAM_AGENT_ID if omitted.

---

forget

Delete a memory by ID.

Parameters:

Parameter	Type	Required	Description
memory_id	string	Yes	UUID of the memory to delete.

---

get_hot_context

Get the highest-confidence (hot-tier) memories for an agent, formatted for system prompt injection. Call this at the start of a session to load established context about the user.

Parameters:

Parameter	Type	Required	Description
agent_id	string	No	Agent to retrieve context for. Uses ENGRAM_AGENT_ID if omitted.
limit	integer	No	Max hot memories to include (1–50). Defaults to 10.

Response: numbered list of memories with type and confidence score, formatted for prompt injection.

---

list_agents

List all agents registered under your API key. Takes no parameters.

---

Resources

Engram also exposes two MCP resources that host applications can read:

engram://agents/{agent_id}/memories

Returns the hot-tier memories for an agent as JSON — the highest-confidence context the agent has about a user.

engram://agents/{agent_id}/health

Returns a plain-text snapshot of the agent’s memory state: hot-tier count and top memories by confidence.

---

SSE and HTTP transports

The default transport is stdio (for local tool use). For remote or browser-based setups, start the server in SSE or HTTP mode:

# SSE transport — default addr :3742
engram-mcp --transport sse

# Custom address
engram-mcp --transport sse --addr :8090

# HTTP transport
engram-mcp --transport http --addr :8090

Connect from any SSE-capable MCP client at:

http://localhost:3742/sse

Set env vars before running:

export ENGRAM_API_KEY=mk_...
export ENGRAM_AGENT_ID=your-agent-id
engram-mcp --transport sse

---

Troubleshooting

Tools not appearing in Claude Desktop

1. Verify engram-mcp is in your PATH: which engram-mcp
2. Check the Engram server is running: curl http://localhost:8080/health
3. Confirm ENGRAM_API_KEY is set in the env block of your config (not as a flag)
4. Fully quit Claude Desktop from the menu bar and relaunch

Connection refused or engram API error

The MCP server cannot reach your Engram instance. Check that ENGRAM_API_URL matches where your server is running. Default is http://localhost:8080 if the variable is not set.

Authentication error

Your API key is invalid or revoked. Generate a new one:

from engram import Engram
client = Engram(base_url="http://localhost:8080", api_key="mk_existing_key")
new_key = client.keys.create(name="mcp", scopes=["read", "write"])
print(new_key.api_key)

No agent ID — tools returning wrong results

If ENGRAM_AGENT_ID is not set and a tool call omits agent_id, the server uses an empty string. Either set ENGRAM_AGENT_ID in the env block, or always pass agent_id explicitly in tool calls.