Membangun Memori Proyek Semantik dengan Basic Memory dan Milvus

Basic Memory menyimpan pengetahuan proyek dalam berkas Markdown biasa dan membuatnya tersedia melalui antarmuka baris perintah (CLI) dan server MCP. Hal ini memberikan tempat yang tahan lama bagi agen pengkodean untuk mengingat keputusan, panduan operasional, dan pelajaran yang harus tetap tersimpan bahkan setelah percakapan berakhir.

Dalam tutorial ini, kita akan membangun proyek memori kecil untuk tim aplikasi. Kita akan mencatat informasi mengenai caching, otentikasi, deployment, dan cadangan data, kemudian mengambil catatan yang tepat menggunakan pencarian semantik dan hibrida.

Milvus akan menyimpan vektor dan menjalankan pencarian kesamaan. Basic Memory akan terus mengelola catatan Markdown, metadata proyek, pencarian teks lengkap, dan manifest vektor di PostgreSQL.

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

Tutorial ini menggunakan Milvus Lite, yang berjalan secara lokal di jalur tertentu pada mesin Anda. Konfigurasi Basic Memory yang sama nantinya dapat diarahkan ke Milvus Standalone, Milvus Distributed, atau Zilliz Cloud.

Prasyarat

Anda memerlukan:

• Python 3.12 atau yang lebih baru
• uv
• Database PostgreSQL dan URL koneksinya ( postgresql+asyncpg://... )
• Kunci API OpenAI

Instal Basic Memory beserta dependensi opsional Milvus dari PyPI:

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

Konfigurasikan Basic Memory

Buat ruang kerja untuk tutorial ini. Menyimpan konfigurasi Basic Memory dan data Milvus Lite di sini memudahkan pemeriksaan contoh dan penghapusan nanti.

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

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

Konfigurasikan PostgreSQL sebagai basis data utama, OpenAI sebagai penyedia embedding, dan Milvus sebagai indeks vektor:

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

Di sini, BASIC_MEMORY_MILVUS_URI adalah jalur lokal, sehingga PyMilvus secara otomatis menjalankan Milvus Lite. Tidak diperlukan server Milvus terpisah.

Milvus bersifat opsional di Basic Memory secara keseluruhan, tetapi ini adalah backend vektor yang dipilih dalam tutorial ini. Pilihan ini saat ini hanya berlaku jika backend basis data utama adalah PostgreSQL. Proyek Basic Memory berbasis SQLite menggunakan sqlite-vec sebagai gantinya.

Buat proyek memori

Proyek Basic Memory memetakan sebuah nama ke direktori catatan Markdown. Tambahkan direktori tutorial sebagai proyek dan jadikan sebagai default:

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

Tim aplikasi kini memiliki ruang memori yang tahan lama. Mari kita isi ruang tersebut dengan katalog kecil yang beragam. Beberapa catatan akan relevan dengan pertanyaan-pertanyaan kita nanti, sementara yang lain berfungsi sebagai pengalih perhatian yang realistis.

Rekam memori proyek

Mulailah dengan keputusan aplikasi terkait penyimpanan sementara:

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

Catat bagaimana token otentikasi ditangani:

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

Tambahkan dua buku panduan operasional:

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

Terakhir, tambahkan dua catatan produk yang tidak terkait. Hal ini membuat latihan pencarian lebih representatif daripada katalog di mana setiap dokumen relevan:

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

Setiap catatan tetap berupa file Markdown biasa di bawah notes/. Basic Memory menambahkan struktur yang dapat dicari tanpa menghilangkan kendali atas sistem berkas.

Buat indeks pencarian

Jalankan pengindeksan ulang penuh setelah menambahkan atau mengubah secara substansial sekelompok catatan:

bm reindex --full --project app-memory

Selama langkah ini, Basic Memory:

1. Membaca dan membagi catatan Markdown menjadi bagian-bagian kecil.
2. Membuat indeks teks lengkap PostgreSQL.
3. Mengirim potongan-potongan tersebut ke model embedding OpenAI yang telah dikonfigurasi.
4. Menyimpan vektor hasil ke dalam koleksi Milvus khusus proyek.
5. Menandai potongan yang berhasil disimpan sebagai "siap" dalam manifes vektor PostgreSQL-nya.

Basic Memory menggunakan koleksi Milvus yang deterministik untuk setiap proyek. Anda tidak perlu membuat atau memberi nama koleksi tersebut sendiri.

Mengambil memori berdasarkan makna

Misalkan seorang insinyur baru ingat bahwa aplikasi memiliki optimasi untuk permintaan berulang, tetapi tidak ingat bahwa tim menyebutnya sebagai strategi caching.

Gunakan pencarian vektor untuk mengajukan pertanyaan dalam bahasa alami:

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

Caching Strategy harus menjadi hasil teratas meskipun kueri tersebut tidak perlu mengulangi judul catatan. Pencarian vektor menyematkan pertanyaan tersebut dan meminta Milvus untuk mencari potongan yang tersimpan terdekat.

Skor yang tepat dan hasil dengan peringkat lebih rendah dapat bervariasi tergantung pada model embedding dan isi proyek.

Gabungkan sinyal semantik dan kata kunci

Sekarang bayangkan menanggapi insiden keamanan. Kueri tersebut berisi istilah yang tepat seperti " JWT", tetapi kita juga ingin bahasa yang terkait secara konseptual tentang pencabutan token dan masuk kembali.

Gunakan pencarian hibrida:

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

Authentication Tokens harus menjadi hasil teratas. Basic Memory menggabungkan pencarian teks lengkap PostgreSQL dengan pencarian vektor Milvus, mengutamakan konten yang kuat di salah satu jalur tersebut dan terutama konten yang ditemukan oleh keduanya.

Ketiga mode pencarian ini memiliki kelebihan masing-masing:

Mode	Bendera perintah	Penggunaan terbaik
Teks lengkap	Tanpa bendera mode	Istilah, frasa, dan kueri kata kunci boolean yang tepat
Vektor	--vector	Parafrasa, konsep, dan pertanyaan eksploratif
Hibrida	--hybrid	Pencarian serbaguna yang menggunakan sinyal kata kunci dan semantik

Gunakan deployment Milvus lainnya

Kode aplikasi dan perintah Basic Memory tidak berubah saat Anda beralih dari Milvus Lite. Ubah URI dan, jika diperlukan, berikan token.

Untuk server Milvus:

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

Untuk Zilliz Cloud:

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

Buat koleksi target baru atau ikuti prosedur migrasi penyimpanan vektor Basic Memory sebelum mengalihkan proyek yang sudah ada antara backend vektor. Kemudian bangun ulang vektor-vektor tersebut:

bm reindex --full --project app-memory

Gunakan memori yang sama melalui MCP

CLI berguna untuk pengaturan, pemeliharaan, pembuatan skrip, dan memahami alur data. Dalam pekerjaan sehari-hari, klien MCP dapat memulai layanan Basic Memory yang sama dan memanggil alat-alat seperti write_note, search_notes, dan build_context secara langsung.

Misalnya, konfigurasi Codex MCP dapat menjalankan perintah yang diinstal oleh 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-***********"

Klien MCP lainnya menggunakan file executable yang sama beserta argumen dalam bentuk 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-***********"
      }
    }
  }
}

Simpan kata sandi basis data dan kunci API di manajemen rahasia klien atau lingkungan peluncuran Anda jika memungkinkan. Persyaratan pentingnya adalah proses MCP menerima konfigurasi Basic Memory yang sama dengan yang digunakan oleh CLI.

Apa yang dimiliki oleh setiap lapisan penyimpanan

Di akhir tutorial, tanggung jawab dipisahkan secara sengaja:

• Direktori proyek memiliki catatan Markdown asli.
• PostgreSQL mengelola proyek, entitas, metadata, indeks teks lengkap, dan manifest vektor otoritatif Basic Memory.
• OpenAI mengubah potongan catatan dan pertanyaan pencarian menjadi embedding.
• Milvus mengelola penyimpanan vektor dan proses pencarian tetangga terdekat.
• Basic Memory mengoordinasikan lapisan-lapisan tersebut dan menyediakan satu antarmuka CLI dan MCP.

Oleh karena itu, Milvus tidak menggantikan PostgreSQL dalam integrasi ini. Milvus menggantikan jalur " pgvector " PostgreSQL untuk penyimpanan vektor dan pencarian kesamaan, sementara fitur-fitur relasional dan teks lengkap Basic Memory lainnya tetap berada di PostgreSQL.