Создание семантической памяти проекта с помощью Basic Memory и Milvus

Basic Memory хранит знания о проекте в обычных файлах Markdown и делает их доступными через CLI и сервер MCP. Это предоставляет агенту-программисту надежное место для сохранения решений, руководств и уроков, которые должны сохраняться после завершения одного разговора.

В этом руководстве мы создадим небольшой проект памяти для команды разработчиков приложения. Мы запишем заметки о кэшировании, аутентификации, развертывании и резервном копировании, а затем будем находить нужные заметки с помощью семантического и гибридного поиска.

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 и URL-адрес для подключения по протоколу postgresql+asyncpg://...
• Ключ API OpenAI

Установите Basic Memory вместе с дополнительными зависимостями Milvus из PyPI:

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.

Создание проекта «memory»

Проект 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

Добавьте два операционных руководства:

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

Каждая заметка по-прежнему представляет собой обычный файл Markdown, расположенный в папке notes/. 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

Код приложения и команды Basic Memory не изменяются, когда вы выходите за рамки возможностей Milvus Lite. Измените 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 получал ту же конфигурацию Basic Memory, что и CLI.

Что принадлежит каждому уровню хранения

В конце этого руководства обязанности намеренно разделены:

• Каталог проекта отвечает за исходные заметки в формате Markdown.
• PostgreSQL отвечает за проекты, сущности, метаданные, полнотекстовый индекс и авторитетный векторный манифест Basic Memory.
• OpenAI преобразует фрагменты заметок и поисковые запросы в вложения.
• Milvus отвечает за сохранность векторных данных и поиск ближайших соседей.
• Basic Memory координирует работу всех уровней и предоставляет единый интерфейс для командной строки (CLI) и MCP.

Таким образом, в данной интеграции Milvus не заменяет PostgreSQL. Он заменяет путь « pgvector » в PostgreSQL для хранения векторов и поиска по схожести, в то время как остальные реляционные и полнотекстовые функции Basic Memory остаются в PostgreSQL.