{"id":51778778,"url":"https://github.com/ydb-platform/mcp-memory-ydb","last_synced_at":"2026-07-20T09:31:15.448Z","repository":{"id":369699883,"uuid":"1263258252","full_name":"ydb-platform/mcp-memory-ydb","owner":"ydb-platform","description":null,"archived":false,"fork":false,"pushed_at":"2026-07-06T13:16:28.000Z","size":31,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-06T15:06:57.207Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/ydb-platform.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-08T19:25:03.000Z","updated_at":"2026-07-06T13:16:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ydb-platform/mcp-memory-ydb","commit_stats":null,"previous_names":["ydb-platform/mcp-memory-ydb"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ydb-platform/mcp-memory-ydb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydb-platform%2Fmcp-memory-ydb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydb-platform%2Fmcp-memory-ydb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydb-platform%2Fmcp-memory-ydb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydb-platform%2Fmcp-memory-ydb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ydb-platform","download_url":"https://codeload.github.com/ydb-platform/mcp-memory-ydb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydb-platform%2Fmcp-memory-ydb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35682455,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"ssl_error","status_checked_at":"2026-07-20T02:08:09.736Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-07-20T09:31:14.182Z","updated_at":"2026-07-20T09:31:15.439Z","avatar_url":"https://github.com/ydb-platform.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-memory-ydb\n\nLong-term memory MCP server for AI agents. It uses [mem0](https://github.com/mem0ai/mem0)\nto turn raw text into extracted facts and [YDB Serverless](https://yandex.cloud/en/services/ydb)\nas the vector store behind them.\n\nBuilt on top of [`ydb-mcp`](https://github.com/ydb-platform/ydb-mcp) (Yandex's MCP\nserver for YDB): the generic SQL tools are switched off and replaced with four\nmemory tools. Works with any OpenAI-compatible LLM/embeddings provider (OpenAI,\nOllama, Yandex Cloud, …).\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `memory_search(query, limit)` | Semantic search across the namespace's memory; each match carries its `id` |\n| `memory_save(text)` | Save a fact — mem0 extracts it and adds it (append-only) |\n| `memory_delete(memory_id)` | Remove a stale/superseded fact by its `id` |\n| `memory_update(memory_id, text)` | Replace the text of a fact by its `id` |\n\n## How it works\n\n`memory_save` does not just store the text you give it. It hands that text to\n**mem0**, which calls your LLM to extract the salient facts. In mem0 2.x this is\n**append-only**: facts accumulate and are not auto-overwritten or de-duplicated\naway. To replace or correct a stale fact, find it via `memory_search` and call\n`memory_delete` / `memory_update` with its `id`. Each extracted fact is embedded\nand written to YDB.\n\n**Language of stored facts.** mem0's extraction prompt is English, so out of the\nbox facts are stored in English even if the user writes another language. To keep\nthe user's own language, set `MEMORY_FACT_INSTRUCTIONS` to a short instruction —\nand write it **in that language**: empirically the model honors a same-language\ndirective far more reliably than an English \"keep the source language\" note. For\nRussian, for example:\n\n```\nMEMORY_FACT_INSTRUCTIONS=Сохраняй каждый факт на языке исходного сообщения, не переводи.\n```\n\nThe server ships no default instruction, leaving mem0's well-tuned prompt\nuntouched unless you opt in.\n\n`memory_search` embeds the query and runs a cosine-similarity search over those\nfacts in YDB, returning the closest matches above `MEMORY_THRESHOLD`.\n\n```\ntext ─▶ mem0 (LLM: extract, append-only) ─▶ embeddings ─▶ YDB vector store\n                                                          │\nquery ─▶ embeddings ─▶ cosine search ◀────────────────────┘\n```\n\n- **mem0** — fact extraction and embedding (append-only in 2.x; curate stale facts\n  via `memory_delete` / `memory_update`). A required dependency, not an optional layer.\n- **[langchain-ydb](https://github.com/ydb-platform/langchain-ydb)** — the vector\n  store; embeds facts and runs similarity search in YDB.\n- **YDB Serverless** — the database that holds the vectors and metadata.\n\n## Memory namespaces\n\nAll memory lives under a single **namespace**, set once via `MEMORY_NAMESPACE`\n(default `default`). A namespace is a partition label — use a different one to\nkeep, say, work and personal memory separate, or one per project. Point a second\nserver instance at a different namespace and the two never see each other's facts.\n\nThe agent does **not** choose the namespace: it is fixed per server process, so\nthe agent calls `memory_save(text)` / `memory_search(query)` and cannot read or\nwrite the wrong partition by mistake. To switch namespaces, run another instance\nwith its own config.\n\n\u003e **A namespace is not a security boundary.** It is a query filter, not row-level\n\u003e security or authentication. Anything with access to the YDB database can read\n\u003e every namespace. Treat the server as single-user-trusted: run your own\n\u003e instance against your own database. It is not a multi-tenant backend — that\n\u003e would require an authenticated transport that maps each caller to a namespace\n\u003e the agent cannot forge.\n\n## Quick start\n\n### 1. Configure\n\n```bash\n# From PyPI (once published):\nuvx mcp-memory-ydb setup\n\n# From source — option 1: uvx (closest to production, isolated environment):\ngit clone https://github.com/ydb-platform/mcp-memory-ydb\ncd mcp-memory-ydb\nuvx --from . mcp-memory-ydb setup\n\n# From source — option 2: venv (convenient for development):\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e .\nmcp-memory-ydb setup\n```\n\nThe wizard creates `.mcp-memory-ydb.env` and prints ready-to-use commands for connecting to your agent.\n\n### 2. Connect to your agent\n\n**Claude Code:**\n```bash\n# From PyPI:\nclaude mcp add --scope user memory-ydb -- uvx mcp-memory-ydb\n\n# From source via uvx (production approach):\nclaude mcp add --scope user memory-ydb -- uvx --from /path/to/mcp-memory-ydb mcp-memory-ydb\n\n# From source via venv:\nclaude mcp add --scope user memory-ydb -- /path/to/.venv/bin/mcp-memory-ydb\n```\n\n**Cursor / VS Code** — add this to your MCP settings (the wizard prints a ready-to-paste version):\n```json\n{\n  \"mcpServers\": {\n    \"memory-ydb\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-memory-ydb\"]\n    }\n  }\n}\n```\n\nThe server reads its config from `~/.mcp-memory-ydb.env` automatically (the path `setup` saves to by default), so the MCP entry needs only the command — no `env` block required.\nFor source via uvx, add `\"--from\", \"/path/to/mcp-memory-ydb\"` before `\"mcp-memory-ydb\"` in `args`.\nFor venv, set `command` to `/path/to/.venv/bin/mcp-memory-ydb` and clear `args`.\n\n### 3. Agent system prompt (usually optional)\n\nThe server ships **MCP instructions** that tell the agent to search memory before\nanswering and save after. Clients that honor server instructions (e.g. Claude\nCode) pick this up automatically on connect — **no system prompt needed**.\n\nFor clients that ignore server instructions, add this to the agent's system\nprompt as a fallback:\n\n```\nBefore answering, call memory_search for relevant context about the user.\nAfter answering, call memory_save if you learned something important.\nUse these tools silently — do not announce or narrate searching or saving.\nSave facts in the user's own language, without translating.\n```\n\n## How you use it\n\nYou never call the tools by hand. Once the server is connected (step 2 above),\nthe **agent** calls `memory_search` and `memory_save` on its own — guided by the\nserver's built-in instructions (or the fallback system prompt) — while you just\nhave a normal conversation. Memory works in the\nbackground.\n\nTo confirm it works, test it through a conversation. The flow is the same in\nClaude Code, Cursor, and VS Code:\n\n1. **Verify the server is connected.**\n   - Claude Code: run `/mcp` — `memory-ydb` should be listed with its four tools.\n   - Cursor / VS Code: open the MCP settings panel — `memory-ydb` should show a\n     connected status.\n2. **Teach it a fact.** Say:\n   *\"Remember that my favorite language is Rust and I work in the Moscow timezone.\"*\n   The agent calls `memory_save` (Claude Code shows the tool call inline).\n3. **Recall it in a fresh conversation.** Start a new chat and ask:\n   *\"What's my favorite programming language?\"*\n   The agent calls `memory_search` and answers from memory.\n\nIf step 3 works in a brand-new conversation, the full save → store → search\nround-trip across sessions is verified.\n\n## Troubleshooting\n\nThe server fails fast with a single readable error. The two most common ones:\n\n**`Could not connect to YDB … PERMISSION_DENIED`**\nThe service account cannot access the database. Check that:\n- the SA has the **`ydb.editor`** role on the database's folder\n  (`yc resource-manager folder add-access-binding \u003cfolder\u003e --role ydb.editor --subject serviceAccount:\u003csa-id\u003e`);\n- `YDB_SA_KEY_FILE` points at the **right** key for that SA (a valid key for the\n  *wrong* SA also yields `PERMISSION_DENIED`);\n- `YDB_DATABASE` is the full path `/ru-central1/\u003cfolder\u003e/\u003cdb\u003e`.\n\n**`LLM/Embeddings unavailable … CERTIFICATE_VERIFY_FAILED`**\nPython cannot verify the provider's TLS certificate. This is almost always a\nlocal trust-store issue, not a problem with the server. If you have a custom\n`SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` set in your environment, it may be a\nnarrow bundle missing the provider's CA. Either add the CA to that bundle, or\npoint the variable at the [certifi](https://pypi.org/project/certifi/) bundle\nwhen launching the server:\n```bash\nSSL_CERT_FILE=\"$(python -m certifi)\" mcp-memory-ydb\n```\nTo confirm the cause, compare a request made with your bundle vs. certifi's —\nif certifi works and yours does not, your bundle is missing the CA.\n\n## Configuration\n\nAll settings live in `.mcp-memory-ydb.env`. Annotated template: [`.env.example`](.env.example).\n\nThe server validates its configuration, connects to YDB, and probes the LLM/embeddings\nat startup. If something is unreachable or misconfigured, it **fails clearly within a\nfew seconds** instead of hanging.\n\n### Environment variables\n\n| Variable | Required | Description |\n|----------|:---:|-------------|\n| `LLM_BASE_URL` | yes | Provider base URL |\n| `LLM_MODEL` | yes | OpenAI: `gpt-4o-mini`; Yandex: `gpt://\u003cfolder_id\u003e/yandexgpt/latest`; Ollama: `llama3` |\n| `LLM_API_KEY` | yes | API key |\n| `EMBEDDINGS_MODEL` | yes | OpenAI: `text-embedding-3-small`; Yandex: `emb://\u003cfolder_id\u003e/text-search-query/latest` |\n| `EMBEDDINGS_BASE_URL` | | Embeddings base URL (default: `LLM_BASE_URL`) |\n| `EMBEDDINGS_API_KEY` | | Embeddings API key (default: `LLM_API_KEY`) |\n| `YDB_ENDPOINT` | yes | `grpcs://ydb.serverless.yandexcloud.net:2135` |\n| `YDB_DATABASE` | yes | `/ru-central1/\u003cfolder\u003e/\u003cdb\u003e` |\n| `YDB_SA_KEY_FILE` | | Path to the service-account JSON key |\n| `YDB_SA_KEY` | | Service-account key as a JSON string (alternative to `YDB_SA_KEY_FILE`) |\n| `MEMORY_NAMESPACE` | | Memory partition, e.g. per project (default: `default`) |\n| `MEMORY_FACT_INSTRUCTIONS` | | Steers mem0 extraction (e.g. stored language); empty = mem0 default. Write it in your own language. |\n| `MEMORY_THRESHOLD` | | Minimum cosine score (default: `0.15`) |\n| `MEMORY_TIMEOUT` | | Memory operation timeout, seconds (default: `30`) |\n| `PROBE_TIMEOUT` | | Startup LLM/embeddings probe timeout (default: `MEMORY_TIMEOUT`) |\n| `YDB_TIMEOUT` | | YDB `discovery_request_timeout` (default: `MEMORY_TIMEOUT`) |\n\n## Requirements\n\n- Python 3.11+\n- An OpenAI-compatible **LLM and embeddings** provider with an API key (OpenAI,\n  Yandex Cloud, Ollama, …) — mem0 uses the LLM to extract facts and the\n  embeddings to vectorize them\n- A YDB Serverless database and a service account with the `ydb.editor` role\n\n## License\n\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fydb-platform%2Fmcp-memory-ydb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fydb-platform%2Fmcp-memory-ydb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fydb-platform%2Fmcp-memory-ydb/lists"}