🌙 luminary-memory

A lightweight, self-hosted memory layer for AI agents.

Self-hosted · Private · Budget-aware · Self-maintaining

What your agent remembers is what it becomes.

Agents are only as good as what they remember. A stateless agent re-learns the same context every session, paying the same tokens, making the same mistakes. luminary-memory closes that gap with a local memory store that persists between runs, retrieves the right context on demand, and keeps itself tidy over time.

Four retrieval strategies. One fused answer. Zero cloud.

• Semantic, ONNX embeddings (384-dim, CPU, no GPU needed)
• Keyword, FTS5 BM25 (SQLite, zero config)
• Temporal, recency decay × access count
• Graph, entity co-occurrence with automatic curation

Strategies run in parallel and fuse via weighted RRF (semantic 0.4, keyword 0.3, graph 0.2, temporal 0.1) → adaptive cutoff (cliff detection) → Jaccard deduplication (0.85) → token budget (4096). Short queries are expanded with graph entities before embedding, so "deploy?" still finds "production cluster".

Important rules always in context. In the Hermes provider, the top-N most important memories are injected every turn (persistent context) and merged with query recall under anti-duplication — so the agent never forgets a rule that exists in the store. Rules are pinned (never pruned), and similar rule ingests auto-replace the old one instead of stacking contradictions. Core memory (tagged core) is auto-loaded into the system prompt every session — the DB-backed equivalent of MEMORY.md — so durable rules are present from the very first prompt, no query needed.

Quickstart

pip install luminary-memory

from luminary_memory import MemoryClient

client = MemoryClient(db_path="memory.db")

# store a durable fact
client.ingest("The deploy target is the staging cluster", tags=["deploy", "infra"])

# recall, four strategies fused into one ranked answer
result = client.recall("where do we deploy?")
for memory, score in zip(result.memories, result.scores):
    print(f"{score:.3f}  {memory.content}")
# → 0.942  The deploy target is the staging cluster

# CLI
luminary-memory add "deploy target is staging" --tags deploy
luminary-memory recall "where do we deploy?" --json
luminary-memory list
luminary-memory lifecycle
luminary-memory stats

Hermes Agent, first-class memory provider

Drop-in. Install the provider with pip install "luminary-memory[hermes]", then add memory.provider: luminary to your Hermes config. That's it.

From the next session: auto-recall injects relevant memories every turn, auto-save persists completed turns, and the model can call luminary_recall / luminary_ingest / luminary_list on demand.

Two optional LLM-powered features keep the store sharp:

• ingest_llm, evaluates every turn before saving: drops chit-chat, stores factual summaries instead of raw transcripts.
• auto_maintain, reviews the store at session end: keeps current facts, updates changed ones, deletes stale or duplicate ones.

22 settings are exposed in the Hermes dashboard for zero-hassle tuning. See hermes/README.md for the one-shot installer and full configuration.

Configuration

Every setting has a LUMINARY_* env var or a Settings object.

Provider-specific settings (Hermes dashboard): max_memories, context_*, mode, recall_limit, auto_recall, recall_sync, auto_retain, retain_every_n_turns, retain_user_prefix / retain_assistant_prefix, ingest_llm, auto_maintain, consolidate_semantic, importance_auto, recall_indicator, retain_indicator — live in ~/.hermes/luminary/config.json. See hermes/SKILL.md for the full provider config table.

Architecture

Memory is a loop, not a pipeline you run once. Every turn, luminary recalls what is relevant before the agent answers, then ingests what mattered after, and a background lifecycle keeps the store lean.

        ┌───────────────────────────── LOOP ─────────────────────────────┐
        │                                                               │
   recall(query) ──► 4 strategies in parallel ──► weighted RRF ──► adaptive cutoff ──► ranked results
        ▲            semantic │ keyword │ temporal │ graph   (per-strategy weights)   (cliff detection)
        │                                                               │
        └── inject into agent context ◄── token budget (4096) ◄── dedup (Jaccard 0.85)
                                                            │            │
   persistent context ──► top-N by importance every turn ──┘ (merged, anti-duplicated)
                                                            │
   ingest(text) ──► whitelist ──► (LLM curation) ──► embed (ONNX 384-d) ─┘
                                                            │
   lifecycle() ──► cleanup (TTL) ──► consolidate (semantic + Jaccard, pinned exempt) ──► prune (importance, pinned exempt)
   maintenance() ──► LLM reviews store ──► keep │ update │ delete stale facts

Why it is accurate:

Why it stays clean:

health_score() gives you a 0-100 checkup with actionable recommendations.

Documentation

License

Apache-2.0 © 2026 Dwiky Candra