Basic MemoryとMilvusを用いたセマンティック・プロジェクト・メモリの構築

Basic Memoryは、プロジェクトのナレッジを通常のMarkdownファイルに保存し、CLIやMCPサーバーを通じて利用できるようにします。これにより、コーディングエージェントは、1回の会話を超えて残すべき決定事項、ランブック、教訓などを記憶するための永続的な場所を確保できます。

このチュートリアルでは、アプリケーションチーム向けの小規模なメモリプロジェクトを構築します。キャッシュ、認証、デプロイ、バックアップに関するメモを記録し、セマンティック検索とハイブリッド検索を用いて適切なメモを検索できるようにします。

Milvusはベクトルを保存し、類似度検索を実行します。Basic Memoryは、Markdown形式のメモ、プロジェクトのメタデータ、全文検索、およびPostgreSQL内のベクトルマニフェストを引き続き管理します。

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://... 接続URL
• 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サーバーを用意する必要はありません。

Basic Memory全体においてMilvusはオプションですが、このチュートリアルではベクトルバックエンドとしてMilvusが選択されています。この選択は現在、プライマリデータベースバックエンドがPostgreSQLの場合にのみ適用されます。SQLiteベースのBasic Memoryプロジェクトでは、代わりにsqlite-vec を使用します。

メモリプロジェクトの作成

Basic Memory プロジェクトは、名前を 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

2つの運用ランブックを追加します:

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

最後に、関連性のない製品メモを2つ追加します。これにより、すべてのドキュメントが関連しているカタログよりも、検索演習がより現実的なものになります：

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のベクトル検索を組み合わせ、いずれかの経路で高い評価を得たコンテンツ、特に両方の経路で見つかったコンテンツを優先します。

3つの検索モードにはそれぞれ異なる強みがあります：

モード	コマンドフラグ	最適な用途
全文検索	モードフラグなし	完全一致の用語、フレーズ、およびブール演算子を含むキーワード検索
ベクトル	--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に取って代わるものではありません。Milvusは、ベクトル格納および類似度検索においてPostgreSQLのpgvector パスを置き換える一方で、Basic Memoryのその他のリレーショナル機能および全文検索機能は引き続きPostgreSQLで処理されます。