Qdrant Memory

Name: Qdrant Memory
Author: cnkang

本地服务

github.com/cnkang记忆与知识1今天更新

代码仓库

关于 Qdrant Memory

Qdrant Memory 为 AI Agent 提供基于 Qdrant 的持久化、分范围记忆，并通过 stdio MCP 暴露显式操作。它以操作员配置的用户和 Agent 范围隔离记忆，不会自动提取对话内容。

主要功能

01四个范围化记忆工具
02记忆搜索与持久化增删改
03操作员固定用户和 Agent 范围
04支持嵌入式、托管及云端 Qdrant
05支持 Ollama 和 OpenAI 兼容嵌入

适用场景

01让 Agent 显式保存并检索记忆
02按配置的用户与 Agent 隔离数据
03通过 MCP 客户端执行记忆维护

MCP 相关

作为本地 stdio MCP 服务，提供记忆搜索、添加、更新和删除四种工具。它不提供资源或提示词，也不会自动抽取对话内容。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cnkang-qdrant-memory": {
      "command": "uvx",
      "args": [
        "qdrant-memory-mcp"
      ],
      "env": {
        "QDRANT_URL": "<QDRANT_URL>",
        "QDRANT_API_KEY": "<QDRANT_API_KEY>",
        "EMBEDDING_API_KEY": "<EMBEDDING_API_KEY>"
      }
    }
  }
}

启动命令uvx qdrant-memory-mcp

需要配置的环境变量

QDRANT_URLOptional remote Qdrant endpoint when configured for server/cloud mode.

QDRANT_API_KEY密钥Optional Qdrant credential for configured remote storage.

EMBEDDING_API_KEY密钥Optional credential for the configured embedding provider.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypiqdrant-memory-mcp0.2.6stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Qdrant Memory MCP

对于共享生产部署，请阅读部署安全指南。除 MCP 授权外，还必须使用仅供所有者使用的数据库写入凭据。Runtime 0.5.0 包含目标保护和共享 doctor；操作员必须配置这些控制措施。支持范围限制请参阅所有者支持记录。

一个记忆，多个 Agent — 可选的共享所有者模式

此发行版新增了可选的单所有者服务和 stdio 桥接。安装 Runtime 0.5.0 即可使用。请参阅共享集成指南。私有默认设置保持不变。Native Provider 自动共享提取功能暂缓推出。

WorkBuddy 连接器和 DeepSeek Harness 套件复用此 stdio MCP、托管启动器和规范 Skill。

简体中文

通过四个明确的 stdio MCP 工具，为 AI Agent 提供持久化、限定范围的记忆。此仓库分发现有的 Python Runtime。其仅含元数据的 wheel 不包含 Python 业务实现。控制台脚本直接指向 qdrant_memory.standalone:main，并依赖于 hermes-plugin-qdrant-memory[mcp]==0.5.0。

有关源代码对齐、WorkBuddy 资源和兼容性边界，请参阅 0.2.4 发行说明。

使用精确版本安装命令前，请先在 PyPI 发行页面上确认该版本。

**版本：**MCP 发行版 0.2.4 固定使用 Runtime 0.5.0，后者支持 MCP Python SDK 1.x 和 2.x（mcp>=1.30,<3）。两个 SDK 主版本使用相同的四个限定范围工具和 stdio 启动参数。该版本保留了无需大模型即可显式写入彼此不同且高度相似文本的修复。以下命令使用这些精确版本。发行构件可通过发行版 PyPI 页面和 Runtime PyPI 页面获取。发布流程请参阅发行清单。

Runtime、可选 Agent Skill 和 MCP 发行版的版本彼此独立。Skill 提供使用指南，而非 Runtime 依赖项。Hermes 保留其原生 MemoryProvider、自动提取和预取功能。普通 MCP 只执行明确请求的记忆操作。它不会自动提取每一轮对话。

安装和初始化

若要使用目前支持的最简本地配置，请按照 Ollama 快速入门（中文）。其中介绍如何使用已有模型、安装缺少的模型、创建独立的 WorkBuddy 配置文件、设置连接，以及进行首次保存和搜索检查。此本地方式无需 Qdrant 服务、 Docker、云账户或嵌入 API 密钥。直接配置仍需安装 Python/uv 并进行一次性配置文件设置。托管式 WorkBuddy 连接器和 DSH 软件包则改为通过 Node.js 准备这些依赖项。

需要 Python 3.11+，以及 uv 或 Python 虚拟环境。必须配置存储和嵌入服务。以下示例中，请运行 Ollama 并自行安装 qwen3-embedding:4b。

创建由操作员管理的配置文件目录，并将 qdrant-memory.json 保存其中：

{
  "schema_version": 1,
  "scope": {"user_id": "my-user", "agent_id": "my-agent"},
  "qdrant": {"mode": "embedded", "collection": "qdrant_memory"},
  "embedding": {
    "mode": "plugin", "provider": "ollama", "model": "qwen3-embedding:4b",
    "base_url": "http://127.0.0.1:11434", "dimensions": 2560, "distance": "Cosine"
  }
}

初始化后启动（将 /path/to/profile 替换为绝对路径）：

uvx --from qdrant-memory-mcp==0.2.4 qdrant-memory-mcp --home /path/to/profile init
uvx --from qdrant-memory-mcp==0.2.4 qdrant-memory-mcp --home /path/to/profile mcp

不带 --home 的命令会使用 ~/.qdrant-memory，与 Hermes 无关。让 Registry 客户端启动 uvx --from qdrant-memory-mcp==0.2.4 qdrant-memory-mcp mcp 之前，请先配置并初始化该目录。可执行文件名称与软件包名称一致。 Registry 的位置参数 mcp 用于选择协议模式。客户端提供自定义配置文件时，可选的命名参数 --home 必须放在 mcp 前面。

或者：

python3 -m venv .venv
.venv/bin/python -m pip install qdrant-memory-mcp==0.2.4
.venv/bin/qdrant-memory-mcp --home /path/to/profile init
.venv/bin/qdrant-memory-mcp --home /path/to/profile mcp

在 Windows 上使用 .venv\Scripts\python.exe 和 .venv\Scripts\qdrant-memory-mcp.exe。

Qdrant 嵌入式、自托管服务和 Cloud，以及 Ollama 和兼容 OpenAI 的嵌入服务，都可在 Runtime 的配置参考中设置。将凭据保存在操作员环境变量中（QDRANT_API_KEY、 EMBEDDING_API_KEY 或已配置的名称）。切勿提交这些变量的值。对现有集合进行初始化需要操作员明确选择。首次测试时不要使用生产环境目标。

连接客户端

Codex config.toml 示例：

[mcp_servers.qdrant_memory]
command = "uvx"
args = ["--from", "qdrant-memory-mcp==0.2.4", "qdrant-memory-mcp", "--home", "/path/to/profile", "mcp"]

OpenCode opencode.json 示例：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "qdrant_memory": {
      "type": "local",
      "command": ["uvx", "--from", "qdrant-memory-mcp==0.2.4", "qdrant-memory-mcp", "--home", "/path/to/profile", "mcp"],
      "enabled": true
    }
  }
}

Pi 需要单独安装 MCP 客户端/扩展。在该扩展中，使用 command: uvx 和相同的参数列表。这里不声称 Pi 内置支持 MCP，也不声称存在通用的扩展配置格式。以下内容仅为配置示例。此发行版的验收测试使用官方 Python MCP SDK，而非实时 Agent 应用。请参阅 Runtime 的客户端证据和限制。

工具与边界

工具	输入	结果
`qdrant_memory_search`	`query`、可选的 `category`	带有 ID、分数和来源信息的限定范围记忆
`qdrant_memory_add`	`text`	持久记忆 ID
`qdrant_memory_update`	精确的 `id`、替换后的 `text`	限定范围的替换
`qdrant_memory_delete`	精确的 `id`	限定范围的删除

作用范围由操作员的配置文件（user_id、agent_id）固定。模型输入和 MCP 客户端身份都无法覆盖此范围。知道某个 ID 并不代表获得访问权限。迁移、导出、重置和批量删除仍是受信任的操作员 CLI 命令。参见独立维护。不会公布资源或提示词。这是一个本地子进程，不提供公共 HTTP/SSE 监听器或远程身份验证服务。标准输出专用于协议消息，已清理的诊断信息则输出到标准错误。

数据从客户端流向 Runtime，再流向嵌入提供方、Qdrant 和本地 SQLite 账本。使用本地 Ollama 和嵌入式 Qdrant 时，记忆处理会保留在本地。云端嵌入服务会接收记忆/查询文本，云端 Qdrant 会接收向量和已存储的负载。客户端/模型也可能接收召回的文本。操作员必须授权数据保留和访问，并保护配置文件。

一个写入租约负责协调一个配置文件/目标。不要让 MCP、CLI 或 Hermes 进程同时写入该目标。不同配置文件或机器之间不会提供分布式锁。此软件包不支持未协调的多进程写入、自动提取、HTTP 传输，也不支持从 Hermes 隐式发现凭据。它保留 Runtime 的账本、ID 和恢复语义。

验证与开发

CI 会构建 wheel/sdist、检查元数据和所有权标记。在 Linux/macOS/Windows、Python 3.11 和 3.14 上，它会使用临时配置文件、嵌入式 Qdrant 和确定性的环回嵌入夹具运行已安装协议测试。没有测试会连接个人 Qdrant、Hermes 配置文件或记忆数据。这些测试涵盖初始化、发现、四种工具、持久化、恢复、作用范围隔离、错误信息脱敏和协议标准输出。提供方/云端兼容性证据请参阅 Runtime。

CI 优先使用不可变的 Runtime PyPI 版本。在 Runtime 发布到 PyPI 之前， CI 会根据 runtime-source.json 中记录的不可变修订版本构建 wheel。这只是一个准备阶段的夹具：已发布的依赖元数据始终使用精确的 PyPI 版本。发布工作流的验收要求从 PyPI 安装，绝不会使用该回退方式。

参见 CI 和依赖维护、发布、架构，以及可选的 Skill。

WorkBuddy 和 DeepSeek Harness

如需显式持久记忆，请使用 WorkBuddy 连接器或 DSH 安装指南。两者都复用 Python Runtime、四种 MCP 工具和规范 Skill。已发布的托管启动器使用 Node.js 准备私有 Python 和 CPU 模型依赖。因此，托管方式无需安装系统 Python、uvx 或 Ollama。DSH Bundle 以 @cnkang/qdrant-memory-dsh-bundle 形式分发。现有 Hermes 配置文件和默认设置保持不变。参见架构与版本矩阵和验证限制。