timem-mcp 0.2.0

TiMEM MCP Server - Model Context Protocol server for TiMEM Engine

TiMEM MCP Server

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

不会配 MCP？ 复制 AI 接入提示词 发给任意 AI，按步骤完成安装与配置。
English: AI setup prompt

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 (GitHub — recommended)

Install from GitHub; PyPI is optional and can be used later.

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):

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

Full guide: docs/installation/from_github.md（中文）· English

2. Configure your MCP client

Client	Guide
Cursor	docs/installation/cursor.md
Claude Desktop	docs/installation/claude_desktop.md
All clients (paths)	docs/installation/mcp_clients.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 4 tools: create_memory, search_memories, 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: docs/tools_zh.md（中文）· English

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

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.

Parameters: messages, session_id, optional user_id, expert_id, domain

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

search_memories

Enhanced semantic memory search.

Parameters: query_text, layer, user_id, limit, enable_memories_rethink

API: POST /api/v1/memory/search

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.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 4 MCP tools

MCP Inspector (manual testing):

npx @modelcontextprotocol/inspector python -m timem_mcp

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

Contributing

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

License

MIT License — see LICENSE.