Lumena MCP Server

Was ist Lumena?

Lumena ist ein lokaler Speicher für LLM-Agenten – es organisiert Agentengedächtnisse in einem strukturierten Gedächtnispalast (Räume, Loci, Chunks) mit hybridem Abruf, verwaltetem Verfall und nativen Integrationen. Es läuft vollständig auf Ihrer eigenen Hardware ohne Cloud-Abhängigkeiten.

• Keine Cloud. Embeddings laufen lokal über ONNX Runtime. Der Speicher ist eine einzelne SQLite-Datei.

• Optionaler Daemon. Der Hintergrundplaner startet automatisch mit lumena serve; kann auch selbständig mit lumena daemon start laufen.

• Hybrider Abruf. BM25 (SQLite FTS5), Vektorsuche nach Kosinusähnlichkeit und optional Graph-Traversal mit Reciprocal-Rank-Fusion.

• Verwalteter Speicherlebenszyklus. Vergessen auf drei Ebenen: zeitbasierter Verfall, Interferenz durch Ähnlichkeit und Räumung nach Budget.

• Integrationen. LangGraph-Checkpoint-Saver, LangChain-Speicheradapter, MCP-Server, FastAPI-REST-API.

Related MCP server: engram

Schnellstart

# 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

Beim ersten Lauf wird ein Einbettungsmodell benötigt. Standardmäßig versucht lumena, eines zu exportieren, was die umfangreiche [export]-Toolchain erfordert. Der schlanke, empfohlene Weg ist ein vorgefertigtes Modellpaket (ohne Toolchain): setzen Sie LUMENA_PREBUILT_MODEL_URL oder verwenden Sie den Ein-Befehl-Installer.

Installationsoptionen (Extras)

Die Standardinstallation ist bewusst schlank (kein torch/CUDA). Fügen Sie Extras nur hinzu, wenn sie benötigt werden:

Speichern und abrufen

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

API-Endpunkte

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

Architektur

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

Projektstand

Lumena ist produktionsreife Software. Es arbeitet End-to-End mit API-Versionierung, umfassenden Tests und dokumentierten Einschränkungen für die Sicherheit. Es ist geeignet für Produktion, Evaluierung, Entwicklung und vertrauenswürdige LAN-Bereitstellungen.

Benchmark-Suiten

Alle laufen mit einem einzigen Befehl, ohne gegenüberliegende Kommandozeile – from repo root:

Hinweis zu Ergebnissen: : Die Retrieval-Benchmarks verwenden einen synthetischen Korpus mit Keyword-Überlappung (1.000 Passagen, 50 Abfragen) plus BEIR-Teilmenge (500-Passagen- und 20-Abfrage-Untermengen aus 5 Standarddatensätzen). Der synthetische Korpus ist absichtlich einfach (BM25 erreicht fast die nDCG-Decke). Betrachten Sie diese Zahlen also nur als Funktionsprüfung der Umgebung, nicht als Indikator für Retrival-Qualität – Die BEIR-Teilmengen sind das aussagekräftige Signal. Das redundante Artefakt wurde mit echten Embeddern neu erzeugt (all-MiniLM-L6-v2 und BAAI/bge-small-en-v1.5);. Die Benchmark läuft mit Mock-Embeddings nicht.

Integrationen

Projektstruktur

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

Mach mit

Wir freuen uns über Beiträger. So stoßen Sie am besten ein:

1. Lesen Sie CONTRIBUTING.md – Einrichtung, Benennung der Branches, Code-Standards.

2. Suchen Sie eine good first issue aus dem Issue-Tracker.

3. Führen Sie die Tests aus: pytest tests/ (muss mit ≥50 % Abdeckung bestanden).

4. Senden Sie einen Pull-Request gegen main.

Bereiche, die besonders hilfreich bewäwherender schon:

• Führen Sie die komplette BEIR-Testumgebung aus – Generate Leaderboard-Benchmark-Ergebnisse.

• Optische die Performance-Suite auf echter Hardware – Behauptungen zu RAM/Latenz brauchen messbare Geräte (RPi5, Jetson, x86_64).

• Ergänzen Sie Tests – mehreren Modulen fehlen Testdateien. Sooden Sie mit einer aus.

Entwicklungssetup

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

Dokumentation

Community

• GitHub Discussions

• Issue-Tracker

• Sicherheitshinweise

• Matrix: #lumena:matrix.org

Lizenz

Lumena ist dual-lizenziert:

• Community Edition — AGPL-3.0-or-later. Frei und Open Source. Wenn Sie ein modifiziertes Lumena als Netzwerkdienst betreiben, verlangt die AGPL, dass Sie Ihren Quellcode den Benutzern zur Verfügung stellen.

• Pro / Commercial Edition — eine kommerzielle Lizenz von QuantumindSSI, die die AGPL-Verpflichtungen aufhebt und Pro-Funktionen freischaltet. Siehe COMMERCIAL-LICENSE.md.

Versionen bis einschließlich v1.0.0 wurden unter Apache 2.0 (LICENSES/Apache-2.0.txt) veröffentlicht; diese Gewährung für diese Versionen ist unwiderruflich. Kommerzielle Anfragen: licensing@quantumindssi.com.