Metadata-Version: 2.4
Name: timem-mcp
Version: 0.3.2
Summary: TiMEM MCP Server - Model Context Protocol server for TiMEM Engine
Project-URL: Homepage, https://github.com/TiMEM-AI/timem-mcp
Project-URL: Documentation, https://docs.timem.cloud
Project-URL: Repository, https://github.com/TiMEM-AI/timem-mcp
Author-email: TiMEM Team <contact@timem.cloud>
License: MIT
License-File: LICENSE
Keywords: ai,mcp,memory,model-context-protocol,timem
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: fastmcp<3.0.0,>=2.14.0
Requires-Dist: httpx<1.0.0,>=0.24.0
Requires-Dist: mcp<2.0.0,>=1.3.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: starlette<2.0.0,>=0.27.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.23.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio<1.0.0,>=0.21.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# TiMEM MCP Server

**Language:** English | [简体中文](README_zh.md)

[Model Context Protocol](https://modelcontextprotocol.io) server for [TiMEM Engine](https://timem.cloud), providing memory management tools for AI applications.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> **Need help configuring MCP?** Copy the [AI setup prompt](docs/installation/ai_setup_prompt_en.md) into any AI assistant and follow the steps.

## Get your API key

Obtain an API key from [TiMEM Console](https://console.timem.cloud).

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

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

```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](docs/guides/coding-memory.md)

Guide: [cursor_en.md](docs/installation/cursor_en.md) · [中文版](docs/installation/cursor.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:**

```bash
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](https://docs.astral.sh/uv/); no clone needed):

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

Full guide: [from_github_en.md](docs/installation/from_github_en.md) · [中文版](docs/installation/from_github.md)

### 2. Configure your MCP client

| Client | Guide |
|--------|-------|
| **Cursor** | [cursor_en.md](docs/installation/cursor_en.md) · [中文](docs/installation/cursor.md) |
| **Claude Desktop** | [claude_desktop.md](docs/installation/claude_desktop.md) |
| **All clients (paths)** | [mcp_clients_en.md](docs/installation/mcp_clients_en.md) · [中文](docs/installation/mcp_clients.md) |

Copy an example config:

- clone + pip: [`.cursor/mcp.json.example`](.cursor/mcp.json.example)
- uvx from git: [`.cursor/mcp.json.example.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)

```bash
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`](.cursor/rules/timem-memory.mdc) to your project so Agent calls memory tools proactively.

Tool reference: [tools_en.md](docs/tools_en.md) · [中文](docs/tools_zh.md)

## Quick Start: PyPI (optional)

When published to PyPI:

```json
{
  "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](docs/installation/mcp_clients_en.md) for config paths and [AI setup prompt](docs/installation/ai_setup_prompt_en.md) for guided setup.

## Development

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

```bash
npx @modelcontextprotocol/inspector python -m timem_mcp
```

See [docs/tools_en.md](docs/tools_en.md) for per-field Inspector examples.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Security: [SECURITY.md](SECURITY.md). Changes: [CHANGELOG.md](CHANGELOG.md).

## License

MIT License — see [LICENSE](LICENSE).
