{"id":44427864,"url":"https://github.com/n24q02m/mnemo-mcp","last_synced_at":"2026-08-28T04:05:41.737Z","repository":{"id":337983891,"uuid":"1156058980","full_name":"n24q02m/mnemo-mcp","owner":"n24q02m","description":"Persistent AI memory with hybrid search and embedded sync. Open, free, unlimited.","archived":false,"fork":false,"pushed_at":"2026-08-27T01:44:30.000Z","size":3630,"stargazers_count":10,"open_issues_count":27,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-08-27T03:13:12.490Z","etag":null,"topics":["ai-agents","ai-coding","ai-memory","claude","claude-code","cursor","docker","hybrid-search","mcp","mcp-server","model-context-protocol","open-source","python","sqlite"],"latest_commit_sha":null,"homepage":"https://mcp.n24q02m.com/servers/mnemo-mcp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/n24q02m.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","claude":"CLAUDE.md","gemini":null,"cursor":null,"copilot":null,"dco":null,"cla":null,"disclosure":null},"funding":{"github":"n24q02m"}},"created_at":"2026-02-12T08:01:04.000Z","updated_at":"2026-08-26T20:15:17.000Z","dependencies_parsed_at":"2026-08-27T03:19:04.012Z","dependency_job_id":null,"html_url":"https://github.com/n24q02m/mnemo-mcp","commit_stats":null,"previous_names":["n24q02m/mnemo-mcp"],"tags_count":181,"template":false,"template_full_name":null,"purl":"pkg:github/n24q02m/mnemo-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fmnemo-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fmnemo-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fmnemo-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fmnemo-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/n24q02m","download_url":"https://codeload.github.com/n24q02m/mnemo-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fmnemo-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36948622,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-28T02:00:06.244Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-coding","ai-memory","claude","claude-code","cursor","docker","hybrid-search","mcp","mcp-server","model-context-protocol","open-source","python","sqlite"],"created_at":"2026-02-12T11:25:32.680Z","updated_at":"2026-08-28T04:05:41.730Z","avatar_url":"https://github.com/n24q02m.png","language":"Python","funding_links":["https://github.com/sponsors/n24q02m"],"categories":["🧠 Knowledge \u0026 Memory (62 servers)"],"sub_categories":[],"readme":"# Mnemo MCP Server\n\nmcp-name: io.github.n24q02m/mnemo-mcp\n\n**Persistent AI memory with hybrid search and embedded sync. Open, free, unlimited.**\n\n\u003c!-- Badge Row 1: Status --\u003e\n[![CI](https://github.com/n24q02m/mnemo-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/n24q02m/mnemo-mcp/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/n24q02m/mnemo-mcp/graph/badge.svg?token=GELGVQNMUZ)](https://codecov.io/gh/n24q02m/mnemo-mcp)\n[![PyPI](https://img.shields.io/pypi/v/mnemo-mcp?logo=pypi\u0026logoColor=white)](https://pypi.org/project/mnemo-mcp/)\n[![License: Apache-2.0](https://img.shields.io/github/license/n24q02m/mnemo-mcp)](LICENSE)\n[![SafeSkill 91/100](https://img.shields.io/badge/SafeSkill-91%2F100_Verified%20Safe-brightgreen)](https://safeskill.dev/scan/n24q02m-mnemo-mcp)\n\n\u003c!-- Badge Row 2: Tech --\u003e\n[![Python](https://img.shields.io/badge/Python-3776AB?logo=python\u0026logoColor=white)](#)\n[![SQLite](https://img.shields.io/badge/SQLite-003B57?logo=sqlite\u0026logoColor=white)](#)\n[![MCP](https://img.shields.io/badge/MCP-000000?logo=anthropic\u0026logoColor=white)](#)\n[![semantic-release](https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release\u0026logoColor=white)](https://github.com/python-semantic-release/python-semantic-release)\n[![Renovate](https://img.shields.io/badge/renovate-enabled-1A1F6C?logo=renovatebot\u0026logoColor=white)](https://developer.mend.io/)\n\n\u003c!-- BEGIN: AUTO-GENERATED-CROSS-PROMO --\u003e\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eSister projects from n24q02m\u003c/strong\u003e (click to expand)\u003c/summary\u003e\n\n| Project | Tagline | Tag |\n|---|---|---|\n| [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling |\n| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |\n| [better-drive](https://github.com/n24q02m/better-drive) | 2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling |\n| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |\n| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |\n| [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |\n| [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling |\n| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |\n| [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP |\n| [claude-plugins](https://github.com/n24q02m/claude-plugins) | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |\n| [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |\n| [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |\n| [mcp-core](https://github.com/n24q02m/mcp-core) | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |\n| [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |\n| [fastretrieval](https://github.com/n24q02m/fastretrieval) | Multi-model retrieval runtime for ONNX/GGUF embeddings and reranking | Library |\n| [skret](https://github.com/n24q02m/skret) | Secrets without the server. | CLI |\n| [tacet](https://github.com/n24q02m/tacet) | A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling |\n| [web-core](https://github.com/n24q02m/web-core) | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |\n| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |\n\n\u003c/details\u003e\n\u003c!-- END: AUTO-GENERATED-CROSS-PROMO --\u003e\n\n## Table of contents\n\n- [Features](#features)\n- [Status](#status)\n- [Documentation](#documentation)\n- [Smithery](#smithery)\n- [Tools](#tools)\n- [Security](#security)\n- [Build from Source](#build-from-source)\n- [CLI](#cli)\n- [Remote (HTTP mode)](#remote-http-mode)\n- [Deploy to Cloudflare](#deploy-to-cloudflare)\n- [Trust Model](#trust-model)\n- [License](#license)\n\n\n\n\u003ca href=\"https://glama.ai/mcp/servers/n24q02m/mnemo-mcp\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/n24q02m/mnemo-mcp/badge\" alt=\"Mnemo MCP server\" /\u003e\n\u003c/a\u003e\n\n## Roadmap (current = Phase 3 / v2.x)\n\n| Phase | Version | Status | Highlights |\n|---|---|---|---|\n| **Phase 1** | **v1.x** | **Shipped** | Typed `memory(action=\"capture\")` (6 context_types + dedup) -- RRF (k=60) hybrid fusion + cross-encoder rerank + temporal decay -- importance x recency archive policy + restore -- Alembic migrations -- multi-provider LLM dispatch -- plugin trinity (recall-context + memory-commit skills, SessionStart + opt-in PostToolUse hooks) |\n| **Phase 2** | v1.x+1 | **Shipped** | LLM-driven compression of older memories + Passport sync (encrypted import/export bundle for cross-machine bootstrap) -- AES-256-GCM + Argon2id, S3 / R2 / B2 / MinIO + GDrive backends, delta-sync with LWW per row |\n| **Phase 3** | **v2.0.0** | **Shipped (BREAKING)** | Temporal knowledge graph -- bitemporal `valid_from` / `valid_to` columns -- entity resolution via embedding KNN -- `entity_search` / `entity_graph` / `history` actions -- KG-aware passport bundle sections -- `KG_AUTO_ENABLED` opt-in auto-extract on capture |\n\n## Features\n\n- **Hybrid retrieval** -- FTS5 + vector search (sqlite-vec locally, Vectorize on Cloudflare), fused via Reciprocal Rank Fusion (k=60), then re-ranked by a configurable rerank chain (`RERANK_MODELS`, order = litellm fallback; empty -\u003e local qwen3-reranker) with temporal decay and importance boost\n- **Typed capture** -- `memory(action=\"capture\")` with 6 context_types (`conversation`/`fact`/`preference`/`skill`/`task`/`decision`), embedding-based dedup, and a configurable LLM chain (`LLM_MODELS`, order = litellm fallback)\n- **Knowledge graph** -- Automatic entity extraction and relation tracking; top results boosted by graph proximity\n- **Importance scoring + archive policy** -- LLM-scored 0.0-1.0 importance; soft-archive when `recency_factor * (1 - importance) \u003e 1.0`; restore action available\n- **Auto-archive trigger** -- Background sweep every Nth capture (default 100) -- no cron required\n- **STM-to-LTM consolidation** -- LLM summarization of related memories in a category\n- **Duplicate detection** -- Warns before adding semantically similar memories\n- **Zero config** -- Built-in local Qwen3 ONNX embedding + reranking, no API keys needed. Optional cloud providers (Jina AI, Gemini, OpenAI, Cohere)\n- **Multi-machine sync** -- JSONL-based merge sync via Google Drive (bundled Desktop OAuth public client)\n- **Plugin trinity** -- Ships `/recall-context` + `/memory-commit` skills and SessionStart + opt-in PostToolUse hooks (see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md))\n- **Proactive memory** -- Tool descriptions and skills guide AI to save preferences, decisions, facts at the right moment\n- **LLM compression** -- Per-turn compression via the multi-provider dispatcher targets ~3x token reduction at \u003e=0.9 fact retention; graceful skip when no provider configured (see [docs/compression.md](docs/compression.md))\n- **Encrypted passport sync** -- AES-256-GCM bundles + Argon2id KDF, S3 (R2 / B2 / MinIO) and Google Drive backends, delta-sync with last-write-wins per row (see [docs/passport.md](docs/passport.md)). Bootstrap via the `passport-bootstrap` skill.\n- **Temporal knowledge graph** -- Bitemporal columns (`valid_from` / `valid_to` / `superseded_by`) on every memory + entity-resolution dedup (embedding KNN at default 0.85 cosine threshold) + audit trail (`memory_audit` table with prev/new state hashes) + new actions (`entity_search` / `entity_graph` / `history`) + opt-in `KG_AUTO_ENABLED` auto-extract on capture. **BREAKING** for clients that called `memory.get` expecting historical-inclusive results: pass `as_of` for time-travel; default now filters to current-state (`valid_to IS NULL`).\n\n## Comparison vs. peers\n\n| Feature | mnemo-mcp | Mem0 | Letta | OpenMemory |\n|---|---|---|---|---|\n| Hybrid retrieval (FTS + vec) | yes (FTS5 + RRF; sqlite-vec local / Vectorize on Cloudflare) | yes | partial | yes |\n| Cross-encoder rerank chain | yes (qwen3 local + Jina + Cohere) | partial (Cohere only) | no | no |\n| Temporal decay scoring | yes (exp half-life) | no | no | no |\n| Importance boost in rank | yes (LLM 0.0-1.0) | no | no | no |\n| Soft-archive + restore policy | yes (importance x recency) | no | no | no |\n| Self-hostable (single SQLite file) | yes (zero ext deps) | partial (cloud-first) | yes (Postgres) | yes (Postgres + Qdrant) |\n| Multi-provider LLM dispatch | yes (`LLM_MODELS` chain, any litellm provider) | partial | yes | partial |\n| Plugin trinity (skills + hooks) | yes (recall-context + memory-commit) | n/a | n/a | n/a |\n| Multi-machine sync | yes (GDrive bundled OAuth) | yes (cloud) | n/a | n/a |\n| E2E-encrypted passport sync | yes (AES-256-GCM + Argon2id, S3 + GDrive) | no | no | no |\n| LLM compression on capture | yes (multi-provider, ~3x at \u003e=0.90 retention) | no | no | no |\n| Backend-pluggable sync architecture | yes (S3 / R2 / B2 / MinIO + GDrive) | no | no | no |\n| Bitemporal `valid_from` / `valid_to` queries | yes (`as_of` time-travel) | no | partial (events only) | no |\n| Entity resolution via embedding KNN | yes (cosine threshold tunable) | no | no | no |\n| Audit trail with state hashes | yes (`memory_audit` table) | no | no | no |\n\n## Status\n\n\u003e **2026-05-02 -- Architecture stabilization update**\n\u003e\n\u003e Past months saw significant churn around credential handling and the daemon-bridge auto-spawn pattern. This caused multi-process races, browser tab spam, and inconsistent setup UX across plugins. **The architecture is now stable**: 2 clean modes (stdio + HTTP), no daemon-bridge layer, no auto-spawn from stdio.\n\u003e\n\u003e Apologies for the instability period. If you encountered issues with prior versions, please update to the latest release and follow the current [setup docs](https://mcp.n24q02m.com/servers/mnemo-mcp/setup/) -- most prior workarounds are no longer needed.\n\u003e\n\u003e **Related plugins from the same author**:\n\u003e - [wet-mcp](https://github.com/n24q02m/wet-mcp) -- Web search + content extraction\n\u003e - [imagine-mcp](https://github.com/n24q02m/imagine-mcp) -- Image/video understanding + generation\n\u003e - [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) -- Notion API\n\u003e - [better-email-mcp](https://github.com/n24q02m/better-email-mcp) -- Email management\n\u003e - [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) -- Telegram\n\u003e - [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) -- Godot Engine\n\u003e - [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) -- Code review knowledge graph\n\u003e\n\u003e All plugins share the same architecture -- install once, learn pattern transfers.\n\n## Documentation\n\nFull docs at **[mcp.n24q02m.com/servers/mnemo-mcp/setup/](https://mcp.n24q02m.com/servers/mnemo-mcp/setup/)**:\n\n- [Setup](https://mcp.n24q02m.com/servers/mnemo-mcp/setup/) -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json\n- [Modes overview](https://mcp.n24q02m.com/get-started/modes-overview/) -- stdio / local-relay / remote-relay / remote-oauth\n- [Multi-user setup](https://mcp.n24q02m.com/get-started/multi-user/) -- per-JWT-sub credential model\n\n**Install with AI agent** -- paste this to your AI coding agent:\n\n\u003e Install MCP server `mnemo-mcp` following the steps at\n\u003e https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/mnemo-mcp/setup-with-agent.md\n\n## Smithery\n\nmnemo-mcp is packaged for [Smithery](https://smithery.ai/) -- install or run it straight from the registry. It starts over stdio via `uvx mnemo-mcp` with no configuration required to launch; credentials are configured at runtime through the server's own config flow (see [Documentation](#documentation)). The published start command lives in [`smithery.yaml`](smithery.yaml).\n\n## Tools\n\n15 MCP tools, 17 memory actions. The memory surface is exposed both as 11 specialized single-purpose tools and a deprecated legacy `memory` dispatcher (same actions), plus `config`, `help`, and `config__open_relay`:\n\n| Tool | Actions | Description |\n|:-----|:--------|:------------|\n| `add_memory`, `search_memory`, `list_memories`, `update_memory`, `delete_memory`, `export_memories`, `import_memories`, `memory_stats`, `restore_memory`, `archived_memories`, `consolidate_memories` | (one action each) | Specialized single-purpose memory tools -- the recommended surface |\n| `memory` (legacy dispatcher, **DEPRECATED** -- use the granular tools above instead; will be removed in a future release) | `add`, `capture`, `search`, `list`, `update`, `delete`, `export`, `import`, `stats`, `restore`, `archived`, `archive_now`, `consolidate`, `compress`, `entity_search`, `entity_graph`, `history` | Core CRUD + typed capture (6 context_types) + hybrid search (RRF + rerank + temporal decay) + import/export + soft-archive + restore + on-demand archive sweep + LLM consolidation + LLM compression + temporal KG (entity search / graph / history) |\n| `config` | `status`, `sync`, `set`, `warmup`, `setup_sync`, `setup_status`, `setup_start`, `setup_skip`, `setup_reset`, `setup_complete`, `setup_relay`, `sync_now`, `export_passport`, `import_passport` | Server status, trigger sync, update settings, pre-download embedding model, authenticate sync provider, manage HTTP setup form lifecycle, passport export/import |\n| `help` | `topic=\"memory\"` or `topic=\"config\"` | Full documentation for any tool |\n| `config__open_relay` | (HTTP relay mode) | Open the zero-config relay setup form (registered via mcp-core) |\n\nPlugin trinity (Claude Code marketplace install):\n\n| Component | Trigger | Purpose |\n|---|---|---|\n| `mnemo:recall-context` skill | session start, before significant decisions, \"what do I know about X?\" | Pulls cwd / topic-relevant memories with `context_type` filtering |\n| `mnemo:memory-commit` skill | \"remember this\" / \"save this\" / \"ghi nho\" / \"luu lai\" | Typed manual capture with `context_type` decision tree |\n| `mnemo:knowledge-audit` skill | periodic / \"audit memory\" | Find duplicates, contradictions, stale entries; consolidate |\n| `mnemo:session-handoff` skill | end of session | Capture decisions / preferences / corrections / conventions / open questions |\n| `mnemo:temporal-query` skill | \"as of\" / \"back in\" / \"history of\" / \"what did I think then\" | Point-in-time snapshots via `action=\"as_of\"` and version-chain tracing via `superseded_by` |\n| SessionStart hook | every session init | Non-blocking nudge to invoke `recall-context` |\n| PostToolUse hook (opt-in) | `CAPTURE_AUTO_ENABLED=true` | Hint `memory-commit` after Write/Edit of CLAUDE.md / AGENTS.md / ARCHITECTURE.md / docs/*.md |\n\n### MCP Resources\n\n| URI | Description |\n|:----|:------------|\n| `mnemo://stats` | Database statistics and server status |\n\n### MCP Prompts\n\n| Prompt | Parameters | Description |\n|:-------|:-----------|:------------|\n| `save_summary` | `summary` | Generate prompt to save a conversation summary as memory |\n| `recall_context` | `topic` | Generate prompt to recall relevant memories about a topic |\n\n## Security\n\n- **Graceful fallbacks** -- Cloud → Local embedding, no cross-mode fallback\n- **Sync token security** -- OAuth tokens stored at `~/.mnemo-mcp/tokens/` with 600 permissions\n- **Input validation** -- Sync provider, folder, remote validated against allowlists\n- **Error sanitization** -- No credentials in error messages\n\n## Build from Source\n\n```bash\ngit clone https://github.com/n24q02m/mnemo-mcp.git\ncd mnemo-mcp\nuv sync\nuv run mnemo-mcp\n```\n\n## CLI\n\nThe `mnemo-mcp` console script both starts the server and exposes a few one-shot operator subcommands. A bare invocation (or any `--`-prefixed flag) starts the server; a leading subcommand runs an action and exits.\n\n```bash\nmnemo-mcp                       # start the stdio server (default transport)\nmnemo-mcp --http                # start the Streamable HTTP server\n                                # (also via MCP_TRANSPORT=http or TRANSPORT_MODE=http)\n\nmnemo-mcp auth google           # authorize Google Drive sync via OAuth\nmnemo-mcp auth google --client-id \u003cID\u003e --client-secret \u003cSECRET\u003e   # bring-your-own OAuth client\nmnemo-mcp logout                # clear the local Google Drive sync token\nmnemo-mcp warmup                # pre-download the bundled local embedding + rerank model\n\nmnemo-mcp config status         # report whether stored config exists\nmnemo-mcp config delete --yes   # delete the stored (encrypted) config\nmnemo-mcp relay status          # show the active browser-setup relay session\nmnemo-mcp relay open            # open the relay setup form in a browser\nmnemo-mcp relay reset           # clear relay session state\nmnemo-mcp doctor                # environment diagnostics (Python, backend, store, mode)\n```\n\n| Subcommand | Purpose |\n|:-----------|:--------|\n| `auth \u003cprovider\u003e` | Authorize a sync credential provider (currently `google`); `--client-id` / `--client-secret` supply a bring-your-own OAuth client |\n| `warmup` | Pre-download the bundled local Qwen3 ONNX embedding + rerank model so first use works offline |\n| `config status` \\| `config delete [--yes]` | Inspect or remove the stored encrypted configuration |\n| `relay status` \\| `relay open` \\| `relay reset` | Inspect, open, or clear the zero-config browser setup session |\n| `doctor` | Report Python version, credential backend, store dir, config, relay session, and storage mode |\n\n## Remote (HTTP mode)\n\nDeployed over HTTP, mnemo speaks Streamable HTTP transport and is OAuth-gated. Point any MCP client that supports remote HTTP + OAuth at `https://\u003cyour-host\u003e/mcp` and authenticate on first connect; each authenticated user gets an isolated per-user credential store (see [Trust Model](#trust-model)). To stand up an instance, see [Deploy to Cloudflare](#deploy-to-cloudflare).\n\nPublic OCI image publication is discontinued. Existing historical registry tags\nremain untouched; new container deployments build from source or use the\nCloudflare-managed registry.\n\n## Deploy to Cloudflare\n\n[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/n24q02m/mnemo-mcp)\n\nRun your own mnemo instance serverless on Cloudflare (Containers + D1 + Vectorize + KV).\n\n**Prerequisites:** a Cloudflare account on the **Workers Paid plan** — required for Containers, D1, and Vectorize (the Cloudflare free tier does not include them) — and the `wrangler` CLI.\n\n1. `git clone https://github.com/n24q02m/mnemo-mcp \u0026\u0026 cd mnemo-mcp`\n2. `wrangler login`\n3. Provision the storage bindings mnemo uses -- the memories database, the embedding\n   index, and the encrypted credential store:\n   ```\n   wrangler d1 create mnemo-memories\n   wrangler vectorize create mnemo-memory-vectors --dimensions 768 --metric cosine\n   wrangler kv namespace create mnemo-kv\n   ```\n   Paste the returned D1 database ID and KV namespace ID into `wrangler.jsonc` (the\n   Vectorize index binds by name, so no ID is needed), then create the memories schema\n   (tables, indexes, and the FTS5 full-text index) in the database you just made:\n   ```\n   wrangler d1 migrations apply mnemo-memories --remote\n   ```\n   The SQL lives in `migrations/0001_init.sql`, and the D1 binding in `wrangler.jsonc`\n   points at that folder via `migrations_dir: \"migrations\"`. Full-text search uses FTS5,\n   which D1 ships; vector similarity is served by Vectorize rather than by an in-database\n   extension, because D1 cannot load one.\n4. Build the HTTP container from this checkout and push it to your Cloudflare managed registry (CF Containers cannot pull from external registries directly), then set `\u003cYOUR_ACCOUNT_ID\u003e` in `wrangler.jsonc`:\n   ```\n   docker build --target http -t mnemo-mcp:local .\n   wrangler containers push mnemo-mcp:local\n   # set image to registry.cloudflare.com/\u003cYOUR_ACCOUNT_ID\u003e/mnemo-mcp:local\n   ```\n5. Set `\u003cYOUR_PUBLIC_URL\u003e` (e.g. `https://mnemo.example.com`) and `\u003cYOUR_WORKER_DOMAIN\u003e`\n   (e.g. `mnemo.example.com`) in `wrangler.jsonc`, then set the secrets:\n   ```\n   wrangler secret put CREDENTIAL_SECRET              # per-user vault key (encrypts the cf-kv credential store)\n   wrangler secret put MCP_RELAY_PASSWORD             # shared password gating the browser setup form\n   wrangler secret put MCP_DCR_SERVER_SECRET          # required once PUBLIC_URL is set (multi-user, per-JWT-sub)\n   wrangler secret put JINA_AI_API_KEY                # EMBEDDING_MODELS + RERANK_MODELS (cloud embed / rerank)\n   wrangler secret put GOOGLE_VERTEX_EXPRESS_API_KEY  # LLM_MODELS (graph extraction, importance, consolidation)\n   ```\n6. `wrangler deploy` and complete setup in the browser relay form at your Worker domain.\n\nStorage maps to Cloudflare via `MCP_STORAGE_BACKEND=cf-kv` (credentials / tokens, encrypted),\n`MEMORY_DB_BACKEND=cf-d1` (the memories database + FTS5 full-text; unset or `sqlite`\nkeeps the local SQLite file at `DB_PATH`), and Vectorize (embeddings,\ncosine). Embedding and reranking are forced cloud through the `EMBEDDING_MODELS` /\n`RERANK_MODELS` chains (`jina_ai/...`) so the container never downloads the local Qwen3 ONNX\nmodels, and graph / LLM features run through the `LLM_MODELS` chain (`vertex_express/...`).\n\n### Authority \u0026 Sync Boundary\n\nOn Cloudflare deployments, **Cloudflare D1 + Vectorize + KV** is the sole production authority:\n- **D1** (`MEMORY_DB_BACKEND=cf-d1`): Authoritative storage for memory rows, metadata, bitemporal valid ranges, and FTS5 search.\n- **Vectorize** (`MCP_VECTORIZE_IDX`): Dense vector index for semantic similarity search.\n- **KV** (`MCP_STORAGE_BACKEND=cf-kv`): Encrypted per-user credential and session store.\n- **Sync boundary** (`SYNC_ENABLED=false`): Production Cloudflare deployments pin legacy Google Drive sync off; Cloudflare serves as the live authority.\n- **Local \u0026 self-host bootstrap**: Local stdio (`~/.mnemo-mcp/memories.db`) and self-hosted instances retain optional passport sync (Google Drive Device Code OAuth or S3/R2/B2) for workstation migration.\n\n## Trust Model\n\nThis plugin implements **TC-Local** (machine-bound, single trust principal). The mode/storage/encryption breakdown below is the full classification.\n\n| Mode | Storage | Encryption | Who can read your data? |\n|---|---|---|---|\n| stdio (default) | `~/.mnemo-mcp/config.json` | AES-GCM, machine-bound key | Only your OS user (file perm 0600) |\n| HTTP self-host | Same as stdio | Same | Only you (admin = user) |\n| HTTP multi-user remote (`PUBLIC_URL`) | Per-JWT-sub credential store | AES-GCM | Only the authenticated user (per-`sub` isolation) |\n\n### Workspace username (HTTP setup form)\n\nThe browser setup form has an optional **workspace username** field. Entering the\nsame username always lands you in the same per-`sub` bucket, so your credentials\nand memories stay reachable across a re-authorization and across devices, instead\nof being tied to the one-off subject minted for each `/authorize` round-trip.\nLeaving it blank keeps the previous per-authorize behaviour.\n\nTrust boundary: when the form is gated by a *shared* `MCP_RELAY_PASSWORD`, the\nusername is a partition key, not a secret -- anyone who knows that password can\ntype any username and reach that bucket. That is fine for a trusted group; an\nuntrusted multi-tenant deployment needs a per-user secret or delegated OAuth\ninstead.\n\n**One-time migration:** existing users must re-enter their credentials once after\nthis change. Nothing is deleted; credentials stored under the old random subject\nare simply no longer addressed.\n\n## License\n\nApache-2.0 -- See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn24q02m%2Fmnemo-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn24q02m%2Fmnemo-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn24q02m%2Fmnemo-mcp/lists"}