mnemo: Capa de Memoria Local-First para LLMs

Una capa de memoria local-first para LLMs

mnemo es una capa de memoria local-first que proporciona contexto persistente a las aplicaciones de LLM sin dependencia alguna de la nube. Se ejecuta como un servicio sidecar, ingiere texto sin procesar, extrae entidades y relaciones con un LLM configurable y construye un grafo de conocimiento en SQLite.
El grafo es el diferenciador clave: las entidades se deduplican entre sesiones, las relaciones se ponderan y la recuperación utiliza una cadena de 6 etapas: búsqueda de texto completo, búsqueda por nombre de entidad, expansión del grafo con BFS, filtrado de relaciones, puntuación y ensamblado de una cadena de contexto.
Los resultados expandidos por el grafo se puntúan a 0.5× para que las coincidencias directas siempre ocupen un puesto superior.
Esto produce una memoria estructurada y autónoma que controlas por completo, ideal cuando necesitas inyectar contexto pasado relevante en el prompt de sistema del modelo dentro de pipelines personalizados.

git clone https://github.com/zaydmulani09/mnemo
cd mnemo
docker compose up -d

# Pull the llama3 model the first time (~4 GB)
docker exec mnemo-ollama ollama pull llama3

# Verify everything is healthy
curl http://localhost:8080/health

Otras vías de instalación

También puedes instalar mnemo como un binario independiente mediante Cargo. Configura las variables de entorno para que apunten a una instancia local de Ollama o a cualquier API compatible con OpenAI, y luego ejecuta mnemo-api.
Para proyectos Python, el paquete mnemo-sdk envuelve la API:

from mnemo import MnemoClient

client = MnemoClient()  # server at http://localhost:8080

# Store a memory
client.ingest("I'm building a Rust vector database called vecdb")

# Get context for injection into your next LLM prompt
print(client.get_context("what am I working on?"))

# Store a memory
mnemo ingest "I use Neovim and prefer dark mode"

# Retrieve relevant context
mnemo search "what editor do I use?"

# List all extracted entities
mnemo entities

# Show entity detail + graph neighbors
mnemo entity <uuid> --neighbors

# List memory chunks
mnemo chunks

# Server health
mnemo health

# Memory statistics
mnemo stats

# Delete everything (prompts for confirmation)
mnemo wipe

# Skip confirmation prompt
mnemo wipe --yes

# Point at a non-default server
mnemo --server http://192.168.1.10:8080 stats

API HTTP principal

Todos los endpoints aceptan y devuelven JSON en http://localhost:8080.
Endpoints clave:

• GET /health – estado del servidor, la base de datos y el LLM.
• POST /ingest – almacenar texto; incluye un session_id para agrupar turnos relacionados.
• POST /retrieve – ejecuta la cadena completa de memoria y devuelve una cadena context_prompt que proporciona contexto persistente para tu siguiente llamada al LLM. Puedes controlar max_chunks, max_entities, min_confidence (predeterminado 0.5), include_graph (predeterminado true) y graph_depth (predeterminado 2).
• GET /entities, GET /chunks – listado paginado, más un POST /search para búsquedas de texto completo.
• DELETE /wipe – borrado completo irreversible; requiere la cabecera de confirmación X-Confirm-Wipe: true.
• GET /stats – contadores y tiempo de actividad.

Una referencia completa se encuentra en docs/api.md.

Configuración

La configuración se toma de variables de entorno y de un archivo TOML opcional (pasado con --config).
Variables clave:
MNEMO_DB_PATH (archivo sqlite), MNEMO_PORT (8080), MNEMO_LLM_BASE_URL, MNEMO_LLM_MODEL (llama3), MNEMO_LLM_API_KEY y MNEMO_LLM_PROVIDER (ollama, openai, anthropic o custom).
Las variables de entorno siempre tienen prioridad sobre los valores del archivo TOML. La fuente de configuración activa se informa en GET /health → config_source. Se proporciona un archivo de ejemplo en mnemo.example.toml.

Restricciones y best practices

Limitaciones:

• No es un reemplazo de frameworks de agentes gestionados que ya manejan memoria.
• Los resultados expandidos mediante el grafo se puntúan a 0.5×, por lo que las coincidencias directas siempre superan a las conexiones inferidas.
• La profundidad de vecinos está limitada a 5. La eliminación de entidades se propaga en cascada (se eliminan las relaciones). El borrado completo es irreversible.

best practices:

• Usa session_id para limitar el alcance de la recuperación.
• Configura min_confidence (≥ 0.5) para filtrar extracciones de baja calidad.
• Desactiva la expansión del grafo (include_graph: false) cuando solo necesites coincidencias directas.
• Ejecuta en modo --release para obtener ganancias de velocidad de 3 a 5 veces.
• Prefiere las variables de entorno en despliegues contenedorizados.
• Comienza con la ruta Docker + Ollama para una configuración completamente local y sin costo.