llama-memory

Servicio de Memoria MCP para llama-server con historial persistente y memoria semántica mediante Postgres + PGVector.

Nota: Este proyecto está pensado para uso local/demostrativo únicamente. No lo expongas directamente a internet sin un endurecimiento adicional (HTTPS, autenticación adecuada, copias de seguridad).

Qué hace

• Memoria semántica: guarda y recupera recuerdos por significado, no solo por palabras clave.

• Puente de conversación: el LLM crea conversaciones automáticamente; los recuerdos quedan vinculados.

• Recuerdo entre sesiones: pregunta "¿de qué hablamos antes?" y obtén respuestas precisas.

• Protocolo MCP: funciona directamente con el soporte MCP integrado de llama-server.

Related MCP server: engram

Requisitos

• Python 3.11 (se recomienda Miniconda)

• PostgreSQL 16+ con la extensión PGVector

• llama-server con la bandera --jinja (necesaria para la llamada a herramientas)

• nomic-embed-text ejecutándose en llama-server (puerto 8081 por defecto)

Instalación

# Clone the repo
git clone https://github.com/noualit/llama-memory-local.git
cd llama-memory-local

# Create environment
conda create -n llama-memory python=3.11
conda activate llama-memory

# Install dependencies
pip install -e .

Configuración

Copia .env.example a .env y edítalo:

cp .env.example .env

Ejemplo:

# Database
DATABASE_URL="postgresql://postgres:yourpassword@localhost:5432/llamamem"

# Llama-server (LLM)
LLAMA_SERVER_BASE_URL="http://localhost:8080"

# Embedding model (nomic-embed-text via llama-server)
EMBEDDING_MODEL_URL="http://localhost:8081"

# Embedding model name (default: nomic-embed-text)
EMBEDDING_MODEL_NAME="nomic-embed-text"

# Service port
SERVICE_PORT=9001

Configurar la base de datos

Crea la base de datos y ejecuta las migraciones:

psql -U postgres -c "CREATE DATABASE llamamem;"
alembic upgrade head

La aplicación también garantiza el esquema básico al iniciar por conveniencia.

Ejecutar el servicio

# Using the script
.\scripts\run_server.ps1

# Or directly
python -m uvicorn app.main:app --host 0.0.0.0 --port 9001

Conectar a llama-server

Añade a tu configuración MCP de llama-server:

{
  "mcpServers": {
    "llama-memory": {
      "url": "http://YOUR_SERVER_IP:9001/mcp"
    }
  }
}

El servicio debe ser accesible desde llama-server. Usa la IP real, no localhost, si se ejecutan en máquinas diferentes.

Herramientas MCP

Prompt del sistema

Puedes:

• Obtener el prompt del sistema recomendado desde el servicio:

  • GET /system-prompt → devuelve texto plano.

• O pegar esta versión mínima en llama-server:

MEMORY WORKFLOW:
- At the start of each new conversation, call create_conversation with a short title.
- Use the conversation_id from create_conversation when calling save_memory.
- Before answering questions about past topics, call search_memories FIRST.
- When the user shares important information, save it with save_memory.
- If list_conversations has previous chats, check get_conversation_history for context.

Comprobación de estado

curl http://localhost:9001/health

Devuelve el estado de la base de datos, el estado del servicio de incrustaciones y el recuento de herramientas.

Arquitectura

Estructura de alto nivel:

• app/main.py — Aplicación FastAPI, ciclo de vida, /system-prompt

• app/settings.py — Configuración de Pydantic desde .env

• app/clients/embeddings.py — Llama a nomic-embed-text para vectores

• app/db/engine.py — Grupo de conexiones asyncpg (singleton)

• app/db/schema.py — Crea tablas automáticamente al iniciar

• app/mcp/endpoint.py — Manejadores del protocolo MCP, limitador de velocidad

• app/mcp/tools/ — Implementaciones de herramientas individuales

• migrations/ — Migraciones de base de datos Alembic

Desarrollo

# Run tests
pytest tests/ -v

# Run with auto-reload
python -m uvicorn app.main:app --host 0.0.0.0 --port 9001 --reload

Consulta CONTRIBUTING.md para las pautas de contribución.

Licencia

MIT (consulta el archivo LICENSE).