Aufbau eines semantischen Projektgedächtnisses mit Basic Memory und Milvus

Basic Memory speichert Projektwissen in gewöhnlichen Markdown-Dateien und stellt es über eine CLI und einen MCP-Server zur Verfügung. Dies bietet einem Programmieragenten einen dauerhaften Ort, an dem er Entscheidungen, Runbooks und Erkenntnisse speichern kann, die über eine einzelne Konversation hinaus Bestand haben sollen.

In diesem Tutorial erstellen wir ein kleines Speicherprojekt für ein Anwendungsteam. Wir werden Notizen zu Caching, Authentifizierung, Bereitstellungen und Backups aufzeichnen und anschließend mithilfe der semantischen und hybriden Suche die richtige Notiz abrufen.

Milvus speichert die Vektoren und führt die Ähnlichkeitssuche durch. Basic Memory verwaltet weiterhin die Markdown-Notizen, Projektmetadaten, die Volltextsuche und das Vektormanifest in PostgreSQL.

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

Dieses Tutorial verwendet Milvus Lite, das lokal unter einem Pfad auf Ihrem Rechner läuft. Dieselbe Basic-Memory-Konfiguration kann später auf Milvus Standalone, Milvus Distributed oder die Zilliz Cloud verweisen.

Voraussetzungen

Sie benötigen:

• Python 3.12 oder höher
• uv
• Eine PostgreSQL-Datenbank und deren postgresql+asyncpg://... -Verbindungs-URL
• Einen OpenAI-API-Schlüssel

Installieren Sie „Basic Memory“ mit den optionalen Milvus-Abhängigkeiten über PyPI:

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

Konfigurieren Sie „Basic Memory“

Erstellen Sie einen Arbeitsbereich für das Tutorial. Wenn Sie die Basic Memory-Konfiguration und die Milvus Lite-Daten hier speichern, lässt sich das Beispiel später leicht überprüfen und entfernen.

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

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

Konfigurieren Sie PostgreSQL als primäre Datenbank, OpenAI als Embedding-Anbieter und Milvus als Vektorindex:

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-***********"

Hier ist „ BASIC_MEMORY_MILVUS_URI “ ein lokaler Pfad, sodass PyMilvus Milvus Lite automatisch startet. Ein separater Milvus-Server ist nicht erforderlich.

Milvus ist in „Basic Memory“ insgesamt optional, wird in diesem Tutorial jedoch als Vektor-Backend ausgewählt. Die Auswahl gilt derzeit nur, wenn das primäre Datenbank-Backend PostgreSQL ist. SQLite-basierte „Basic Memory“-Projekte verwenden stattdessen „ sqlite-vec “.

Erstellen Sie ein Memory-Projekt

Ein „Basic Memory“-Projekt ordnet einen Namen einem Verzeichnis mit Markdown-Notizen zu. Fügen Sie das Tutorial-Verzeichnis als Projekt hinzu und legen Sie es als Standard fest:

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

Das Anwendungsteam verfügt nun über einen dauerhaften Speicherplatz. Füllen wir ihn mit einem kleinen, gemischten Katalog. Einige Notizen werden für unsere späteren Fragen relevant sein, während andere als realistische Ablenkungselemente dienen.

Projektspeicher aufzeichnen

Beginnen Sie mit der Caching-Entscheidung der Anwendung:

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

Erfassen Sie, wie mit Authentifizierungstoken umgegangen wird:

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

Fügen Sie zwei operative Runbooks hinzu:

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

Fügen Sie abschließend zwei nicht miteinander in Zusammenhang stehende Produktnotizen hinzu. Diese machen die Suchübung repräsentativer als ein Katalog, in dem jedes Dokument relevant ist:

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

Jeder Hinweis ist nach wie vor eine gewöhnliche Markdown-Datei unter notes/. Basic Memory fügt die durchsuchbare Struktur hinzu, ohne die Kontrolle über das Dateisystem zu übernehmen.

Erstellen Sie die Suchindizes

Führen Sie eine vollständige Neuindizierung durch, nachdem Sie eine Gruppe von Notizen hinzugefügt oder wesentlich geändert haben:

bm reindex --full --project app-memory

Während dieses Schritts führt Basic Memory folgende Schritte durch:

1. Liest die Markdown-Notizen und unterteilt sie in Chunks.
2. Erstellt den PostgreSQL-Volltextindex.
3. sendet die Chunks an das konfigurierte OpenAI-Embedding-Modell.
4. speichert die resultierenden Vektoren in der projektspezifischen Milvus-Sammlung.
5. Markiert erfolgreich gespeicherte Blöcke in seinem PostgreSQL-Vektor-Manifest als bereit.

Basic Memory verwendet für jedes Projekt eine deterministische Milvus-Sammlung. Sie müssen die Sammlung nicht selbst erstellen oder benennen.

Abrufen eines Speichereintrags anhand der Bedeutung

Angenommen, ein neuer Entwickler erinnert sich daran, dass die Anwendung über eine Optimierung für wiederholte Anfragen verfügt, weiß aber nicht mehr, dass das Team diese als Caching-Strategie bezeichnet hat.

Verwenden Sie die Vektorsuche, um die Frage in natürlicher Sprache zu stellen:

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

Caching Strategy sollte das führende Ergebnis sein, auch wenn die Abfrage den Titel der Notiz nicht wiederholen muss. Die Vektorsuche bettet die Frage ein und fragt Milvus nach den am besten passenden gespeicherten Chunks.

Genaue Bewertungen und Ergebnisse mit niedrigerem Rang können je nach Einbettungsmodell und Projektinhalt variieren.

Kombinieren Sie semantische und Schlüsselwortsignale

Stellen Sie sich nun vor, Sie reagieren auf einen Sicherheitsvorfall. Die Suchanfrage enthält exakte Begriffe wie „ JWT “, aber wir möchten auch konzeptionell verwandte Formulierungen zu Token-Widerruf und erneuter Anmeldung einbeziehen.

Verwenden Sie die hybride Suche:

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

Authentication Tokens sollte das führende Ergebnis sein. Basic Memory kombiniert die Volltextsuche von PostgreSQL mit der Vektorsuche von Milvus und bewertet Inhalte höher, die in einem der beiden Pfade stark abschneiden – insbesondere solche, die von beiden gefunden werden.

Die drei Suchmodi haben unterschiedliche Stärken:

Modus	Befehlsflag	Optimale Verwendung
Volltext	Kein Modus-Flag	Exakte Begriffe, Phrasen und boolesche Stichwortabfragen
Vektor	--vector	Paraphrasen, Konzepte und explorative Fragen
Hybrid	--hybrid	Allgemeine Suche unter Verwendung von Schlüsselwörtern und semantischen Signalen

Verwenden Sie eine andere Milvus-Bereitstellung

Der Anwendungscode und die Basic-Memory-Befehle ändern sich nicht, wenn Sie über die Kapazitäten von Milvus Lite hinauswachsen. Ändern Sie die URI und geben Sie bei Bedarf ein Token an.

Für einen Milvus-Server:

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

Für die Zilliz Cloud:

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

Erstellen Sie eine neue Zielsammlung oder befolgen Sie die Migrationsanleitung von Basic Memory für den Vektorspeicher, bevor Sie ein bestehendes Projekt zwischen Vektor-Backends umstellen. Erstellen Sie anschließend die Vektoren neu:

bm reindex --full --project app-memory

Verwenden Sie denselben Speicher über MCP

Die CLI ist nützlich für die Einrichtung, Wartung, Skripterstellung und das Verständnis des Datenflusses. Im Arbeitsalltag kann ein MCP-Client denselben Basic-Memory-Dienst starten und Tools wie write_note, search_notes und build_context direkt aufrufen.

Beispielsweise kann eine Codex-MCP-Konfiguration den von uv tool installierten Befehl ausführen:

[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-***********"

Andere MCP-Clients verwenden dieselbe ausführbare Datei und dieselben Argumente im JSON-Format:

{
  "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-***********"
      }
    }
  }
}

Bewahren Sie Datenbankpasswörter und API-Schlüssel nach Möglichkeit in der Geheimnismanagement- oder Startumgebung Ihres Clients auf. Wichtig ist, dass der MCP-Prozess dieselbe „Basic Memory“-Konfiguration erhält, die auch von der CLI verwendet wird.

Was jede Speicherschicht umfasst

Am Ende des Tutorials sind die Zuständigkeiten bewusst getrennt:

• Das Projektverzeichnis verwaltet die ursprünglichen Markdown-Notizen.
• PostgreSQL verwaltet die Projekte, Entitäten, Metadaten, den Volltextindex und das autoritative Vektormanifest von „Basic Memory“.
• OpenAI wandelt Notizabschnitte und Suchanfragen in Embeddings um.
• Milvus ist für die Vektorpersistenz und die Nearest-Neighbor-Abfrage zuständig.
• Basic Memory koordiniert die Ebenen und stellt eine einheitliche CLI- und MCP-Oberfläche bereit.

Milvus ersetzt daher in dieser Integration nicht PostgreSQL. Es ersetzt den PostgreSQL- pgvector -Pfad für die Vektorspeicherung und die Ähnlichkeitssuche, während die übrigen relationalen und Volltextfunktionen von Basic Memory weiterhin in PostgreSQL verbleiben.