Crear una memoria semántica del proyecto con Basic Memory y Milvus

Basic Memory almacena el conocimiento del proyecto en archivos Markdown normales y lo pone a disposición a través de una interfaz de línea de comandos (CLI) y un servidor MCP. Esto proporciona a un agente de programación un lugar permanente donde recordar decisiones, guías operativas y lecciones que deben conservarse más allá de una sola conversación.

En este tutorial, crearemos un pequeño proyecto de memoria para un equipo de desarrollo de aplicaciones. Registraremos notas sobre el almacenamiento en caché, la autenticación, las implementaciones y las copias de seguridad, y luego recuperaremos la nota adecuada mediante la búsqueda semántica e híbrida.

Milvus almacenará los vectores y realizará la búsqueda por similitud. Basic Memory seguirá gestionando las notas Markdown, los metadatos del proyecto, la búsqueda de texto completo y el manifiesto de vectores en PostgreSQL.

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

Este tutorial utiliza Milvus Lite, que se ejecuta localmente en una ruta de tu equipo. La misma configuración de Basic Memory puede apuntar posteriormente a Milvus Standalone, Milvus Distributed o Zilliz Cloud.

Requisitos previos

Necesitas:

• Python 3.12 o posterior
• uv
• Una base de datos PostgreSQL y su URL de conexión postgresql+asyncpg://...
• Una clave de API de OpenAI

Instala Basic Memory con sus dependencias opcionales de Milvus desde PyPI:

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

Configura Basic Memory

Crea un espacio de trabajo para el tutorial. Mantener aquí la configuración de Basic Memory y los datos de Milvus Lite facilita la revisión del ejemplo y su posterior eliminación.

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

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

Configura PostgreSQL como base de datos principal, OpenAI como proveedor de incrustaciones y Milvus como índice vectorial:

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

En este caso, « BASIC_MEMORY_MILVUS_URI » es una ruta local, por lo que PyMilvus inicia Milvus Lite automáticamente. No se requiere un servidor Milvus independiente.

Milvus es opcional en «Memoria básica» en general, pero es el backend vectorial seleccionado en este tutorial. Actualmente, esta selección solo se aplica cuando el backend de la base de datos principal es PostgreSQL. Los proyectos de «Memoria básica» basados en SQLite utilizan en su lugar sqlite-vec.

Crear un proyecto de memoria

Un proyecto de Basic Memory asigna un nombre a un directorio de notas en formato Markdown. Añade el directorio del tutorial como proyecto y configúralo como predeterminado:

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

El equipo de la aplicación dispone ahora de un espacio de memoria duradero. Rellenémoslo con un pequeño catálogo mixto. Algunas notas serán relevantes para nuestras preguntas posteriores, mientras que otras servirán como distracciones realistas.

Registrar las memorias del proyecto

Empieza por la decisión de almacenamiento en caché de la aplicación:

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

Registra cómo se gestionan los tokens de autenticación:

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

Añade dos manuales de operaciones:

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

Por último, añade dos notas sobre productos no relacionadas. Estas hacen que el ejercicio de búsqueda sea más representativo que un catálogo en el que todos los documentos son relevantes:

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

Cada nota sigue siendo un archivo Markdown normal ubicado en notes/. Basic Memory añade la estructura de búsqueda sin restar control al sistema de archivos.

Crea los índices de búsqueda

Ejecuta una reindexación completa tras añadir o modificar sustancialmente un grupo de notas:

bm reindex --full --project app-memory

Durante este paso, Basic Memory:

1. Lee y divide en fragmentos las notas Markdown.
2. Crea el índice de texto completo de PostgreSQL.
3. Envía los fragmentos al modelo de incrustación de OpenAI configurado.
4. Almacena los vectores resultantes en la colección Milvus específica del proyecto.
5. Marca los fragmentos almacenados correctamente como «listos» en su manifiesto de vectores de PostgreSQL.

Basic Memory utiliza una colección Milvus determinista para cada proyecto. No es necesario que crees ni nombres la colección tú mismo.

Recuperar un recuerdo por su significado

Supongamos que un ingeniero nuevo recuerda que la aplicación cuenta con una optimización para las solicitudes repetidas, pero no recuerda que el equipo la denominara «estrategia de almacenamiento en caché».

Utiliza la búsqueda vectorial para formular la pregunta en lenguaje natural:

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

Caching Strategy debería ser el resultado principal, aunque la consulta no tenga que repetir el título de la nota. La búsqueda vectorial incorpora la pregunta y solicita a Milvus los fragmentos almacenados más cercanos.

Las puntuaciones exactas y los resultados de menor rango pueden variar en función del modelo de incrustación y del contenido del proyecto.

Combina señales semánticas y de palabras clave

Ahora imagina que tienes que responder a un incidente de seguridad. La consulta contiene términos exactos como « JWT », pero también queremos lenguaje conceptualmente relacionado con la revocación de tokens y volver a iniciar sesión.

Utiliza la búsqueda híbrida:

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

Authentication Tokens debería ser el resultado principal. Basic Memory combina la recuperación de texto completo de PostgreSQL con la recuperación vectorial de Milvus, dando prioridad al contenido que destaca en cualquiera de las dos vías y, especialmente, al contenido encontrado por ambas.

Los tres modos de búsqueda tienen diferentes puntos fuertes:

Modo	Indicador de comando	Mejor uso
Texto completo	Sin indicador de modo	Términos exactos, frases y consultas con palabras clave booleanas
Vector	--vector	Parafrasis, conceptos y preguntas exploratorias
Híbrido	--hybrid	Búsqueda de uso general que utiliza tanto señales de palabras clave como semánticas

Utiliza otra implementación de Milvus

El código de la aplicación y los comandos de Basic Memory no cambian cuando se supera la capacidad de Milvus Lite. Cambia el URI y, cuando sea necesario, proporciona un token.

Para un servidor Milvus:

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

Para Zilliz Cloud:

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

Crea una nueva colección de destino o sigue el procedimiento de migración del almacén vectorial de Basic Memory antes de cambiar un proyecto existente entre backends vectoriales. A continuación, vuelve a generar los vectores:

bm reindex --full --project app-memory

Utiliza la misma memoria a través de MCP

La CLI resulta útil para la configuración, el mantenimiento, la creación de scripts y la comprensión del flujo de datos. En el trabajo diario, un cliente MCP puede iniciar el mismo servicio de Basic Memory y llamar directamente a herramientas como write_note, search_notes y build_context.

Por ejemplo, una configuración de Codex MCP puede ejecutar el comando instalado por 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-***********"

Otros clientes MCP utilizan el mismo ejecutable y los mismos argumentos en formato 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-***********"
      }
    }
  }
}

Mantenga las contraseñas de la base de datos y las claves de API en el sistema de gestión de secretos de su cliente o en el entorno de ejecución siempre que sea posible. Es fundamental que el proceso de MCP reciba la misma configuración de memoria básica que utiliza la CLI.

Qué gestiona cada capa de almacenamiento

Al final del tutorial, las responsabilidades se separan deliberadamente:

• El directorio del proyecto es responsable de las notas Markdown originales.
• PostgreSQL se encarga de los proyectos, las entidades, los metadatos, el índice de texto completo y el manifiesto vectorial de referencia de Basic Memory.
• OpenAI convierte fragmentos de notas y consultas de búsqueda en representaciones vectoriales.
• Milvus se encarga de la persistencia de vectores y la recuperación del vecino más cercano.
• Basic Memory coordina las capas y ofrece una única experiencia de CLI y MCP.

Por lo tanto, Milvus no sustituye a PostgreSQL en esta integración. Sustituye la ruta « pgvector » de PostgreSQL para el almacenamiento de vectores y la búsqueda de similitudes, mientras que el resto de las funciones relacionales y de texto completo de Basic Memory permanecen en PostgreSQL.