Lumena MCP Server

¿Qué es Lumena?

Lumena es un almacén de memoria local-first para agentes LLM — organiza las memorias de los agentes en un palacio de memoria estructurado (habitaciones, loci, fragmentos) con recuperación híbrida, decaimiento gestionado e integraciones nativas. Se ejecuta íntegramente en tu hardware sin dependencias en la nube.

• Sin nube. Los embeddings se ejecutan localmente mediante ONNX Runtime. El almacenamiento es un único archivo SQLite.

• Daemon opcional. El programador en segundo plano se inicia automáticamente con lumena serve; también puede ejecutarse de forma independiente con lumena daemon start.

• Recuperación híbrida. BM25 (SQLite FTS5), búsqueda vectorial por similitud coseno y recorrido de grafos opcional con fusión de rango recíproco.

• Ciclo de vida de memoria gestionado. Olvido en tres capas: decaimiento basado en el tiempo, interferencia por similitud y expulsión por presupuesto.

• Integraciones. Guardador de puntos de control de LangGraph, adaptador de memoria de LangChain, servidor MCP, API REST FastAPI.

Related MCP server: engram

Inicio rápido

# Clone and install (lean runtime — no torch/CUDA)
git clone https://github.com/QuantumindSSI/lumena.git
cd lumena
pip install -e .            # runtime: sqlite-vec, onnxruntime, transformers tokenizer…

# Initialize
lumena init --device generic

# Start the server
lumena serve
# Dashboard at http://localhost:8848/dashboard
# API docs at http://localhost:8848/docs

La primera ejecución necesita un modelo de embeddings. Por defecto, lumena intentará exportar uno, lo que requiere el pesado conjunto de herramientas [export]. La vía recomendada y ligera es un paquete de modelo precompilado (sin conjunto de herramientas): establece LUMENA_PREBUILT_MODEL_URL o usa el instalador de un solo comando.

Opciones de instalación (extras)

La instalación base es deliberadamente ligera (sin torch/CUDA). Añade extras solo cuando los necesites:

Almacenar y recuperar

from lumena.config import LumenaConfig
from lumena.data.schema import get_connection
from lumena.force.mnemonic.store import store_memory

config = LumenaConfig()
conn = get_connection(config)

chunk_id = store_memory(
    conn,
    content="User prefers dark mode and large fonts",
    room_name="preferences",
    config=config,
)
conn.close()

from lumena.config import LumenaConfig
from lumena.data.schema import get_connection
from lumena.conversation import ConversationMemory

config = LumenaConfig()
conn = get_connection(config)
memory = ConversationMemory(config=config, conn=conn)

turn = memory.retrieve_and_assemble("What UI settings does the user like?")
print(turn.assembled_context)

$ lumena status
Lumena Status
Device: generic
Rooms: 5
Active chunks: 58
Context budget: 2048 tokens
TFC → e=0.50 a=0.50 tau=7.0 r=3

Puntos finales de la API

GET  /health            Liveness probe (unversioned)
GET  /dashboard         Effectiveness dashboard (HTML)
GET  /metrics           Machine-readable metrics
GET  /v1/status        Palace overview
POST /v1/search       Semantic + lexical hybrid search
POST /v1/store        Store a memory chunk
POST /v1/feedback     Log explicit or implicit feedback
POST /v1/assemble     Retrieve + assemble context in one call
POST /v1/turn         Store full conversation turn
GET  /v1/dashboard-data Dashboard data as JSON

Arquitectura

User Input → Intent Router → Parallel Retrieval (BM25 + Dense + Graph)
                                  │
                                  ▼
                          RRF Fusion × V(m) × Recency
                                  │
                                  ▼
                          Context Assembly (Jinja2)
                                  │
                                  ▼
                    Consolidation → Decay / Interference / Eviction

Estado del proyecto

Lumena es software listo para producción. Funciona de extremo a extremo con versionado de API, pruebas exhaustivas y limitaciones de seguridad documentadas. Es adecuado para producción, evaluación, desarrollo y despliegues en LAN de confianza.

Suites de puntos de referencia

Todas se ejecutan con un solo comando desde la raíz del repositorio:

Nota sobre los resultados: Los puntos de referencia de recuperación usan un corpus sintético de solapamiento de palabras clave (1.000 pasajes, 50 consultas) además de la evaluación del subconjunto BEIR (subconjuntos de 500 pasajes y 20 consultas en 5 conjuntos de datos estándar). El corpus sintético es deliberadamente fácil (BM25 casi satura nDCG), así que trata esos números como comprobaciones de validez del marco, no como afirmaciones de calidad de recuperación — los subconjuntos BEIR son la señal significativa. El artefacto de recuperación incluido se regeneró con embedders reales (all-MiniLM-L6-v2 y BAAI/bge-small-en-v1.5); los puntos de referencia se niegan a ejecutarse con embeddings simulados.

Integraciones

Estructura del proyecto

lumena/
├── config.py          Configuration (pydantic-settings)
├── search.py          Search pipeline orchestration
├── fusion.py          RRF fusion + reranking
├── controller.py      Twin-Force state controller
├── conversation.py    Context assembly + turn tracking
├── repair.py          Self-healing retrieval
├── intent.py          Intent router (keyword + optional LR)
├── api/               FastAPI server + dashboard
├── cli/               Typer CLI
├── data/              Schema, migrations, backup
├── force/
│   ├── mnemonic/      Store, retrieval, decay, interference, eviction, provenance
│   └── contextual/    Embedding, token budget, assembly
├── integrations/      LangChain, LangGraph, MCP server
├── p2p/               Beam P2P sharing protocol
├── sovereign/         FRQAD, optical quantization, local LLM
├── brand/             Error hierarchy
└── compliance/        Safety forgetting, PII audit
tests/                43 test files, 327 tests
benchmarks/           11 benchmark suites

Contribuciones

Agradecemos las contribuciones. La mejor forma de empezar:

1. Lee CONTRIBUTING.md — configuración, convenciones de nombres de ramas, estándares de código.

2. Elige un good first issue del rastreador de incidencias.

3. Ejecuta las pruebas: pytest tests/ (deben pasar con ≥50% de cobertura).

4. Envía un PR contra main.

Áreas de alto impacto para contribuir

• Ejecuta el marco BEIR completo — genera resultados de puntos de referencia de recuperación a escala de clasificación.

• Ejecuta la suite de rendimiento en hardware real — las afirmaciones sobre huella de RAM/latencia necesitan artefactos medidos (RPi5, Jetson, x86_64).

• Escribe pruebas — varios módulos carecen de archivos de prueba dedicados. Elige uno y añade cobertura.

Configuración de desarrollo

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/                        # Run full suite
pytest tests/ --cov=lumena            # With coverage
ruff check lumena/ tests/             # Lint

Documentación

Comunidad

• GitHub Discussions

• Seguimiento de incidencias

• Avisos de seguridad

• Matrix: #lumena:matrix.org

Licencia

Lumena tiene doble licencia:

• Community Edition — AGPL-3.0-o-posterior. Libre y de código abierto. Si ejecutas una versión modificada de Lumena como servicio de red, AGPL te exige que pongas tu código fuente a disposición de sus usuarios.

• Pro / Commercial Edition — una licencia comercial de QuantumindSSI que elimina las obligaciones de AGPL y desbloquea las funciones Pro. Consulta COMMERCIAL-LICENSE.md.

Las versiones hasta la v1.0.0 inclusive se publicaron bajo Apache 2.0 (LICENSES/Apache-2.0.txt); esa concesión en esas versiones es irrevocable. Consultas comerciales: licensing@quantumindssi.com.