integrations/mcp/v0.1.0

# Release Notes for v0.1.0

This is the **initial release** of **Memanto MCP** — a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes Memanto's semantic long-term memory to any MCP-compatible agent. With a single config line, MCP clients (Claude Desktop, Cursor, Windsurf, Cline, Continue, Goose, and custom hosts) gain typed semantic memory across sessions, sub-90 ms retrieval, conflict detection, and instant ingestion — all backed by Moorcheh.ai's no-indexing semantic database.

## Improvements

### MCP Memory Tools
- **`remember`**: Persist a single fact, preference, decision, goal, or instruction with optional memory type, provenance, and confidence.
- **`batch_remember`**: Ingest up to 100 memories in one call (ideal for document extraction or bulk imports).
- **`recall`**: Semantic search across the agent's memory — agents should always check here before asking the user to repeat stable information.
- **`recall_recent`**: Newest-first retrieval with no query needed ("what did we just decide?").
- **`recall_as_of`**: Point-in-time recall — "what did we know on 2025-11-01?"
- **`recall_changed_since`**: Differential recall — "what's new since I last checked?"
- **`answer`**: Grounded RAG response synthesized over the agent's memories, no extra LLM key required.
- **13 typed memory categories**: `fact`, `preference`, `goal`, `decision`, `artifact`, `learning`, `event`, `instruction`, `relationship`, `context`, `observation`, `commitment`, `error`.
- **Provenance metadata** on every write: `explicit_statement`, `inferred`, `corrected`, `validated`, `observed`, `imported`.

### Agent Admin Tools (opt-in)
Enabled by setting `MEMANTO_EXPOSE_ADMIN=true`:
- **`create_agent`**: Create a new memory namespace from the client.
- **`list_agents`**: List every agent the API key can see.
- **`get_agent`**: Look up an agent's metadata.
- **`delete_agent`**: Remove an agent's local metadata.

### Installation & Quickstart
- One-line install via `pip install memanto-mcp` (Python 3.10+).
- Drop-in `mcpServers` JSON snippet works across Claude Desktop, Cursor, Windsurf, Cline, Continue, and Goose:
  ```json
  {
    "mcpServers": {
      "memanto": {
        "command": "memanto-mcp",
        "env": {
          "MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
          "MEMANTO_DEFAULT_AGENT_ID": "my-assistant"
        }
      }
    }
  }
  ```
- First call **auto-creates** the default agent and namespace; every subsequent call reuses the same persistent memory.
- Get your Moorcheh API key from the [console](https://console.moorcheh.ai/api-keys) (free tier: 100K ops/month).

### Transports & Deployment
- **stdio** (default) for local IDE/desktop integrations.
- **Streamable HTTP** for modern remote and multi-process setups: `memanto-mcp --transport streamable-http --host 0.0.0.0 --port 8765`.
- **Server-Sent Events (SSE)** for legacy clients.
- CLI flags override environment variables for ergonomic per-launch tweaks.

### Session & Lifecycle Management
- JWT sessions activate lazily on the first memory tool call and **auto-renew before expiry**, so long-running MCP connections never hit a session-expired error mid-conversation.
- Sessions are intentionally **kept alive on shutdown** — other Memanto clients (CLI, REST) can share them within their TTL window.
- Configurable session lifetime via `MEMANTO_SESSION_DURATION_HOURS` (default 6).
- Stderr-only logging keeps stdout reserved for JSON-RPC traffic — no risk of garbled output in stdio mode.

### Configuration
Full environment-driven config (process env → `.env` file in the working directory):

| Variable | Required | Default | Description |
|---|---|---|---|
| `MOORCHEH_API_KEY` | **yes** | — | Moorcheh API key. |
| `MEMANTO_DEFAULT_AGENT_ID` | recommended | _none_ | Default agent — when set, tool calls may omit `agent_id`. |
| `MEMANTO_AGENT_PATTERN` | no | `tool` | Pattern (`support` / `project` / `tool`) used when auto-creating the default agent. |
| `MEMANTO_AGENT_AUTO_CREATE` | no | `true` | Auto-create the default agent on first use if missing. |
| `MEMANTO_SESSION_DURATION_HOURS` | no | `6` | Session lifetime in hours. |
| `MEMANTO_EXPOSE_ADMIN` | no | `false` | Register the 4 agent-management tools. |
| `MEMANTO_MCP_TRANSPORT` | no | `stdio` | `stdio`, `sse`, or `streamable-http`. |
| `MEMANTO_MCP_HOST` | no | `127.0.0.1` | Bind host for sse/http transports. |
| `MEMANTO_MCP_PORT` | no | `8765` | Bind port for sse/http transports. |
| `MEMANTO_MCP_LOG_LEVEL` | no | `INFO` | Log level. |

### Programmatic Embedding
- Embed the server directly inside a custom MCP host:
  ```python
  from memanto_mcp import MCPServerSettings, build_server

  settings = MCPServerSettings()        # reads env / .env
  mcp = build_server(settings)

  # Add your own tools alongside Memanto's, then run.
  mcp.run(transport="stdio")
  ```
- Built on the same `memanto.cli.client.SdkClient` used by the Memanto CLI — shared session and auth semantics.

### Client Coverage
Drop-in configs verified for:
- **Claude Desktop** — `claude_desktop_config.json`
- **Cursor** — `~/.cursor/mcp.json` (or per-project `.cursor/mcp.json`)
- **Windsurf** — `~/.codeium/windsurf/mcp_config.json`
- **Cline (VS Code)** — `cline_mcp_settings.json`
- **Continue** — `~/.continue/config.json` → `experimental.modelContextProtocolServers`
- **Goose** — `~/.config/goose/config.yaml`
- Any custom MCP host that follows the [standard MCP config shape](https://modelcontextprotocol.io/docs/clients).

### Getting Started

```bash
pip install memanto-mcp
export MOORCHEH_API_KEY=mch_xxxxxxxxxxxxxxxxxx
export MEMANTO_DEFAULT_AGENT_ID=my-assistant
memanto-mcp          # stdio transport, ready for any MCP client
```

Then point your MCP client at the `memanto-mcp` command and ask it to *"remember that I prefer concise answers"* — in a brand-new chat tomorrow, ask *"what do I prefer?"*.

### Documentation
- MCP server README: [`integrations/mcp/README.md`](./README.md)
- Memanto documentation: https://docs.memanto.ai
- Moorcheh base documentation: https://docs.moorcheh.ai
- MCP specification: https://modelcontextprotocol.io

This **v0.1.0** release brings Memanto's typed semantic memory to every MCP-compatible agent — one config line, persistent context across sessions, no infrastructure to operate.