TeleMem MCP Server

TeleMem ships a Model Context Protocol (MCP) server that exposes its long-term memory operations as MCP tools. Any MCP-compatible client — Claude Desktop, Claude Code, Cursor, custom agents — can store and retrieve memories through a local TeleMem instance.

Installation

pip install "telemem[mcp] @ git+https://github.com/TeleAI-UAGI/telemem.git"
# or, from a source checkout:
pip install -e ".[mcp]"

This installs the MCP Python SDK on top of TeleMem and provides the telemem-mcp console command.

Running the server

telemem-mcp                                      # stdio (default)
telemem-mcp --transport sse --port 8421          # SSE over HTTP
telemem-mcp --transport streamable-http          # Streamable HTTP
TELEMEM_CONFIG=config/config.yaml telemem-mcp    # custom TeleMem config
python -m telemem.mcp                            # equivalent module form

Option	Default	Description
--transport	stdio	One of stdio, sse, streamable-http
--host	127.0.0.1	Bind host for the HTTP transports
--port	8421	Bind port for the HTTP transports
--config	–	TeleMem YAML/JSON config (overrides TELEMEM_CONFIG)

Environment variables

Variable	Default	Description
TELEMEM_CONFIG	–	Path to a TeleMem YAML/JSON config file. Without it, TeleMem's default configuration is used (OpenAI models, local vector store), which needs OPENAI_API_KEY.
TELEMEM_DEFAULT_USER_ID	telemem-mcp	Memory scope used when a tool call provides no user_id/agent_id/run_id.

The TeleMem Memory instance is created lazily on the first tool call, so the server starts instantly and configuration problems surface as structured tool errors instead of crashes.

Tools

Tool	Description
add_memory	Store a fact (text) or conversation (messages) in long-term memory.
search_memories	Semantic search; returns one consolidated text passage (TeleMem fuses related memories).
get_memories	List stored memories with their memory_ids for a user/agent/run.
get_memory	Fetch a single memory by memory_id.
update_memory	Overwrite the text of an existing memory.
delete_memory	Delete a single memory by memory_id.
delete_all_memories	Wipe a scope. Destructive — requires an explicit user_id, agent_id, or run_id.
memory_history	Show the ADD/UPDATE/DELETE history of a memory.

Errors are returned as structured JSON ({"error": ..., "detail": ...}) so agents can self-correct instead of failing opaquely.

TeleMem semantics worth knowing

• search_memories returns a single fused text passage, not ranked rows — this is TeleMem's design (related memories are clustered and merged).
• Conversation-level event memories live under the pseudo-user "events" and are searched automatically alongside the requested user. Use get_memories with user_id="events" to list them.
• When no scope is given, reads and writes default to TELEMEM_DEFAULT_USER_ID; delete_all_memories deliberately never assumes a default.

Client configuration

Claude Desktop / Cursor

Add to claude_desktop_config.json (or Cursor's mcp.json) — see examples/mcp_config.json:

{
  "mcpServers": {
    "telemem": {
      "command": "telemem-mcp",
      "args": [],
      "env": {
        "TELEMEM_CONFIG": "/absolute/path/to/config/config.yaml",
        "TELEMEM_DEFAULT_USER_ID": "your-handle",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Claude Code

claude mcp add telemem -e TELEMEM_CONFIG=/absolute/path/to/config/config.yaml -- telemem-mcp

Python client

examples/mcp_client.py drives the server programmatically over stdio — the quickstart flow (add a conversation, search it) expressed as MCP tool calls:

export OPENAI_API_KEY=sk-...        # or TELEMEM_CONFIG=config/config.yaml
python examples/mcp_client.py

Embedding in your own server

from telemem.mcp import create_server

server = create_server(host="127.0.0.1", port=8421)
server.run(transport="stdio")  # or "sse" / "streamable-http"

Testing

The MCP layer has an offline test suite (no API key required) covering the tool registry, argument mapping, scoping rules, error surfacing, and a full client/server protocol round-trip:

python tests/test_mcp.py