luminary-memory 0.2.2__tar.gz → 0.2.4__tar.gz

{luminary_memory-0.2.2 → luminary_memory-0.2.4}/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to this project are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/), and the project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.2.4] - 2026-08-18
+
+### Added
+
+- **`MemoryClient.health_score()`** — store health report (0-100) across five dimensions: duplicate rate, staleness, importance, graph density, and size — plus actionable recommendations. Empty store scores 100.
+- **`luminary-memory health` CLI** — human-readable bar + `--json` output.
+- **Test coverage raised 82% → 90%** (roadmap DoD): config_schema standalone shim, enricher `_call_llm`/`review_memories` paths, maintenance CRUD edges, provider lifecycle/maintenance/shutdown, CLI whitelist/limit errors, recall strategy failure fallbacks.
+
+### Fixed
+
+- **`run_maintenance` bad-response detection** — `data.get("actions") or []` masked non-list responses as "no actions"; now correctly reports `{"error": "bad LLM response"}`.
+
+## [0.2.3] - 2026-08-18
+
+### Added
+
+- **Hermes dashboard config schema** — exposes 18 luminary settings (mode, backend, recall limit, token budget, auto-recall/retain, **LLM memory curation**, **auto-maintain**, LLM endpoint, indicators) in the Hermes dashboard Provider panel. `auto_maintain` added; `ingest_llm` label corrected to "LLM memory curation".
+
+### Changed
+
+- **Balanced LLM curation** — the enricher now rejects work/task logs and meta-talk about the memory system itself, while still keeping durable facts (not over-strict). Verified: work logs → `worth_saving: false`; facts → stored.
+
 ## [0.2.2] - 2026-08-18
 
 ### Added
@@ -10,7 +32,8 @@ All notable changes to this project are documented in this file. The format foll
   - `worth_saving` — chit-chat, greetings, and trivial turns are **dropped** instead of polluting the store.
   - `summary` — kept turns are stored as concise factual summaries (e.g. `"Deploy target is the staging cluster."`) instead of raw `User: ... / Assistant: ...` transcripts.
   - `entities` / `tags` — attached for richer recall.
-- **Transparency log** — provider writes `$HERMES_HOME/luminary/luminary.log` recording initialize/recall/retain/errors.
+- **LLM store maintenance** — `MemoryClient.run_maintenance()` + provider `auto_maintain` (session-end): the LLM reviews the store and **deletes obsolete/contradicted/duplicate facts**, **updates changed ones**, and **keeps** current ones (verified: stale deploy target auto-removed).
+- **Transparency log** — provider writes `$HERMES_HOME/luminary/luminary.log` recording initialize/recall/retain/maintenance/errors.
 - **`OpenAICompatibleEnricher` User-Agent header** — required by some OpenAI-compatible gateways (e.g. Command Code 403s without it).
 
 ### Fixed

luminary_memory-0.2.4/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: luminary-memory
+Version: 0.2.4
+Summary: A lightweight, self-hosted memory layer for AI agents
+Project-URL: Homepage, https://github.com/alertxsto/luminary-memory
+Project-URL: Repository, https://github.com/alertxsto/luminary-memory
+Project-URL: Documentation, https://github.com/alertxsto/luminary-memory#readme
+Author: Dwiky Candra
+License: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: fastembed>=0.4.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: pgvector>=0.2.5
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pdoc>=14; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: hermes
+Description-Content-Type: text/markdown
+
+# 🌙 luminary-memory
+
+**A lightweight, self-hosted memory layer for AI agents.**
+
+[![PyPI version](https://img.shields.io/pypi/v/luminary-memory?color=8ab4e8&label=PyPI)](https://pypi.org/project/luminary-memory)
+[![Python](https://img.shields.io/pypi/pyversions/luminary-memory?color=8ab4e8)](https://pypi.org/project/luminary-memory)
+[![License](https://img.shields.io/github/license/alertxsto/luminary-memory?color=8ab4e8)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/alertxsto/luminary-memory/ci.yml?color=8ab4e8&label=CI)](https://github.com/alertxsto/luminary-memory/actions)
+[![Tests](https://img.shields.io/badge/tests-168%20passing-8ab4e8)](https://github.com/alertxsto/luminary-memory/actions)
+[![Coverage](https://img.shields.io/badge/coverage-85%25-8ab4e8)](https://github.com/alertxsto/luminary-memory)
+[![Stars](https://img.shields.io/github/stars/alertxsto/luminary-memory?color=8ab4e8)](https://github.com/alertxsto/luminary-memory)
+
+**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 **Reciprocal Rank Fusion (k=60)** → **Jaccard deduplication (0.85)** → **token budget (4096)**.
+
+---
+
+## Quickstart
+
+```bash
+pip install luminary-memory
+```
+
+```python
+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
+```
+
+```bash
+# 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.
+
+18 settings are exposed in the [Hermes dashboard](https://alertxsto.github.io/luminary-memory) for zero-hassle tuning. See
+[hermes/README.md](hermes/README.md) for the one-shot installer and full configuration.
+
+---
+
+## Configuration
+
+Every setting has a `LUMINARY_*` env var or a `Settings` object.
+
+| Setting | Env var | Default |
+|---------|---------|---------|
+| `backend` | `LUMINARY_BACKEND` | `sqlite` |
+| `db_path` | `LUMINARY_DB_PATH` | `luminary_memory.db` |
+| `pg_dsn` | `LUMINARY_PG_DSN` | — (pgvector only) |
+| `embedding_model` | `LUMINARY_EMBEDDING_MODEL` | `BAAI/bge-small-en-v1.5` |
+| `embedding_dim` | `LUMINARY_EMBEDDING_DIM` | `384` |
+| `ingest_llm` | `LUMINARY_INGEST_LLM` | `false` |
+| `rrf_k` | `LUMINARY_RRF_K` | `60` |
+| `dedup_jaccard_threshold` | `LUMINARY_DEDUP_JACCARD_THRESHOLD` | `0.85` |
+| `token_budget` | `LUMINARY_TOKEN_BUDGET` | `4096` |
+| `ttl_default_seconds` | `LUMINARY_TTL_DEFAULT_SECONDS` | `null` |
+| `prune_min_importance` | `LUMINARY_PRUNE_MIN_IMPORTANCE` | `0.2` |
+| `consolidate_jaccard_threshold` | `LUMINARY_CONSOLIDATE_JACCARD_THRESHOLD` | `0.9` |
+
+See [hermes/SKILL.md](hermes/SKILL.md) for the full provider config table (18 settings).
+
+---
+
+## Architecture
+
+```
+ingest(text) ──► whitelist filter ──► (LLM curation) ──► embed ──► SQLite / pgvector
+
+recall(query) ──► semantic │ keyword │ temporal │ graph
+               ──► RRF fusion ──► Jaccard dedup ──► token budget ──► ranked results
+
+lifecycle() ──► cleanup (TTL) ──► consolidate (near-dupes) ──► prune (low-value)
+
+maintenance() ──► LLM reviews store ──► keep │ update │ delete stale facts
+```
+
+Built-in lifecycle keeps the store lean. LLM maintenance (optional) keeps it accurate. `health_score()` gives you a 0-100 checkup with actionable recommendations.
+
+---
+
+## Documentation
+
+| Section | |
+|---------|-----|
+| [Quickstart](docs/quickstart.md) | Install and first use |
+| [Architecture](docs/architecture.md) | Pipelines and data flow |
+| [Python API](docs/api.md) | `MemoryClient` reference |
+| [CLI](docs/cli.md) | All subcommands |
+| [Recall](docs/recall.md) | Four strategies + fusion |
+| [Lifecycle](docs/lifecycle.md) | Cleanup, consolidation, pruning, LLM maintenance |
+| [Backends](docs/backends.md) | SQLite vs pgvector |
+| [Hermes integration](docs/hermes-integration.md) | Provider, config, installer |
+| [Roadmap](ROADMAP.md) | v0.2.3 → v1.0.0 |
+| [Benchmarks](benchmarks/RESULTS.md) | 230 ms recall @ 5k, 0 LLM tokens |
+
+---
+
+## License
+
+[Apache-2.0](LICENSE) © 2026 Dwiky Candra

luminary_memory-0.2.4/PLAN-v0.2.4.md

@@ -0,0 +1,128 @@
+# PLAN v0.2.4 — Coverage 90% + Health Score
+
+**Version:** 0.2.4 · **Milestone:** Quality hardening + health introspection
+**Goal:** Raise test coverage from 82% → ≥90% (roadmap DoD) and ship
+`MemoryClient.health_score()` for store quality monitoring.
+
+---
+
+## Phase 1 — Coverage: test the untested (T1–T5)
+
+Targets identified by `pytest --cov --cov-report=term-missing`:
+
+| Module | Current | Target | Missing lines to cover |
+|--------|---------|--------|------------------------|
+| `hermes/config_schema.py` | 11% | ≥90% | Standalone fallback shim (no hermes runtime) |
+| `ingest/llm.py` | 68% | ≥90% | `review_memories`, `_call_llm` error/empty paths, enrich failures |
+| `api.py` | 75% | ≥90% | `run_maintenance` actions, `delete`/`update` edges, error handling |
+| `hermes/provider.py` | 81% | ≥90% | maintenance trigger, shutdown, prefetch guards, error paths |
+
+### T1 — config_schema standalone coverage
+- Test: import `config_schema.py` **without** hermes-agent runtime (simulate CI)
+- Assert `CONFIG_SCHEMA` shim exposes `name`, `label`, `storage`, 18 fields
+- Assert `auto_maintain` and `ingest_llm` fields present
+
+### T2 — llm.py enricher paths
+- Test `OpenAICompatibleEnricher.review_memories` with mocked `_call_llm`
+  - returns valid actions JSON → parsed
+  - returns `{}` → `{"skipped": ...}` handled by caller
+  - raises (network) → returns `{}` (best-effort, no crash)
+- Test `_call_llm` with mocked `urlopen`:
+  - 200 with choices → content returned
+  - 200 empty choices → `""`
+  - HTTPError → propagates to caller fallback
+- Test `enrich()` fallback when `base_url` empty → `EnrichedContent(content=text)`
+
+### T3 — api.py maintenance + CRUD edges
+- Test `run_maintenance`:
+  - no enricher → `{"skipped": ...}`
+  - empty store → `{"reviewed": 0, ...}`
+  - enricher returns delete/update/keep actions → applied correctly
+  - enricher returns malformed actions (not a list) → `{"error": "bad LLM response"}`
+  - enricher returns action for unknown id → skipped
+- Test `update()` with changed content → `updated_at` bumped, embedding recomputed
+- Test `delete()` on non-existent id → graceful (no raise)
+
+### T4 — provider.py lifecycle paths
+- Test `on_session_end` with `auto_maintain=true` + `ingest_llm=true` → `run_maintenance` called, logged
+- Test `on_session_end` with maintenance raising → exception logged, not propagated
+- Test `shutdown` writer-thread close (regression: no SQLite thread-affinity crash)
+- Test prefetch guards: `auto_recall=false`, `mode=tools`, shutdown flag → no prefetch
+
+### T5 — coverage gate
+- Add `--cov-fail-under=90` to CI workflow + `Makefile`/`pyproject` pytest config
+- Verify `pytest -q --cov=luminary_memory` ≥ 90% locally
+
+---
+
+## Phase 2 — Health score (T6–T8)
+
+### T6 — `health_score()` API in `api.py`
+
+```python
+def health_score(self) -> dict:
+    """Store health report: overall 0-100 + per-dimension breakdown."""
+```
+
+Dimensions (computed from existing store data — no new schema):
+
+| Dimension | Weight | Signal |
+|-----------|--------|--------|
+| `duplicate_rate` | 25% | % memories with a near-dupe (Jaccard > 0.85) — lower better |
+| `staleness` | 25% | % memories not accessed in 30d (decayed) — lower better |
+| `importance` | 20% | % memories above `prune_min_importance` — higher better |
+| `density` | 15% | memories with graph relations / total — higher better |
+| `size` | 15% | store size vs `token_budget` scale (0 = empty, 100 = healthy volume) |
+
+Score = weighted sum. Returns:
+
+```python
+{
+  "score": 87.5,
+  "dimensions": {
+    "duplicate_rate": {"value": 0.02, "weight": 0.25, "health": 98.0},
+    "staleness": {...}, "importance": {...}, "density": {...}, "size": {...}
+  },
+  "recommendations": ["2 stale memories older than 30d — run lifecycle prune"]
+}
+```
+
+`recommendations` — generated from low-scoring dimensions (≤70):
+- duplicates → "run lifecycle consolidate"
+- stale → "run lifecycle prune or LLM maintenance"
+- low importance → "raise prune_min_importance or review store"
+
+### T7 — CLI `health` subcommand
+
+```bash
+luminary-memory health --json
+luminary-memory health
+# 📊 Memory Health: 87.5/100
+#   • Duplicates: 2.0% ✅
+#   • Stale (>30d): 4.0% ✅
+#   • Importance: 92% ✅
+#   • Graph density: 33% ⚠️
+#   • Size: 60% ✅
+#   → 2 stale memories — run `luminary-memory lifecycle`
+```
+
+### T8 — health score tests + docs
+
+- Test: empty store → score 0? or 100? (decide: empty store = 100 "nothing wrong" — document)
+- Test: all duplicates → low duplicate_rate dimension
+- Test: all stale → low staleness dimension
+- Test: healthy mixed store → score ≥ 80
+- Test CLI `health` output shape (`--json` parseable)
+- Docs: `docs/lifecycle.md` + README (health section), CHANGELOG entry
+
+---
+
+## Definition of Done (v0.2.4)
+
+- [ ] `pytest -q` green (≥90% coverage, CI gate)
+- [ ] `ruff check src tests` clean
+- [ ] CLI smoke: `luminary-memory health` + `--json`
+- [ ] Health score verified against real store (`~/.hermes/luminary/memory.db`)
+- [ ] CHANGELOG 0.2.4 entry
+- [ ] Version bumped to 0.2.4
+- [ ] Tag + GitHub release + PyPI upload (auto-publish)

luminary_memory-0.2.4/README.md

@@ -0,0 +1,142 @@
+# 🌙 luminary-memory
+
+**A lightweight, self-hosted memory layer for AI agents.**
+
+[![PyPI version](https://img.shields.io/pypi/v/luminary-memory?color=8ab4e8&label=PyPI)](https://pypi.org/project/luminary-memory)
+[![Python](https://img.shields.io/pypi/pyversions/luminary-memory?color=8ab4e8)](https://pypi.org/project/luminary-memory)
+[![License](https://img.shields.io/github/license/alertxsto/luminary-memory?color=8ab4e8)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/alertxsto/luminary-memory/ci.yml?color=8ab4e8&label=CI)](https://github.com/alertxsto/luminary-memory/actions)
+[![Tests](https://img.shields.io/badge/tests-168%20passing-8ab4e8)](https://github.com/alertxsto/luminary-memory/actions)
+[![Coverage](https://img.shields.io/badge/coverage-85%25-8ab4e8)](https://github.com/alertxsto/luminary-memory)
+[![Stars](https://img.shields.io/github/stars/alertxsto/luminary-memory?color=8ab4e8)](https://github.com/alertxsto/luminary-memory)
+
+**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 **Reciprocal Rank Fusion (k=60)** → **Jaccard deduplication (0.85)** → **token budget (4096)**.
+
+---
+
+## Quickstart
+
+```bash
+pip install luminary-memory
+```
+
+```python
+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
+```
+
+```bash
+# 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.
+
+18 settings are exposed in the [Hermes dashboard](https://alertxsto.github.io/luminary-memory) for zero-hassle tuning. See
+[hermes/README.md](hermes/README.md) for the one-shot installer and full configuration.
+
+---
+
+## Configuration
+
+Every setting has a `LUMINARY_*` env var or a `Settings` object.
+
+| Setting | Env var | Default |
+|---------|---------|---------|
+| `backend` | `LUMINARY_BACKEND` | `sqlite` |
+| `db_path` | `LUMINARY_DB_PATH` | `luminary_memory.db` |
+| `pg_dsn` | `LUMINARY_PG_DSN` | — (pgvector only) |
+| `embedding_model` | `LUMINARY_EMBEDDING_MODEL` | `BAAI/bge-small-en-v1.5` |
+| `embedding_dim` | `LUMINARY_EMBEDDING_DIM` | `384` |
+| `ingest_llm` | `LUMINARY_INGEST_LLM` | `false` |
+| `rrf_k` | `LUMINARY_RRF_K` | `60` |
+| `dedup_jaccard_threshold` | `LUMINARY_DEDUP_JACCARD_THRESHOLD` | `0.85` |
+| `token_budget` | `LUMINARY_TOKEN_BUDGET` | `4096` |
+| `ttl_default_seconds` | `LUMINARY_TTL_DEFAULT_SECONDS` | `null` |
+| `prune_min_importance` | `LUMINARY_PRUNE_MIN_IMPORTANCE` | `0.2` |
+| `consolidate_jaccard_threshold` | `LUMINARY_CONSOLIDATE_JACCARD_THRESHOLD` | `0.9` |
+
+See [hermes/SKILL.md](hermes/SKILL.md) for the full provider config table (18 settings).
+
+---
+
+## Architecture
+
+```
+ingest(text) ──► whitelist filter ──► (LLM curation) ──► embed ──► SQLite / pgvector
+
+recall(query) ──► semantic │ keyword │ temporal │ graph
+               ──► RRF fusion ──► Jaccard dedup ──► token budget ──► ranked results
+
+lifecycle() ──► cleanup (TTL) ──► consolidate (near-dupes) ──► prune (low-value)
+
+maintenance() ──► LLM reviews store ──► keep │ update │ delete stale facts
+```
+
+Built-in lifecycle keeps the store lean. LLM maintenance (optional) keeps it accurate. `health_score()` gives you a 0-100 checkup with actionable recommendations.
+
+---
+
+## Documentation
+
+| Section | |
+|---------|-----|
+| [Quickstart](docs/quickstart.md) | Install and first use |
+| [Architecture](docs/architecture.md) | Pipelines and data flow |
+| [Python API](docs/api.md) | `MemoryClient` reference |
+| [CLI](docs/cli.md) | All subcommands |
+| [Recall](docs/recall.md) | Four strategies + fusion |
+| [Lifecycle](docs/lifecycle.md) | Cleanup, consolidation, pruning, LLM maintenance |
+| [Backends](docs/backends.md) | SQLite vs pgvector |
+| [Hermes integration](docs/hermes-integration.md) | Provider, config, installer |
+| [Roadmap](ROADMAP.md) | v0.2.3 → v1.0.0 |
+| [Benchmarks](benchmarks/RESULTS.md) | 230 ms recall @ 5k, 0 LLM tokens |
+
+---
+
+## License
+
+[Apache-2.0](LICENSE) © 2026 Dwiky Candra

{luminary_memory-0.2.2 → luminary_memory-0.2.4}/docs/api.md

@@ -14,7 +14,7 @@ pdoc --output-dir docs/api --docformat markdown src/luminary_memory
 
 ## Quick surface
 
-- `MemoryClient` — `ingest`, `ingest_batch`, `recall` (tags + snippets + planner), `search`, `get`/`update`/`delete`, `list`, `export`/`import_memories`, `run_lifecycle`, `stats`, `close`.
+- `MemoryClient` — `ingest`, `ingest_batch`, `recall` (tags + snippets + planner), `search`, `get`/`update`/`delete`, `list`, `export`/`import_memories`, `run_lifecycle`, `run_maintenance` (LLM curation), `stats`, `close`.
 - `Settings` — `LUMINARY_*` env vars, `as_dict()`.
 - `Memory`, `RecallResult` — `types.py`.
 - Subpackages `backends/`, `embeddings/`, `ingest/`, `recall/`, `lifecycle/`, `export`.

{luminary_memory-0.2.2 → luminary_memory-0.2.4}/docs/hermes-integration.md

@@ -49,6 +49,7 @@ The provider reads `$HERMES_HOME/luminary/config.json` (created on first save wi
 | `llm_timeout` | `60` | Enricher request timeout (seconds) |
 | `recall_indicator` | `true` | Show `🌙 Luminary — recalled N memories` |
 | `retain_indicator` | `true` | Show `🌙 Luminary — memory saved` |
+| `auto_maintain` | `false` | **LLM store review at session end** — keeps/updates/deletes stale, contradicted, or duplicate facts (requires `ingest_llm`) |
 
 ### LLM memory curation (v0.2.2+)
 

luminary_memory-0.2.4/docs/lifecycle.md

@@ -0,0 +1,108 @@
+# Lifecycle
+
+Two maintenance layers keep the store lean: deterministic passes
+(`run_lifecycle()`) and LLM-driven curation (`run_maintenance()`).
+
+## `run_lifecycle()` — deterministic passes
+
+### cleanup — TTL expiry
+
+Removes memories whose `ttl_seconds` has elapsed.
+
+### consolidate — merge near-duplicates
+
+Clusters memories by Jaccard similarity (`LUMINARY_CONSOLIDATE_JACCARD_THRESHOLD`, default 0.9) and merges each cluster into a single memory — keeping the longest content, summing access counts, and unioning tags.
+
+### prune — drop low-value memories
+
+Removes memories below a minimum importance (`LUMINARY_PRUNE_MIN_IMPORTANCE`, default 0.2).
+
+## `run_maintenance()` — LLM-driven curation (v0.2.2+)
+
+Sends the store to the configured LLM enricher, which reviews every memory and
+decides **keep** / **update** / **delete**:
+
+- **delete** — obsolete, contradicted, or duplicate facts (e.g. the old
+  deploy target after it changed).
+- **update** — facts that changed, with replacement content.
+- **keep** — still-current facts.
+
+Requires an LLM enricher (set `ingest_llm: true` + `llm_*` config); no-ops
+otherwise. One LLM call per review run (all memories in a single call).
+
+```python
+client = MemoryClient(db_path="memory.db", enricher=enricher)
+print(client.run_maintenance())
+# {'reviewed': 4, 'deleted': 2, 'updated': 0}
+```
+
+### Automatic maintenance in the Hermes provider
+
+With `auto_maintain: true` in `~/.hermes/luminary/config.json` (plus
+`ingest_llm: true`), the provider runs `run_maintenance()` automatically at
+every session end:
+
+```json
+{
+  "ingest_llm": true,
+  "llm_base_url": "https://api.commandcode.ai/provider/v1",
+  "llm_model": "deepseek/deepseek-v4-flash",
+  "llm_api_key": "your-key",
+  "auto_maintain": true
+}
+```
+
+Results are recorded in the transparency log
+(`~/.hermes/luminary/luminary.log`): `maintenance {'reviewed': N, 'deleted': N, 'updated': N}`.
+
+## `health_score()` — store health report (v0.2.4+)
+
+Returns a 0-100 health score with a per-dimension breakdown, computed from
+existing store data (no new schema):
+
+| Dimension | Weight | What it measures |
+|-----------|--------|------------------|
+| `duplicate_rate` | 25% | Share of memories with a near-duplicate (Jaccard > threshold) |
+| `staleness` | 25% | Share of memories not accessed in 30 days |
+| `importance` | 20% | Share of memories above `prune_min_importance` |
+| `density` | 15% | Share of memories with graph relations |
+| `size` | 15% | Store volume (scales toward 100 at ~1k memories) |
+
+```python
+report = client.health_score()
+print(report["score"])            # 87.5
+print(report["recommendations"])  # actionable hints
+```
+
+CLI:
+
+```bash
+luminary-memory health           # human-readable bar
+luminary-memory health --json    # raw JSON
+```
+
+```
+📊 Memory Health: 87.5/100 █████████░
+  ✅ duplicate_rate: 98%
+  ⚠️ density: 33%
+  → 2 stale memories (>30d) — run lifecycle prune or LLM maintenance
+```
+
+Empty store scores 100 (nothing wrong); low-scoring dimensions produce
+recommendations.
+
+## Scheduling
+
+Run via cron for a self-maintaining store:
+
+```cron
+0 4 * * *  /usr/local/bin/luminary-memory lifecycle
+```
+
+Or programmatically:
+
+```python
+client = MemoryClient(db_path="memory.db")
+print(client.run_lifecycle())
+client.close()
+```

{luminary_memory-0.2.2 → luminary_memory-0.2.4}/hermes/README.md

@@ -61,6 +61,25 @@ Any OpenAI-compatible endpoint works. Costs one small LLM call per retained
 turn (temperature 0, strict JSON). If the enricher fails, the provider falls
 back to storing the turn verbatim — it never blocks.
 
+### Store maintenance (auto_maintain)
+
+With `auto_maintain: true` (plus `ingest_llm: true`), the provider also
+reviews the store at every session end — the LLM keeps current facts, updates
+changed ones, and **deletes stale, contradicted, or duplicate memories**:
+
+```json
+{
+  "ingest_llm": true,
+  "llm_base_url": "https://api.commandcode.ai/provider/v1",
+  "llm_model": "deepseek/deepseek-v4-flash",
+  "llm_api_key": "your-key",
+  "auto_maintain": true
+}
+```
+
+Results land in the transparency log:
+`maintenance {'reviewed': N, 'deleted': N, 'updated': N}`.
+
 ## Manual install (no script)
 
 ```bash

{luminary_memory-0.2.2 → luminary_memory-0.2.4}/hermes/SKILL.md

@@ -76,6 +76,22 @@ client.list(limit=20)   # most recent first
 Use this before re-ingesting — if a fact is already stored, update instead of
 duplicating.
 
+### Store maintenance
+
+The store keeps itself clean two ways:
+
+```python
+# deterministic passes (TTL, consolidate, prune)
+client.run_lifecycle()
+
+# LLM review: keep current facts, update changed ones, delete stale/duplicates
+client.run_maintenance()   # requires an LLM enricher (ingest_llm)
+```
+
+In the Hermes provider, `auto_maintain: true` (plus `ingest_llm: true`) runs
+`run_maintenance()` automatically at every session end — no manual trigger
+needed. Results are logged to `~/.hermes/luminary/luminary.log`.
+
 ## Configuration — Tweaks
 
 Provider config lives in `~/.hermes/luminary/config.json` (auto-created,
@@ -92,6 +108,7 @@ Provider config lives in `~/.hermes/luminary/config.json` (auto-created,
 | `retain_every_n_turns` | `1` | Save every N turns (higher = fewer, batched saves) |
 | `ingest_llm` | `false` | **LLM memory curation** — drops chit-chat, stores factual summary instead of raw transcript |
 | `llm_base_url` / `llm_model` / `llm_api_key` | `""` | OpenAI-compatible enricher endpoint/model/key |
+| `auto_maintain` | `false` | **LLM store review at session end** — keeps/updates/deletes stale or duplicate facts (needs `ingest_llm`) |
 | `recall_indicator` | `true` | Show `🌙 Luminary — recalled N memories` |
 | `retain_indicator` | `true` | Show `🌙 Luminary — memory saved` |
 | `backend` | `sqlite` | `sqlite` (zero config) or `pgvector` (scale) |