利用 Basic Memory 與 Milvus 建構語義化專案記憶庫

Basic Memory將專案知識儲存於普通的 Markdown 檔案中，並透過命令列介面（CLI）和 MCP 伺服器提供存取。這為程式碼代理提供了一個持久的儲存空間，用以記錄應在單次對話結束後仍能保留的決策、操作手冊及經驗教訓。

在本教學中，我們將為一個應用程式團隊建置一個小型記憶體專案。我們將記錄關於快取、身分驗證、部署及備份的筆記，並透過語義搜尋與混合搜尋來檢索正確的筆記。

Milvus將負責儲存向量並執行相似度搜尋。Basic Memory 則會持續在 PostgreSQL 中管理 Markdown 筆記、專案元資料、全文搜尋以及向量清單。

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。

先決條件

您需要：

• Python 3.12 或更新版本
• uv
• 一個 PostgreSQL 資料庫及其postgresql+asyncpg://... 連線網址
• 一個 OpenAI API 金鑰

從 PyPI 安裝 Basic Memory 及其 Milvus 選用依賴項：

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

設定 Basic Memory

為本教學建立一個工作區。將 Basic Memory 的設定與 Milvus Lite 資料存放於此，可讓範例日後更容易檢視與移除。

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

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

將 PostgreSQL 設定為主資料庫、OpenAI 設定為嵌入式模型供應商，並將 Milvus 設定為向量索引：

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 伺服器。

在「基本記憶體」中，Milvus 雖屬選用組件，但本教學中已將其設為向量後端。此設定目前僅適用於主資料庫後端為 PostgreSQL 的情況。基於 SQLite 的「基本記憶體」專案則改用sqlite-vec 。

建立記憶體專案

「基本記憶體」專案會將名稱映射至 Markdown 筆記的目錄。請將本教學的目錄新增為專案，並設定為預設專案：

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

應用程式團隊現在擁有了一個持久的記憶體空間。讓我們用一個小型且內容混雜的目錄來填滿它。其中部分筆記將與我們稍後的提問相關，而其他筆記則會提供逼真的干擾選項。

記錄專案記憶內容

首先從應用程式的快取決策開始：

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

記錄身份驗證令牌的處理方式：

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

新增兩份運作手冊：

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

最後，新增兩則無關的產品筆記。與所有文件都相關的目錄相比，這些筆記能讓搜尋演練更具代表性：

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 添加了可搜尋的結構，同時不剝奪檔案系統對檔案的控制權。

建立搜尋索引

在新增或大幅修改一組筆記後，執行完整重新索引：

bm reindex --full --project app-memory

在此步驟中，Basic Memory 會：

1. 讀取並將 Markdown 筆記分割為區塊。
2. 建立 PostgreSQL 全文索引。
3. 將分塊資料傳送至已設定的 OpenAI 嵌入模型。
4. 將生成的向量儲存至專案專屬的 Milvus 集合中。
5. 將成功儲存的區塊標記為「已準備就緒」，並記錄於其 PostgreSQL 向量清單中。

Basic Memory 會為每個專案使用一個確定性的 Milvus 集合。您無需自行建立或命名該集合。

根據意涵檢索記憶體

假設一位新進工程師記得應用程式針對重複請求有項優化措施，但不記得團隊將其稱為「快取策略」。

使用向量搜尋以自然語言提出問題：

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

Caching Strategy 即使查詢中未重複註記標題，該結果仍應位居首位。向量搜尋會將問題進行嵌入，並向 Milvus 查詢最接近的儲存區塊。

確切的得分與排名較低的結果，可能會因嵌入模型及專案內容而有所不同。

結合語義與關鍵字訊號

現在試想處理一則資安事件的情境。查詢中包含「JWT 」等精確術語，但我們也希望涵蓋關於憑證撤銷與重新登入等概念上相關的表述。

使用混合搜尋：

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

Authentication Tokens 應為首選結果。「基本記憶體（Basic Memory）」模式結合了 PostgreSQL 全文檢索與 Milvus 向量檢索，優先呈現任一途徑中表現優異的內容，特別是同時被兩者檢索到的內容。

這三種搜尋模式各有其優勢：

模式	指令標誌	最佳用途
全文	無模式標誌	精確術語、短語及布林關鍵字查詢
向量	--vector	換語、概念及探索性問題
混合式	--hybrid	同時運用關鍵字與語義訊號進行通用檢索

使用其他 Milvus 部署環境

當您需要超越 Milvus Lite 的處理能力時，應用程式程式碼和 Basic Memory 指令均無需變更。只需變更 URI，並在必要時提供存取憑證。

針對 Milvus 伺服器：

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

針對 Zilliz Cloud：

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

在將現有專案切換至其他向量後端之前，請建立新的目標集合，或遵循 Basic Memory 的向量儲存庫遷移程序。接著重新建構向量：

bm reindex --full --project app-memory

透過 MCP 使用相同的記憶體

命令列介面（CLI）對於設定、維護、腳本編寫以及理解資料流非常有用。在日常工作中，MCP 客戶端可以啟動相同的 Basic Memory 服務，並直接呼叫write_note 、search_notes 以及build_context 等工具。

例如，Codex MCP 配置可執行由uv tool 安裝的指令：

[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 格式呈現的參數：

{
  "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 金鑰存放於您的客戶端機密管理系統或啟動環境中。關鍵要求在於 MCP 進程必須接收與 CLI 所使用的相同 Basic Memory 配置。

各儲存層的權限範圍

在本教學結束時，各項職責已刻意進行分離：

• 專案目錄負責管理原始的 Markdown 筆記。
• PostgreSQL 負責管理 Basic Memory 的專案、實體、元資料、全文索引以及權威向量清單。
• OpenAI 將筆記片段和搜尋問題轉換為嵌入向量。
• Milvus 負責向量持久化與最近鄰檢索。
• Basic Memory 負責協調各層，並提供統一的 CLI 與 MCP 使用體驗。

因此，在此整合中，Milvus 並未取代 PostgreSQL。它僅取代了 PostgreSQL 中用於向量儲存與相似度搜尋的pgvector 路徑，而 Basic Memory 的其餘關聯式資料庫與全文搜尋功能則仍保留在 PostgreSQL 中。