timem-mcp 0.9.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 17 tools: 5 memory tools (create_memory, classify_memory_scene, search_memories, delete_memory, ready), 8 public rule-learning tools, and 4 knowledge-base tools. For coding memory orchestration, install timem-skill timem-coding-memory.

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 17-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 17 tools including create_memory, search_memories, learn_rule, recall_rules, get_rule_usage_report, search_knowledge, and ready. Run ready to check API connectivity. Coding orchestration: install timem-skill timem-coding-memory.

Cursor deeplink (optional)

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

Optional: timem-skill (Cursor)

Install timem-skill timem-coding-memory + shared into .cursor/skills/. See agent-adapters.md.

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
TiMEM_MCP_TOOL_PROFILE	No	full	Static server-side tool filter: full, memory, rule, knowledge, or a comma-separated combination

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

Optional Tool Profiles

Tool Profiles reduce the schemas returned by MCP tools/list when an Agent only needs part of TiMEM. They are opt-in; omitting the variable preserves the full 17-tool surface.

Profile	Visible tools
full (default)	17 tools
rule	8 Rule tools + ready (9 total)
memory	4 Memory tools + ready (5 total)
knowledge	4 Knowledge tools + ready (5 total)
memory,rule	both domains + ready (13 total)

For a Rule-only stdio client, add "TiMEM_MCP_TOOL_PROFILE": "rule" to the server's env object and fully restart the client. ready, MCP Resources, and MCP Prompts remain available in every profile. Read timem://capabilities for the active profile and exact tool list, or timem://guides/tool-profiles for configuration help.

Profiles are fixed when a server instance starts and are a context optimization, not an authorization boundary. Shared HTTP deployments should mount a dedicated server instance or endpoint for each offered profile.

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).
• search_memories — semantic search; coding scene uses Search Tier from timem-skill before calling.
• create_memory — persist memories after WRITE EVAL (timem-skill write rubric).
• delete_memory — soft-delete one memory by ID.
• ready — check MCP config and TiMEM API connectivity.

Rule-learning tools

• learn_rule — create a reusable rule from situation_text and outcome_text.
• recall_rules — recall relevant rules from one query_text; default similarity is retrieval-only, while judged and auto add applicability checks.
• 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.
• get_rule_usage_report — inspect the authenticated user's aggregate or daily learn/recall usage, including recall billable tokens.

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 the default 17-tool surface

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.