Lumena Server

        ┌───┐
     ┌──┤   ├──┐
     │  │ ✦ │  │
     └──┤   ├──┘
        └───┘

What is Lumena?

Lumena is a local-first memory store for LLM agents — it organizes agent memories in a structured memory palace (rooms, loci, chunks) with hybrid retrieval, managed decay, and native integrations. It runs entirely on your hardware with no cloud dependencies.

• No cloud. Embeddings run locally via ONNX Runtime. Storage is single-file SQLite.
• Optional daemon. Background scheduler auto-starts with lumena serve; can also run standalone with lumena daemon start.
• Hybrid retrieval. BM25 (SQLite FTS5), cosine-similarity vector search, and optional graph traversal with reciprocal rank fusion.
• Managed memory lifecycle. Three-layer forgetting: time-based decay, similarity interference, and budget eviction.
• Integrations. LangGraph checkpoint saver, LangChain memory adapter, MCP server, FastAPI REST API.

Quick Start

# 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

First run needs an embedding model. By default lumena will try to export one, which requires the heavy [export] toolchain. The lean, recommended path is a prebuilt model bundle (no toolchain): set LUMENA_PREBUILT_MODEL_URL or use the one-command installer.

Install options (extras)

The base install is deliberately lean (no torch/CUDA). Add extras only when needed:

Store and retrieve

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 endpoints

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

Architecture

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

State of the Project

Lumena is production-ready software. It works end-to-end with API versioning, comprehensive tests, and documented security limitations. It is suitable for production, evaluation, development, and trusted-LAN deployments.

Benchmark Suites

All run with a single command from the repo root:

Note on results: Retrieval benchmarks use a synthetic keyword-overlap corpus (1,000 passages, 50 queries) plus BEIR subset evaluation (500-passage, 20-query subsets across 5 standard datasets). The synthetic corpus is deliberately easy (BM25 near-saturates nDCG), so treat those numbers as harness sanity checks, not retrieval-quality claims — the BEIR subsets are the meaningful signal. The committed retrieval artifact was regenerated with real embedders (all-MiniLM-L6-v2 and BAAI/bge-small-en-v1.5); benchmarks refuse to run with mock embeddings.

Integrations

Project Structure

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

Contributing

We welcome contributions. The best way to start:

1. Read CONTRIBUTING.md — setup, branch naming, code standards.
2. Pick a good first issue from the issues tracker.
3. Run the tests: pytest tests/ (must pass with ≥50% coverage).
4. Submit a PR against main.

High-impact areas to contribute

• Run the full BEIR harness — generate leaderboard-scale retrieval benchmark results.
• Run the perf suite on real hardware — RAM/latency footprint claims need measured artifacts (RPi5, Jetson, x86_64).
• Write tests — several modules lack dedicated test files. Pick one and add coverage.

Development setup

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

Documentation

Community

• GitHub Discussions
• Issue Tracker
• Security Advisories
• Matrix: #lumena:matrix.org

License

Lumena is dual-licensed:

• Community Edition — AGPL-3.0-or-later. Free and open source. If you run a modified Lumena as a network service, AGPL requires you to make your source available to its users.
• Pro / Commercial Edition — a commercial license from QuantumindSSI that removes the AGPL obligations and unlocks Pro features. See COMMERCIAL-LICENSE.md.

Versions up to and including v1.0.0 were released under Apache 2.0 (LICENSES/Apache-2.0.txt); that grant on those releases is irrevocable. Commercial inquiries: [email protected].