What Your Agent Remembers
Is What It Becomes.
Durable, cross-session memory with four-strategy fused recall. Runs entirely on your infrastructure. No cloud, zero token bloat.
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 statsRetrieval Strategies
Semantic, keyword, temporal, and co-occurrence graph running in parallel.
Fused Answer
Reciprocal Rank Fusion (RRF, k=60) with Jaccard deduplication (0.85).
Cloud Dependencies
100% self-hosted on your machine with local CPU ONNX embeddings.
Embedding Dimensions
Local ONNX model BAAI/bge-small-en-v1.5 running on CPU, no GPU required.
The Challenge
Every Session, Your Agent
Starts Over.
Stateless agents re-learn the same context every session, pay the same tokens repeatedly, and make the same mistakes. Luminary closes that gap with a local memory store that persists between runs, retrieves relevant context on demand, and keeps itself tidy over time.
- 01 Semantic Vector Search
- Local 384-dimensional ONNX vector similarity (
BAAI/bge-small-en-v1.5). Captures conceptual intent and meaning on CPU without sending text to third-party APIs. - 02 Keyword Matching (FTS5)
- SQLite FTS5 full-text matching. Guarantees exact matches for symbol names, function signatures, variables, API routes, and error codes.
- 03 Temporal Decay
- Half-life decay curves weighted by access recency and frequency. Surfaces recently updated and high-utility facts first.
- 04 Co-Occurrence Graph
- Entity co-occurrence relationship graph. Traverses relational links between facts across distinct sessions, tools, and tasks.
Parallel Execution & Context Protection
Four strategies execute concurrently in parallel. Reciprocal Rank Fusion combines the candidates into a single ranked stream, followed by Jaccard deduplication and strict token budget truncation to protect your model's context window.
Built for Agents That Do Real Work.
Every turn is a deposit. Persistent memory turns scattered conversations into a compounding knowledge base your agents actually draw from.
Never Re-Debug the Same Bug
Your coding agent remembers the flaky test fix from last Tuesday, the repo conventions, and why that migration stalled — so it starts from context, not from zero.
Context That CompoundsChatbots That Actually Remember You
Preferences, project context, decisions from three weeks ago — surfaced automatically every turn, without re-prompting or context-stuffing the whole history.
Cross-Session ContinuityPipelines That Keep Their State
Background workers and cron jobs share durable execution state — task outcomes, partial results, and handoffs survive restarts, not just process memory.
Stateful WorkflowsA Second Brain That Never Leaks
Natural-language recall over your own notes and knowledge — tagged, temporally decaying, and stored in a SQLite file on your machine. Zero cloud, zero telemetry.
100% Private & LocalHermes That Remembers Everything
First-class Hermes memory provider — auto-recall every turn, auto-save every session, and an LLM curator that drops chit-chat and prunes stale facts so the store stays sharp.
Self-Curating StoreQuickstart
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
Four Phases. One Unified Lifecycle.
Ingest
Whitelist filter → optional LLM enrichment → local 384-d ONNX embedding → store
Store
SQLite + FTS5 by default · PostgreSQL + pgvector when scaling
Recall
4 parallel queries → RRF fusion (k=60) → Jaccard dedup (0.85) → token budget (4096)
Lifecycle
TTL cleanup sweep · near-duplicate consolidation · low-utility pruning
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)
Everything You Need to Know.
Does any memory data or prompt text leave my machine?
No. Luminary is 100% self-hosted and operates completely on your local infrastructure. Embeddings are generated on your CPU using an optimized local ONNX runtime (BAAI/bge-small-en-v1.5), and memories are persisted directly in your SQLite file or your own PostgreSQL instance. There is zero telemetry, no external API calls, and zero data leakage.
Do I need a dedicated GPU or external embedding API keys?
No GPU or third-party cloud API keys are required. Luminary bundles an ONNX-optimized 384-dimensional embedding model that runs fast and efficiently on modern CPUs. It runs seamlessly on developer laptops, VPS instances, Raspberry Pis, and containerized agent runners.
How does Luminary differ from a standard vector database?
A standard vector database only computes embedding cosine similarity, which frequently misses exact identifiers, function names, timestamps, and relational context. Luminary runs four parallel retrieval strategies (semantic, SQLite FTS5 keyword, temporal decay, and co-occurrence graph), blends them via Reciprocal Rank Fusion (k=60), eliminates duplicates with Jaccard similarity (0.85), and strictly enforces your agent's token budget (4096).
How does Luminary keep its memory store clean and accurate?
Two layers. Deterministic lifecycle passes (TTL expiry, near-duplicate consolidation, low-value pruning) run automatically. Optionally, an LLM curation layer (ingest_llm) evaluates every turn before saving — dropping chit-chat and storing concise factual summaries — and auto_maintain reviews the whole store at session end, deleting obsolete or contradicted facts and updating changed ones. Everything is local-first and transparently logged.
How do I migrate from SQLite to pgvector in production?
Migration requires zero application code changes. Luminary is architected around a pluggable backend interface. To switch to PostgreSQL with pgvector, simply set the environment variable LUMINARY_BACKEND=pgvector and configure your LUMINARY_PG_DSN connection string. All client methods (ingest, recall, run_lifecycle) work identically.
How does the autonomous lifecycle keep the memory store tidy?
Luminary includes an automated lifecycle engine that executes on demand or via a scheduled cron. It evaluates TTL expiration dates, combines near-duplicate entries using Jaccard text similarity (0.85), and prunes low-utility, rarely-accessed memories to ensure storage stays lean without manual intervention.
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