使用 Basic Memory 和 Milvus 构建语义化项目记忆

Basic Memory 将项目知识保存在普通 Markdown 文件中，并通过 CLI 和 MCP Server 提供访问。这为编码 Agent 提供了持久的记忆空间，用于保存需要跨越单次对话长期留存的决策、操作手册和经验。

本教程将为应用团队构建一个小型记忆项目。我们会记录有关缓存、身份验证、部署和备份的笔记，然后通过语义检索和 Hybrid Search 找到所需的笔记。

Milvus 将存储向量并执行相似性检索。Basic Memory 则继续在 PostgreSQL 中管理 Markdown 笔记、项目元数据、全文搜索和向量清单。

Text

Markdown notes
      |
      v
Basic Memory CLI / MCP
      |-- PostgreSQL: projects, metadata, full-text search, vector manifest
      |-- OpenAI: embeddings
      `-- Milvus: vector persistence and similarity search

本教程使用 Milvus Lite，它通过你本地计算机上的路径运行。之后，你可以使用相同的 Basic Memory 配置连接 Milvus Standalone、Milvus Distributed 或 Zilliz Cloud。

Prerequisites

你需要：

• Python 3.12 或更高版本
• uv
• PostgreSQL Database 及其 postgresql+asyncpg://... 连接 URL
• OpenAI API key

从 PyPI 安装 Basic Memory 及其 Milvus 可选依赖项：

Shell

uv tool install --python 3.12 "basic-memory[milvus]"

配置 Basic Memory

为本教程创建一个工作区。将 Basic Memory 配置和 Milvus Lite 数据保存在此处，便于之后检查和删除示例。

Shell

mkdir -p basic-memory-milvus-demo/notes
cd basic-memory-milvus-demo

export BASIC_MEMORY_CONFIG_DIR="$PWD/.basic-memory"

配置 PostgreSQL 作为主数据库、OpenAI 作为 Embedding 提供商，并使用 Milvus 作为向量索引：

Shell

export BASIC_MEMORY_DATABASE_BACKEND=postgres
export BASIC_MEMORY_DATABASE_URL="postgresql+asyncpg://USER:PASSWORD@HOST:5432/DATABASE"

export BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=true
export BASIC_MEMORY_SEMANTIC_VECTOR_INDEX=milvus
export BASIC_MEMORY_MILVUS_URI="$PWD/basic-memory-vectors.db"

export BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER=openai
export BASIC_MEMORY_SEMANTIC_EMBEDDING_MODEL=text-embedding-3-small
export OPENAI_API_KEY="sk-***********"

这里，BASIC_MEMORY_MILVUS_URI 是本地路径，因此 PyMilvus 会自动启动 Milvus Lite，无需单独部署 Milvus server。

对于 Basic Memory 整体而言，Milvus 是可选组件，但本教程选择它作为向量后端。目前，只有当主数据库后端为 PostgreSQL 时，这一选择才会生效。基于 SQLite 的 Basic Memory 项目则使用 sqlite-vec。

创建记忆项目

Basic Memory 项目将一个名称映射到一个 Markdown 笔记目录。将本教程目录添加为项目，并将其设为默认项目：

Shell

bm project add app-memory "$PWD/notes" --default

现在，应用团队有了一个持久化的记忆空间。接下来，我们将在其中填充一个小型的混合目录。部分笔记与后续问题相关，其余笔记则作为贴近真实场景的干扰项。

Record project memories

首先记录应用的缓存决策：

Shell

bm tool write-note \
  --title "Caching Strategy" \
  --folder "engineering" \
  --project app-memory <<'EOF'
# Caching Strategy

The application caches read-heavy product responses in Redis for five minutes. This avoids repeated database queries and makes repeated requests faster. Cache entries are invalidated immediately after a write.
EOF

记录身份验证 token 的处理方式：

Shell

bm tool write-note \
  --title "Authentication Tokens" \
  --folder "engineering" \
  --project app-memory <<'EOF'
# Authentication Tokens

JWT access tokens expire after fifteen minutes. Refresh tokens rotate on every use. After suspicious activity, revoke the entire token family and require the user to sign in again.
EOF

添加两份运维手册：

Shell

bm tool write-note \
  --title "Deployment Reliability" \
  --folder "operations" \
  --project app-memory <<'EOF'
# Deployment Reliability

Production releases use a canary deployment. Readiness probes must pass before traffic shifts, and the rollout automatically stops when the error rate crosses the agreed threshold.
EOF

bm tool write-note \
  --title "Database Backups" \
  --folder "operations" \
  --project app-memory <<'EOF'
# Database Backups

PostgreSQL uses daily snapshots and continuous write-ahead log archiving. The team runs a restore drill every month and records the recovery point and recovery time.
EOF

最后，添加两条互不相关的产品说明。相比所有文档都与检索相关的文档集合，这些说明可以让检索练习更具代表性：

Shell

bm tool write-note \
  --title "UI Accessibility" \
  --folder "product" \
  --project app-memory <<'EOF'
# UI Accessibility

The settings screen must support keyboard navigation, visible focus states, sufficient color contrast, and descriptive labels for screen readers.
EOF

bm tool write-note \
  --title "Content Planning" \
  --folder "product" \
  --project app-memory <<'EOF'
# Content Planning

The content calendar tracks blog drafts, launch screenshots, reviewers, and publication dates for the next product release.
EOF

每条笔记仍是 notes/ 目录下的普通 Markdown 文件。Basic Memory 在不改变文件系统所有权的前提下，为这些文件添加可检索的结构。

构建搜索索引

添加或大幅修改一组笔记后，运行一次完整的重新索引：

Shell

bm reindex --full --project app-memory

在此过程中，Basic Memory 会：

1. 读取 Markdown 笔记并将其拆分为文本块。
2. 构建 PostgreSQL 全文索引。
3. 将文本块发送到已配置的 OpenAI Embedding 模型。
4. 将生成的向量存储在项目专属的 Milvus Collection 中。
5. 在 PostgreSQL 向量清单中，将成功存储的文本块标记为就绪。

Basic Memory 会为每个项目使用一个以确定性方式命名的 Milvus Collection。你无需自行创建或命名该 Collection。

按语义检索记忆

假设一位新工程师记得应用针对重复请求进行过优化，却不记得团队将其称为缓存策略。

使用向量搜索以自然语言提问：

Shell

bm tool search-notes \
  "How does the application make repeated requests faster?" \
  --vector \
  --project app-memory \
  --page-size 3 \
  --plain

即使查询中没有重复笔记标题，Caching Strategy 也应排在结果首位。向量搜索会对问题进行 Embedding，并在 Milvus 中查找与其最接近的已存储文本块。

具体分数和排名靠后的结果可能会因 Embedding 模型和项目内容而异。

结合语义和关键词信号

现在，假设你需要响应一起安全事件。查询中包含 JWT 等确切术语，但我们也希望检索到与撤销 token 和重新登录相关、概念相近的表述。

使用 Hybrid Search：

Shell

bm tool search-notes \
  "JWT rotation after suspicious activity" \
  --hybrid \
  --project app-memory \
  --page-size 3 \
  --plain

Authentication Tokens 应排在搜索结果首位。Basic Memory 将 PostgreSQL 全文搜索与 Milvus 向量检索相结合：内容在任一路径中表现突出时都能获得更高得分，尤其是同时被两条路径召回的内容。

三种搜索模式各有所长：

模式	命令标志	最适用场景
Full Text	不指定模式标志	确切术语、短语和布尔关键词查询
Vector	--vector	同义改写、概念和探索性问题
Hybrid	--hybrid	同时使用关键词和语义信号的通用检索

使用其他 Milvus 部署

当 Milvus Lite 无法满足需求时，应用程序代码和 Basic Memory 命令无需更改。只需更改 URI，并在需要时提供 token。

对于 Milvus server：

Shell

export BASIC_MEMORY_MILVUS_URI="http://localhost:19530"
export BASIC_MEMORY_MILVUS_TOKEN="root:Milvus"

对于 Zilliz Cloud：

Shell

export BASIC_MEMORY_MILVUS_URI="https://YOUR_CLUSTER_ENDPOINT"
export BASIC_MEMORY_MILVUS_TOKEN="YOUR_API_KEY"

在现有项目的不同向量后端之间切换之前，请创建一个新的目标 Collection，或按照 Basic Memory 的向量存储迁移流程进行操作。然后重新构建向量：

Shell

bm reindex --full --project app-memory

通过 MCP 使用同一份 Memory

CLI 适用于设置、维护、编写脚本以及理解数据流。在日常工作中，MCP 客户端可以启动同一个 Basic Memory 服务，并直接调用 write_note、search_notes 和 build_context 等工具。

例如，Codex 的 MCP 配置可以运行由 uv tool 安装的命令：

TOML

[mcp_servers.basic-memory]
command = "basic-memory"
args = ["mcp"]

[mcp_servers.basic-memory.env]
BASIC_MEMORY_CONFIG_DIR = "/absolute/path/to/basic-memory-milvus-demo/.basic-memory"
BASIC_MEMORY_DATABASE_BACKEND = "postgres"
BASIC_MEMORY_DATABASE_URL = "postgresql+asyncpg://USER:PASSWORD@HOST:5432/DATABASE"
BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED = "true"
BASIC_MEMORY_SEMANTIC_VECTOR_INDEX = "milvus"
BASIC_MEMORY_MILVUS_URI = "/absolute/path/to/basic-memory-milvus-demo/basic-memory-vectors.db"
BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER = "openai"
BASIC_MEMORY_SEMANTIC_EMBEDDING_MODEL = "text-embedding-3-small"
OPENAI_API_KEY = "sk-***********"

其他 MCP 客户端可以使用同一个可执行文件，并以 JSON 格式提供参数：

JSON

{
  "mcpServers": {
    "basic-memory": {
      "command": "basic-memory",
      "args": ["mcp"],
      "env": {
        "BASIC_MEMORY_CONFIG_DIR": "/absolute/path/to/basic-memory-milvus-demo/.basic-memory",
        "BASIC_MEMORY_DATABASE_BACKEND": "postgres",
        "BASIC_MEMORY_DATABASE_URL": "postgresql+asyncpg://USER:PASSWORD@HOST:5432/DATABASE",
        "BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED": "true",
        "BASIC_MEMORY_SEMANTIC_VECTOR_INDEX": "milvus",
        "BASIC_MEMORY_MILVUS_URI": "/absolute/path/to/basic-memory-milvus-demo/basic-memory-vectors.db",
        "BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER": "openai",
        "BASIC_MEMORY_SEMANTIC_EMBEDDING_MODEL": "text-embedding-3-small",
        "OPENAI_API_KEY": "sk-***********"
      }
    }
  }
}

建议尽可能将数据库密码和 API key 保存在客户端的密钥管理系统或启动环境中。关键要求是，MCP 进程必须接收到与 CLI 相同的 Basic Memory 配置。

各存储层负责的内容

完成本教程后，各层的职责将明确分离：

• 项目目录负责存储原始 Markdown 笔记。
• PostgreSQL 负责存储 Basic Memory 的项目、Entity、元数据、全文索引和权威向量清单。
• OpenAI 将笔记分块和检索问题转换为 Embedding。
• Milvus 负责向量持久化和最近邻检索。
• Basic Memory 负责协调各层，并提供统一的 CLI 和 MCP 使用体验。

因此，在此集成中，Milvus 不会取代 PostgreSQL。它取代的是 PostgreSQL 的 pgvector 路径，负责向量存储和相似性检索，而 Basic Memory 的其余关系型功能和全文搜索功能仍由 PostgreSQL 提供。