Metadata-Version: 2.4
Name: timem-mcp
Version: 0.6.0
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 and rule-learning 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 **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](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 may lag behind GitHub/main, so prefer GitHub when you need the latest 21-tool surface.

### 1. Install timem-mcp

**Option A — clone + pip:**

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

```bash
uvx --from git+https://github.com/TiMEM-AI/timem-mcp@main 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 **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)

```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 `timem-mcp` 0.4.0+ is published to PyPI:

```json
{
  "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](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 21 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).
