Why luminary-memory

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.

What your agent remembers is what it becomes.

Value proposition

• Self-hosted and private — all data stays on your machine. No cloud dependency, no API keys to leak, no per-token memory cost.
• Four retrieval strategies in one recall — semantic (embeddings), keyword (FTS5), temporal (recency × access), and graph (entity co-occurrence) run in parallel and fuse into a single ranked result via Reciprocal Rank Fusion.
• Zero hard dependencies — the default backend is SQLite + FTS5 (standard library). Embeddings run locally on CPU via ONNX. Ingesting and recalling memories in minutes.
• Budget-aware by design — results are deduplicated (Jaccard) and truncated to a configurable token budget, so memory injection never blows up your agent's context window.
• Self-maintaining — a built-in lifecycle handles TTL expiry, near-duplicate consolidation, and low-value pruning, so the store stays lean without manual cleanup.
• Scales when you do — a pluggable backend lets you move from SQLite to pgvector without changing your code.

Hermes Agent — first-class memory provider

luminary-memory ships a native Hermes Agent memory provider (luminary-memory[hermes]): drop-in, auto-recall every turn, auto-save every session — with zero LLM tokens per turn.

pip install "luminary-memory[hermes]"

Enable it in your Hermes config.yaml:

memory:
  provider: luminary

That's it. From the next session:

• 🌙 Auto-recall — relevant memories are retrieved in the background and injected into agent context every turn
• 💾 Auto-save — completed turns are persisted automatically; session boundaries flush buffered turns
• 🛠️ Explicit tools — the model can call luminary_recall / luminary_ingest / luminary_list on demand
• 📋 Deterministic indicator — a 🌙 Luminary — recalled N memories status line surfaces memory use

Registers via the standard hermes_agent.memory_providers entry point — no Hermes source changes, no cloud, no LLM API keys. See docs/hermes-integration.md for the full configuration table.

LLM memory curation (optional): set ingest_llm: true in ~/.hermes/luminary/config.json (plus llm_base_url / llm_model / llm_api_key) to have the provider evaluate every turn before saving — chit-chat and trivial turns are dropped, and kept turns are stored as concise factual summaries (e.g. "Deploy target is the staging cluster.") instead of raw User: ... / Assistant: ... transcripts. One small LLM call per retained turn; any OpenAI-compatible endpoint works.

LLM store maintenance (optional): set auto_maintain: true in the same config file to have the provider review the store at every session end — the LLM keeps current facts, updates changed ones, and deletes stale, contradicted, or duplicate memories, so the store never accumulates outdated or redundant facts.

Quickstart

Install

pip install luminary-memory

Python API

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

# maintain the store (TTL cleanup + consolidation + pruning)
client.run_lifecycle()

client.close()

CLI

luminary-memory add "The deploy target is the staging cluster" --tags deploy
luminary-memory recall "where do we deploy?" --json
luminary-memory search "postgresql"
luminary-memory list
luminary-memory lifecycle
luminary-memory stats

How recall works

Four retrieval strategies run in parallel, then fuse into one ranked result:

Fusion pipeline: 4 strategies → RRF fusion (k=60) → Jaccard dedup (0.85) → token budget (4096)

Backends

Switch backends with one setting:

from luminary_memory import MemoryClient
from luminary_memory.config import Settings

client = MemoryClient(settings=Settings(
    backend="pgvector",
    pg_dsn="postgresql://user:pass@localhost/memdb",
))

Configuration

Every setting can be set via a LUMINARY_* environment variable or passed as a Settings object.

Use cases

• AI coding agents — retain architecture decisions, API choices, and error fixes across sessions.
• Chatbots & assistants — remember user preferences, history, and conversation context.
• Automation pipelines — persist execution state, task outcomes, and learned parameters.
• Personal knowledge & local RAG — a private second brain with zero cloud involvement.

Architecture

ingest(text) ──► whitelist filter ──► (LLM enrich, optional) ──► embed ──► backend
                                                                          │
recall(query) ──► 4 strategies (semantic·keyword·temporal·graph)
               ──► RRF fusion ──► Jaccard dedup ──► token budget ──► ranked results
                                                                          │
lifecycle() ──► cleanup (TTL) ──► consolidate (near-dupes) ──► prune (low-value)

Hermes integration

A ready-to-use skill lives in hermes/SKILL.md: install it, then the agent can ingest durable facts on tool calls, recall context into its system prompt, and schedule lifecycle maintenance via cron. See docs/hermes-integration.md.

Development

git clone https://github.com/alertxsto/luminary-memory.git
cd luminary-memory
pip install -e ".[dev]"

python -m pytest          # run tests
python -m ruff check src tests   # lint

Contributions welcome — see CONTRIBUTING.md.

Documentation

• Quickstart — install and first use
• Architecture — pipelines and data flow
• Python API — MemoryClient reference
• CLI — all subcommands and flags
• Recall — how the four strategies + fusion work
• Lifecycle — cleanup, consolidation, pruning
• Backends — SQLite vs pgvector
• Hermes integration — use with Hermes Agent

Roadmap

See ROADMAP.md for the full product roadmap — v0.2.2 (LLM memory curation & maintenance), v0.3.0 (intelligence), and v1.0.0 (stable).

License

Apache-2.0 © 2026 Dwiky Candra