Milvus
Zilliz
별표46.0K데모 예약하기시작하기
홈페이지
  • 홈
  • 문서

  • 연동 기능

  • 요원들

  • 기본 메모리

Basic Memory와 Milvus를 활용한 시맨틱 프로젝트 메모리 구축

Basic Memory는 프로젝트 지식을 일반 마크다운 파일에 저장하고, CLI 및 MCP 서버를 통해 이를 이용할 수 있게 해줍니다. 이를 통해 코딩 에이전트는 단일 대화의 범위를 넘어 지속되어야 하는 결정 사항, 실행 매뉴얼, 교훈 등을 기억할 수 있는 안정적인 공간을 확보하게 됩니다.

이 튜토리얼에서는 애플리케이션 팀을 위한 소규모 메모리 프로젝트를 구축해 보겠습니다. 캐싱, 인증, 배포, 백업에 관한 노트를 기록한 다음, 시맨틱 및 하이브리드 검색을 통해 적절한 노트를 찾아볼 것입니다.

Milvus는 벡터를 저장하고 유사도 검색을 수행합니다. Basic Memory는 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

운영 런북 두 개를 추가하세요:

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/ 아래에 있는 일반적인 마크다운 파일입니다. Basic Memory는 파일 시스템에 대한 소유권을 침해하지 않으면서 검색 가능한 구조를 추가합니다.

검색 인덱스 구축

노트 그룹을 추가하거나 대폭 변경한 후 전체 재색인 작업을 실행합니다:

bm reindex --full --project app-memory

이 단계에서 Basic Memory는:

  1. 마크다운 노트를 읽어와 청크로 분할합니다.
  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 구성을 수신해야 한다는 점입니다.

각 스토리지 계층이 담당하는 역할

이 튜토리얼의 마지막 단계에서는 책임 범위가 의도적으로 분리됩니다:

  • 프로젝트 디렉터리는 원본 마크다운 노트를 관리합니다.
  • PostgreSQL은 Basic Memory의 프로젝트, 엔티티, 메타데이터, 전체 텍스트 인덱스 및 권위 있는 벡터 매니페스트를 관리합니다.
  • OpenAI는 노트 청크와 검색 질문을 임베딩으로 변환합니다.
  • Milvus는 벡터 저장 및 최인접 이웃 검색을 담당합니다.
  • Basic Memory는 각 계층을 조정하며 단일 CLI 및 MCP 환경을 제공합니다.

따라서 이 통합 환경에서 Milvus는 PostgreSQL을 대체하지 않습니다. Milvus는 벡터 저장 및 유사도 검색을 위한 PostgreSQL의 ` pgvector ` 경로를 대체할 뿐이며, Basic Memory의 나머지 관계형 및 전체 텍스트 기능은 PostgreSQL에 그대로 유지됩니다.

번역DeepL

목차 목록

관리형 Milvus를 무료로 사용해 보세요

Zilliz Cloud는 번거로움이 없으며, Milvus 기반으로 10배 더 빠릅니다.

시작하기
피드백

이 페이지가 도움이 되었나요?