What Your Agent Remembers
Is What It Becomes.
Durable, cross-session memory with four-way fused recall. Runs locally on your CPU with zero cloud dependencies, zero telemetry, and zero LLM tokens burned per search.
pip install luminary-memory
from luminary_memory import MemoryClient
client = MemoryClient(db_path="memory.db")
# 1. Ingest facts, preferences, or environment states
client.ingest(
"The deploy target is the staging cluster",
tags=["deploy", "infra"]
)
# 2. Recalled across semantic, keyword, temporal, & graph
result = client.recall("where do we deploy?")
for m, s in zip(result.memories, result.scores):
print(f"{s:.3f} {m.content}")
# → 0.942 The deploy target is the staging cluster
# 3. Autonomous maintenance sweep
client.run_lifecycle() # TTL cleanup + Jaccard dedup + prune# 1. Ingest a memory with metadata tags
luminary-memory add "The deploy target is the staging cluster" --tags deploy infra
# 2. Recall with 4-strategy parallel fusion
luminary-memory recall "where do we deploy?" --limit 5 --json
# 3. Fast keyword search across FTS5 index
luminary-memory search "staging"
# 4. Autonomous maintenance (TTL, Jaccard dedup, pruning)
luminary-memory lifecycle
# 5. Check memory store health and count
luminary-memory statsLLM Tokens / Recall
Retrieval runs locally via CPU ONNX embeddings. You never burn API tokens to search memory.
End-to-End Recall (p50)
Measured on 1,000-memory stores. 4 parallel strategies fused in under a quarter-second.
Fused Strategies
Vector cosine, SQLite FTS5 keyword, temporal decay, and entity graph blended via weighted RRF (k=60).
Peak Memory (RSS)
In-process SQLite + ONNX runtime. Zero background daemons or vector database clusters.
How It Works
Stateless Agents Forget Everything.
Here Is How Luminary Fixes That.
When agents restart from an empty prompt every turn, they repeat past mistakes, re-query known data, and inflate token bills. Luminary provides an embedded, self-pruning memory store that sits directly inside your Python process. Every memory is embedded locally, indexed across four dimensions, and retrieved in parallel without cloud roundtrips.
- 01 Semantic Vector Search
- Local 384-dimensional ONNX vector similarity (
BAAI/bge-small-en-v1.5). Captures conceptual meaning directly on your CPU without third-party API calls. - 02 Keyword Matching (FTS5)
- SQLite FTS5 full-text matching with BM25 ranking. Guarantees exact matches for symbol names, function signatures, paths, variables, and error codes.
- 03 Temporal Half-Life Decay
- Exponential decay curves weighted by access frequency and age. Surfaces fresh and frequently accessed facts over stale historical entries.
- 04 Co-Occurrence Entity Graph
- Relational entity graph tracking co-occurring symbols and concepts. Discovers contextual links even when the query shares no direct keywords.
Parallel Fusion & Context Budget Protection
All four retrieval strategies run concurrently. Weighted Reciprocal Rank Fusion merges candidates into a unified rank (semantic and keyword carry the most weight), short queries are expanded with related entities from the graph, Jaccard deduplication eliminates paraphrased clutter, and hard token budget limits protect your model's context window.
Tested at Scale. Zero Marketing Numbers.
Benchmarked with synthetic and real workloads on standard x86_64 CPUs using benchmarks/hermes_provider_bench.py. Transparent and reproducible.
Want to fill in the pgvector numbers? Issue #6 is a real benchmark task.
Built for Agents That Do Real Work.
Coding agents that keep context
Repository conventions, flaky test workarounds, architecture decisions. Your coding agent persists them across CLI sessions, so it starts every morning with what it learned last week instead of a blank prompt.
Hermes agents with zero-token memory
Luminary is a first-class Hermes memory provider (memory.provider=luminary). Every turn recalls the relevant facts, every session exit saves what mattered. Retrieval costs zero LLM tokens because embeddings run locally on CPU.
Background workers that survive restarts
Cron jobs and pipeline workers share outcomes, partial states, and rate-limit budgets across process restarts. Memory lives in a SQLite file, not in a process that dies at 3 a.m.
Quickstart
Running in Four Steps.
-
1
Install Package
One lightweight package with bundled ONNX CPU embeddings. No GPU or cloud credentials required.
pip install luminary-memory -
2
Store Memories
Ingest durable facts, environment configurations, and preferences with metadata tags.
client.ingest("The deploy target is staging", tags=["deploy"]) -
3
Fused Recall
Query naturally. The four-strategy fused retrieval pipeline returns scored, deduplicated memories.
luminary-memory recall "where do we deploy?" --json -
4
Autonomous Lifecycle
Autonomous lifecycle sweep handles TTL expiration, near-duplicate consolidation, and low-value pruning.
luminary-memory lifecycle
One Loop, Running Every Turn.
Memory is not a pipeline you run once. It is a loop your agent lives in: recall, act, ingest, repeat.
Recall before you answer
At the start of every turn, four strategies run in parallel: vector cosine, FTS5 keyword, temporal decay, entity graph. RRF (k=60) fuses them into one ranked list, Jaccard dedup (0.85) drops paraphrases, and a token budget (4096) caps what enters the context window.
Act with context
The agent answers with the recalled facts already in context. Zero LLM tokens were spent on retrieval: embeddings run locally on CPU via ONNX.
Ingest what mattered
After the turn, durable facts are extracted (optional LLM curation filters chit-chat), embedded locally, and stored with metadata tags and co-occurrence relations.
Lifecycle keeps it sharp
Periodically, TTL cleanup expires stale facts, semantic consolidation merges near-duplicates, and importance-based pruning drops low-value noise. The store stays lean without you touching it.
SQLite by Default. pgvector When You Scale.
Luminary abstracts storage behind a pluggable interface. Start instantly with zero setup on your machine, then migrate seamlessly when your infrastructure demands it.
SQLite + FTS5
Default- Dependencies Python standard library, zero extra installs
- Vector Engine In-process cosine similarity on CPU
- Keyword Matching Built-in SQLite FTS5 index (BM25 ranking)
- Ideal Scale Single-user agents, local CLI, edge (under 100k memories)
- Setup Zero-config instant local
.dbfile
PostgreSQL + pgvector
- Dependencies PostgreSQL 14+ with pgvector extension
- Vector Engine pgvector cosine similarity (HNSW-ready)
- Keyword Matching ILIKE pattern matching on content and tags
- Ideal Scale Multi-agent fleets, backend services, enterprise
- Setup Database connection string (
LUMINARY_PG_DSN)
FAQ
Frequently Asked Questions
Does any memory data or prompt text leave my machine?
No. Luminary is completely self-hosted. Embeddings are generated on your local CPU using an ONNX runtime (BAAI/bge-small-en-v1.5), and memories are persisted directly to your local SQLite file or your own PostgreSQL instance. There is zero telemetry and zero external API calls.
Do I need a GPU or third-party embedding API keys?
No. The default embedding engine runs locally on standard CPU hardware via ONNX with zero external API keys. It runs efficiently on laptops, Linux servers, and containerized CI environments.
Why four retrieval strategies instead of just a vector database?
Vector search alone struggles with exact identifiers (function names, file paths, error codes) and ignores temporal recency. Luminary combines vector similarity with SQLite FTS5 exact keyword matching, temporal decay curves, and entity graph co-occurrences. Results are merged via Reciprocal Rank Fusion (k=60) and pruned with Jaccard deduplication (0.85).
How does Luminary prevent memory store bloat over time?
Two layers keep the store lean: deterministic lifecycle passes (run_lifecycle()) that expire TTLs, consolidate near-duplicates via semantic cosine clustering, and prune low-importance entries (<0.2); and an optional LLM maintenance review (run_maintenance()) that cleans obsolete facts at session end.
How do I check memory store quality?
Run luminary-memory health in your CLI. It evaluates duplicate rate (25%), staleness (25%), importance distribution (20%), graph relation density (15%), and store size (15%), outputting an overall 0-100 health score with actionable maintenance recommendations.
How do I switch from SQLite to pgvector for large-scale fleets?
Set LUMINARY_BACKEND=pgvector and configure your LUMINARY_PG_DSN connection string. All client methods (ingest, recall, run_lifecycle) share the identical Python API, letting you scale without modifying application code.
How does the Hermes agent integration work?
Configure memory.provider=luminary in your Hermes agent settings. The provider automatically performs local fused recall on every conversational turn (consuming zero LLM tokens) and triggers automatic store maintenance when the session closes.
Give Your Agents a Memory
That Lasts.
Self-hosted, private, and ready in seconds. Eliminate stateless repetition from your AI agent stack today.
pip install luminary-memory