timem-mcp 0.5.0

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 and rule-learning 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 21 tools: memory and coding policy tools (create_memory, classify_memory_scene, search_memories, should_search_memories, should_create_memory, delete_memory, ready) plus rule-learning tools such as learn_rule, recall_rules, and record_rule_outcome.

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 may lag behind GitHub/main, so prefer GitHub when you need the latest 21-tool surface.

1. Install timem-mcp

Option A — clone + pip:

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

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

uvx --from git+https://github.com/TiMEM-AI/timem-mcp@main 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 21 tools are listed, including create_memory, should_search_memories, should_create_memory, learn_rule, recall_rules, record_rule_outcome, and 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 timem-mcp 0.4.0+ is published to PyPI:

{
  "mcpServers": {
    "TiMEM-MCP-0.4.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	Yes for memory/rule tools	-	User scope. Cloud HTTP requires X-TiMEM-User-Id; stdio can use env or per-tool user_id.
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

Memory tools

• create_memory — create memories from conversation history (POST /api/v1/memory/ -> task polling).
• classify_memory_scene — classify a conversation as general, coding, or writing.
• search_memories — enhanced semantic memory search (POST /api/v1/memory/search).
• should_search_memories — coding Search Tier gating and suggested query (local heuristics).
• should_create_memory — coding implicit create checklist helper (local heuristics).
• delete_memory — soft-delete one memory by ID.
• ready — check MCP config and TiMEM API connectivity.

Rule-learning tools

• learn_rule — learn or merge a reusable rule from situation_text and outcome_text.
• recall_rules — recall relevant rules for a situation (similarity, judged, or auto mode).
• record_rule_outcome — record whether a recalled rule was helpful and optionally trigger refinement.
• list_rules, get_rule, update_rule, delete_rule — manage rule lifecycle; delete archives the rule.
• list_rule_governance_proposals, resolve_rule_governance_proposal — inspect and resolve governance proposals.
• get_rule_usage_summary, get_rule_usage_daily, get_rule_usage_top_users, list_rule_usage_events, get_rule_usage_event — inspect rule-learning usage metrics.

Rule tools call the backend /api/v1/rules API only; they do not import backend internals. User-scoped rule tools require user_id from the tool parameter, HTTP X-TiMEM-User-Id, or TiMEM_USER_ID; missing user scope returns a validation error instead of falling back to a shared default.

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 21 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.