🌙 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 result. Local by default.

• 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
• Active-task session continuity, exact-session episodes preserve short-term context when durable recall abstains without promoting raw turns into semantic memory or widening scope across users, agents, or sessions.

Strategies fuse via weighted RRF (semantic 0.4, keyword 0.3, graph 0.2, temporal 0.1) → scope/status/time filtering → conservative confidence and abstention → adaptive cutoff → Jaccard deduplication → token budget. Short queries may be expanded with graph entities or stored content tokens before embedding; there is no language-specific alias classifier.

Important rules always in context. Durable rules tagged core are auto-loaded into the system prompt every session (the DB-backed MEMORY.md). All other durable memories are surfaced through query retrieval: relevant facts are recalled on demand (ranked by query relevance) and merged with the core block under anti-duplication. When durable recall abstains, the Hermes provider can also expose a bounded exact-session continuity block so an ambiguous follow-up stays attached to its active task without turning raw conversation into durable memory.

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 activity --limit 5
luminary-memory list
luminary-memory lifecycle
luminary-memory stats

Hermes Agent, first-class memory provider

Luminary integrates through Hermes' public MemoryProvider entry point. The installer selects Luminary and disables Hermes' two native persistent-memory surfaces (MEMORY.md and USER.md) using their existing config switches, so the agent has one durable memory authority without a Hermes source patch or a version-specific fork.

For a new install, use bash hermes/install.sh. If configuring Hermes manually, set the provider and the two native switches together:

memory:
  provider: luminary
  memory_enabled: false
  user_profile_enabled: false

This is capability-based integration, not a version pin. Hermes must expose the MemoryProvider entry-point contract and lifecycle; when it does not, setup should stop with a visible diagnostic rather than silently running two memory systems. No Hermes version number is embedded in Luminary's runtime path.

From the next session: auto-recall injects relevant memories every turn, the auto-retain hook evaluates completed turns for durable storage and serialized self-improvement review, and the model can call luminary_recall / luminary_ingest / luminary_list on demand.

Two optional LLM-powered features keep the store sharp:

• ingest_llm, curates automatic turn batches before storage, then reconciles the current turn against exact-scope candidates. It can save a grounded new fact or explicitly version/retract a claim; it cannot mutate from similarity alone. Without curation, automatic transcript batches are not promoted into durable memory, but remain available in the exact-session continuity ledger; explicit memory/core writes remain available.
• auto_maintain, reviews the store at session end: keeps current facts, updates changed ones, deletes stale or duplicate ones.

Provider settings are exposed in the Hermes dashboard for tuning. See docs/config-reference.md for the complete reference and hermes/README.md for the one-shot installer.

Audit-grade behavior

Exact active-memory deduplication is enforced by the database for the full user/workspace/agent/session scope, so concurrent writers converge on one row instead of racing through a read-then-insert check. Evidence-required recall fails closed when a quote is not grounded in the stored content, and MemoryClient.count() reports the same active, scope-visible view as list().

Hermes writes scoped JSONL troubleshooting events to ~/.hermes/luminary/luminary.log. Events include trace_id, operation, status/reason, counts, confidence, and latency; prompt text, memory content, Telegram tokens, and API keys are omitted. Inspect it with:

tail -f ~/.hermes/luminary/luminary.log | jq

The documentation map below is the public source of truth for the library, provider, operator, and integration guides. The benchmark notes keep the boundary around Mem0/Hindsight comparisons explicit: matched local measurements, not a universal superiority claim.

Configuration

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

The direct library client keeps rule_auto_replace=true for compatibility, but replacement still requires an explicit supersedes_id. The accuracy-facing CLI and Hermes provider disable replacement unless that relationship is supplied and preserve conflicting claims for auditability. rule_keywords is retained only for callers that already depend on the compatibility matcher; it does not classify memory by language or vocabulary.

Provider-specific settings (Hermes dashboard): max_memories, 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, core_tag, core_top_n, core_budget, importance_recall_boost, recall_min_score, extract_on_session_end (compatibility flag), recall_indicator, retain_indicator (live in ~/.hermes/luminary/config.json). The exact defaults and dashboard schema are maintained in docs/config-reference.md. 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) ──► scoped strategy candidates ──► weighted RRF ──► confidence/abstention ──► ranked results
        ▲            semantic │ keyword │ temporal │ graph   (per-strategy weights)   (cliff detection)
        │                                                               │
        └── inject into agent context ◄── token budget (4096) ◄── dedup (Jaccard 0.85)
                                                            │            │
   core memory ──► auto-loaded every session (tag 'core') ─┘ (merged, anti-duplicated)
                                                            │
   ingest(text) ──► whitelist ──► (LLM curation) ──► embed (ONNX 384-d) ─┘
   Hermes sync_turn ──► exact-session episode ledger ──► serialized retain ──► incremental review ──► capture / supersede / retract
                                                            │
   lifecycle() ──► cleanup (TTL) ──► consolidate (semantic + Jaccard, pinned exempt) ──► prune (importance, pinned exempt)
   maintenance() ──► LLM reviews store ──► keep │ update │ delete stale facts

Accuracy safeguards:

Why it stays clean:

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

Documentation

License

Apache-2.0 © 2026 Dwiky Candra