# Notion Memory MCP 🧠

**A Model Context Protocol server that turns Notion into a programmable memory tier for AI agents.**

Give any MCP-compatible agent (Hermes, Claude Desktop, Cursor, custom agents) five clean tools to search, read, save, append, and query your Notion workspace — making Notion the persistent "disk" layer of an agent's 3-tier memory architecture.

```
⚡ L1 cache  → agent built-in memory (always in context)
🧮 RAM       → mem0 / vector store (auto recall)
💾 DISK      → Notion via this MCP ← you are here
```

## Why

Agent memory solutions (mem0, honcho...) are opaque — great for reflexive recall, invisible to humans. Notion is the opposite: fully visible and editable by humans, but not natively tool-callable.

This server bridges them: **agents get programmatic access; humans keep full visual control.**

## Tools exposed

| Tool | What it does |
|---|---|
| `notion_search(query)` | Find pages/databases by title or content |
| `notion_read(page_id)` | Read a page as structured plain text |
| `notion_save(title, content)` | Upsert page by exact title (markdown-ish → blocks) |
| `notion_append(page_id, text)` | Append to a page (running logs) |
| `notion_query_db(db_id)` | Query database rows with optional select-filter |

## Setup

```bash
pip install -r requirements.txt
export NOTION_API_TOKEN=ntn_your_integration_token   # notion.so/my-integrations
python3 server.py                                     # stdio transport
```

### Hermes Agent
```bash
hermes mcp add notion-memory -- python3 /path/to/server.py
# with env: NOTION_API_TOKEN set in ~/.hermes/.env
```

### Claude Desktop / Cursor
Add to your MCP config:
```json
{
  "mcpServers": {
    "notion-memory": {
      "command": "python3",
      "args": ["/path/to/server.py"],
      "env": { "NOTION_API_TOKEN": "ntn_..." }
    }
  }
}
```

## Design decisions

- **Upsert-by-title** (`notion_save`): agents think in names, not UUIDs. Re-saving replaces the body — idempotent writes.
- **Markdown-ish → blocks**: headings (#), bullets (-), paragraphs map to native Notion blocks. No complex AST.
- **Read-open, write-scoped**: reads hit whatever the integration can see; create/update only. No delete tool by design — destructive ops stay human-only.
- **stdlib + httpx + mcp**: minimal dependencies, easy audit.

## Skills demonstrated

MCP server development · async Python (httpx + asyncio) · Notion API (search/blocks/databases) · protocol design for LLM tool use · defensive API error mapping

## License

MIT — built by [Shahjalal Shanto](https://github.com/shahjalal2313)

*Part of an agent-memory architecture: built-in cache + mem0 RAM + Notion disk.*