getmnemo-mcp

Model Context Protocol server for Mnemo Memory — exposes long-term memory tools to any MCP client (Claude Desktop, Cursor, Windsurf, VS Code, Zed).

Tools

| Tool | What it does | |---|---| | memory_search | Hybrid 7-strategy retrieval over the workspace memory store. Filter by polarity, searchMode (memories/documents/both), exclude already-seen ids, or opt into precise mode. | | memory_answer | Cited-answer pipeline: question in, synthesized answer + citations out (mode: "fast" for ~1-2s). | | memory_add | Store an atomic fact with optional metadata; polarity: "negative" marks a hard constraint. | | memory_get | Fetch one memory by ID within the configured container. | | memory_update | Patch an existing memory's content, metadata, or polarity. | | memory_delete | Soft-delete a memory by ID so it leaves retrieval. | | memory_restore | Undo a soft delete during its recovery window (API-key sessions only). | | memory_list | Paginate through memories (cursor-based). | | document_add | Ingest a raw document (up to 500,000 characters) into the async extraction lane; returns a jobId. | | job_status | Poll an ingestion job: queued / processing / completed / failed (API-key sessions only). |

Personal-memory tools (0.3.0, Mnemo API v0.3.0)

| Tool | What it does | Key scope(s) | API flag | |---|---|---|---| | daily_brief | Today's reminders, important dates, last-24h captures, follow-ups and meetings for one container. | brief:read | MEMORY_API_BRIEF_ENABLED | | memory_timeline | One container as a time-ordered stream of memories, reminders, documents (and optional events). | timeline:read | MEMORY_API_TIMELINE_ENABLED | | people_list | People the workspace remembers, with memory / open-reminder counts. | people:read | MEMORY_API_PEOPLE_ENABLED | | people_get | One person by slug (contact details, important dates, aliases). | people:read | MEMORY_API_PEOPLE_ENABLED | | people_upsert | Create a person, or update them when the slug already exists. | people:write | MEMORY_API_PEOPLE_ENABLED | | reminder_create | A reminder with a due time, filed under a person or a container. | reminders:write | MEMORY_API_PEOPLE_ENABLED | | reminders_upcoming | Overdue / due-today / upcoming reminders plus important dates, by local day. | reminders:read | MEMORY_API_PEOPLE_ENABLED | | reminder_complete | Mark a reminder done. | reminders:write | MEMORY_API_PEOPLE_ENABLED | | meetings_upcoming | Upcoming Google Calendar meetings with attendees resolved to people. | meetings:read | MEMORY_API_MEETINGS_ENABLED | | meeting_brief | Pre-meeting brief: reader answer with citations, matched people, previous meetings. | meetings:read + answer:read | MEMORY_API_MEETINGS_ENABLED | | memory_merge | Fold 2..20 duplicate memories into one survivor (idempotent on mergeKey). | memories:write + memories:delete | MEMORY_API_INBOX_ENABLED |

These scopes are opt-in: mint (or edit) the API key with them at https://app.mnemohq.com/settings/api-keys. Every feature is dark until the API operator sets its MEMORY_API_* flag; until then the tool returns a 503 FEATURE_DISABLED error that names the flag.

All personal-memory tools except memory_timeline are API-key only: the API rejects hosted OAuth MCP tokens on cross-container routes, so hosted OAuth sessions (https://mcp.mnemohq.com/mcp) do not list them.

Remote HTTP calls are scoped by the user's Mnemo OAuth grant. The user signs in, chooses a workspace and memory container, and the server derives that scope from the access token. The model cannot set or change it.

Install

Local stdio clients

npx -y getmnemo-mcp

Or wire it into the client config directly. Example for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "getmnemo": {
      "command": "npx",
      "args": ["-y", "getmnemo-mcp"],
      "env": {
        "GETMNEMO_API_KEY": "prfly_live_...",
        "GETMNEMO_WORKSPACE_ID": "ws_...",
        "GETMNEMO_CONTAINER_TAG": "user:jane"
      }
    }
  }
}

Get an API key at https://app.mnemohq.com/settings/api-keys.

Hosted remote MCP clients

For clients that support remote MCP and OAuth 2.1, use:

https://mcp.mnemohq.com/mcp

The client should discover OAuth metadata, open Mnemo sign-in, and return to the client after the user selects a workspace and container. No API key, workspace header, or container configuration is required for this path.

Develop

npm install
cp .env.example .env   # fill in API-key/container values for stdio
npm run dev            # stdio
npm run dev:http       # Streamable HTTP on :8787
npm run build          # bundle to dist/
npm run lint && npm run typecheck && npm test

Architecture

• stdio (src/cli.ts): one process per MCP client connection, env-configured.
• Streamable HTTP (src/http.ts): hosted transport for public OAuth sessions, with private API-key compatibility for trusted deployments.
• Both transports share src/server.ts (tool registration + dispatch), src/personal-tools.ts (personal-memory tools) and src/api-client.ts (typed REST wrapper).

The public hosted transport uses Mnemo's OAuth 2.1 authorization server and resource-bound tokens. Header-selected containers remain disabled by default; they are only a private compatibility path for a trusted gateway.

The server deliberately does NOT depend on getmnemo (the JS SDK) so it can ship independently.

License

MIT