timem-mcp 0.3.3

TiMEM MCP Server - Model Context Protocol server for TiMEM Engine

TiMEM MCP Server

Language: English | 简体中文

Model Context Protocol server for TiMEM Engine, providing memory management tools for AI applications.

Need help configuring MCP? Copy the AI setup prompt into any AI assistant and follow the steps.

Get your API key

Obtain an API key from TiMEM Console.

Set environment variables on your system (recommended — do not hard-code keys in config files):

export TiMEM_API_KEY="your-api-key"
export TiMEM_USER_ID="your-user-id"

Quick Start (Cloud HTTP — recommended)

No local install. Set environment variables, then add this to your MCP client config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "TiMEM-MCP": {
      "url": "https://api.timem.cloud/mcp",
      "headers": {
        "X-API-Key": "${env:TiMEM_API_KEY}",
        "X-TiMEM-User-Id": "${env:TiMEM_USER_ID}"
      }
    }
  }
}

Restart your MCP client. Expect 7 tools: create_memory, classify_memory_scene, search_memories, should_search_memories, should_create_memory, delete_memory, ready.

Coding scene guide: MCP resource timem://guides/coding-memory · docs

Guide: cursor_en.md · 中文版

Quick Start (Local stdio — optional)

For offline development, install from GitHub; PyPI timem-mcp==0.3.2 is also available.

1. Install timem-mcp

Option A — clone + pip:

git clone https://github.com/TiMEM-AI/timem-mcp.git
cd timem-mcp
git checkout v0.2.0
pip install -e .

Option B — uvx from GitHub (requires uv; no clone needed):

uvx --from git+https://github.com/TiMEM-AI/timem-mcp@v0.2.0 timem-mcp

Full guide: from_github_en.md · 中文版

2. Configure your MCP client

Client	Guide
Cursor	cursor_en.md · 中文
Claude Desktop	claude_desktop.md
All clients (paths)	mcp_clients_en.md · 中文

Copy an example config:

• clone + pip: .cursor/mcp.json.example
• uvx from git: .cursor/mcp.json.example.from-git

On Windows with conda, set command to the full path of your python.exe.

3. Verify

Fully quit and restart your client. Confirm 7 tools: create_memory, classify_memory_scene, search_memories, should_search_memories, should_create_memory, delete_memory, ready. Run ready to check API connectivity.

Cursor deeplink (optional)

python scripts/generate_cursor_deeplink.py local       # clone + pip
python scripts/generate_cursor_deeplink.py from-source # uvx from GitHub

Optional: Cursor Rules

Add .cursor/rules/timem-memory.mdc to your project so Agent calls memory tools proactively.

Tool reference: tools_en.md · 中文

Quick Start: PyPI (optional)

When published to PyPI:

{
  "mcpServers": {
    "TiMEM-MCP-0.2.0": {
      "type": "stdio",
      "command": "uvx",
      "args": ["timem-mcp"],
      "env": {
        "TiMEM_API_KEY": "${env:TiMEM_API_KEY}",
        "TiMEM_USER_ID": "${env:TiMEM_USER_ID}",
        "TiMEM_API_HOST": "https://api.timem.cloud"
      }
    }
  }
}

Deeplink: python scripts/generate_cursor_deeplink.py pypi

Configuration

Variable	Required	Default	Description
TiMEM_API_KEY	Yes	-	TiMEM Engine API key
TiMEM_USER_ID	Recommended	-	Default user ID (overridable per tool call)
TiMEM_API_HOST	No	https://api.timem.cloud	API endpoint
TiMEM_MEMORY_TASK_POLL_INTERVAL_SECONDS	No	1.0	Poll interval for async memory generation
TiMEM_MEMORY_TASK_MAX_WAIT_SECONDS	No	60.0	Max wait for async memory generation
TIMEM_AUTO_SCENE	No	unset	Set to 1 to enable automatic scene classification on create_memory

Both TiMEM_* and TIMEM_* prefixes are supported (TiMEM_* takes priority).

Available tools

create_memory

Create memories from conversation history. Backend accepts HTTP 202 and generates in the background; this server polls until complete.

When TIMEM_AUTO_SCENE=1 is set and domain is omitted, the conversation is automatically classified into one of general, coding, or writing via MCP sampling.

Parameters: messages, session_id, optional user_id, expert_id, domain (general/coding/writing), memory_hint (coding: decision/constraint/lesson/…), wait_for_completion

API: POST /api/v1/memory/ → GET /api/v1/memory/memory-generation/tasks/{task_id}

classify_memory_scene

Explicitly classify a conversation into a memory scene (general, coding, or writing). Useful when you want to decide the scene before calling create_memory.

Parameters: messages

search_memories

Enhanced semantic memory search. domain=coding maps to character_id=coder on the backend. For coding tasks, see Search Tier in timem://guides/coding-memory.

Parameters: query_text (required for semantic search), layer, user_id, session_id, limit, enable_memories_rethink, optional domain, optional keywords

API: POST /api/v1/memory/search

should_search_memories

Coding-scene Search Tier (S0–S6 / S-skip) gating. Local heuristics only — no backend call. Returns whether to search and a suggested query_text.

Parameters: user_input, optional session_id

should_create_memory

Coding-scene implicit create checklist helper. Local heuristics only — does not write memory.

Parameters: user_input

delete_memory

Soft-delete a single memory by ID. No hard_delete or bulk delete.

When to use: User explicitly asks to forget/remove a memory; confirm memory_id from search or create first.

Parameters: memory_id

API: DELETE /api/v1/memory/{memory_id}

ready

Health check for MCP config and TiMEM API connectivity.

Other MCP clients

Claude Desktop, Windsurf, Cline, and other stdio MCP clients use the same JSON shape. See mcp_clients_en.md for config paths and AI setup prompt for guided setup.

Development

pip install -e ".[dev]"
pytest tests/ -m "not live" -v
pytest tests/ -m live -v                # requires backend + credentials
pytest tests/test_mcp_stdio.py -v       # confirms 7 MCP tools

MCP Inspector (manual testing):

npx @modelcontextprotocol/inspector python -m timem_mcp

See docs/tools_en.md for per-field Inspector examples.

Contributing

See CONTRIBUTING.md. Security: SECURITY.md. Changes: CHANGELOG.md.

License

MIT License — see LICENSE.