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

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/.github/workflows/publish.yml

@@ -35,9 +35,9 @@ jobs:
           ls -lh skill_asset/luminary-memory-skill.zip
       - name: Publish to PyPI (trusted publishing / OIDC)
         uses: pypa/gh-action-pypi-publish@release/v1
-        # Requires one-time setup on PyPI: configure this repo as a trusted
-        # publisher for project luminary-memory (https://pypi.org/manage/account/publishing/).
-        # Fallback: python -m build && twine upload dist/*
+        # Trusted Publisher only — no API token. Configured at
+        # https://pypi.org/manage/account/publishing/. Never fall back to twine:
+        # an API token upload alongside Trusted Publishing triggers a PyPI alert.
       - name: Attach skill asset to GitHub Release
         uses: softprops/action-gh-release@v2
         with:

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

@@ -2,6 +2,34 @@
 
 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.6] - 2026-08-18
+
+### Polish & hardening
+
+- **Lifecycle logging** — `cleanup`, `consolidate` (mode + merged count), `prune`, and `run_lifecycle` (result + duration) now log their activity; `estimate_importance` logs via the runner.
+- **SQLite batch errors logged** — `add_many` failures log the exception before rollback/re-raise (was silent).
+- **CLI recall JSON richer** — each memory now includes `source`, `created_at`, and `importance`.
+- **Env var warnings** — invalid `LUMINARY_*` int/float values warn instead of silently falling back.
+- **Dashboard schema 20 fields** — `consolidate_semantic` (Semantic consolidation) and `importance_auto` (Auto importance estimation) added to the Hermes provider config.
+- **`recall(limit=0)` truly unlimited** — passes `None` to backends instead of a 10k magic cap.
+- **Dedup capped window** — `dedup_jaccard(max_pairs=500)` keeps recall O(n·k) instead of O(n²) on large result sets.
+- **`import_memories` error logging** — failures log the path before re-raise.
+- **pgvector JSON columns safe** — `metadata`/`tags` parse via a `_json_load` helper (corrupt data falls back instead of crashing); HNSW index failure now logged.
+- **Prefetch thread join** — `queue_prefetch` joins any in-flight worker before spawning a new one (no thread leak / stale-cache overwrite).
+- **Degenerate embedding guard** — semantic consolidation falls back to Jaccard when embeddings are all-equal (no false merges of unrelated memories).
+- **`CONTRIBUTING.md`** — new Testing section (Postgres/pgvector setup, coverage ≥ 90%) pointing at [issue #1](https://github.com/alertxsto/luminary-memory/issues/1) (add Postgres to CI).
+
+## [0.2.5] - 2026-08-18
+
+### Added
+
+- **Semantic consolidation** — `consolidate(semantic=True)` merges memories by embedding-cosine similarity (default `LUMINARY_CONSOLIDATE_SEMANTIC=true`), catching paraphrases that token-overlap misses; falls back to Jaccard when embeddings are missing. CLI: `luminary-memory lifecycle --semantic/--no-semantic`.
+- **Auto importance estimation** — `lifecycle/importance.py:estimate_importance()` scores each memory from access (`log1p`), recency (24h decay), and graph centrality; applied on ingest and re-estimated before every prune (`LUMINARY_IMPORTANCE_AUTO=true`). Pruning and the health score's importance dimension now use live values.
+
+### Changed
+
+- `run_lifecycle()` now also re-estimates importances (returns `reestimated` count).
+
 ## [0.2.4] - 2026-08-18
 
 ### Added

luminary_memory-0.2.6/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing
+
+Thanks for helping build luminary-memory.
+
+## Setup
+
+```bash
+git clone <repo> && cd luminary-memory
+pip install -e ".[dev]"
+```
+
+## Development workflow
+
+1. Create a branch: `git checkout -b feat/your-change`.
+2. Write a failing test first (`tests/`).
+3. Implement the minimal change.
+4. Run the checks:
+
+```bash
+python -m pytest
+python -m ruff check src tests
+```
+
+5. Commit with a conventional message.
+
+## Commit conventions
+
+- `feat:` — new feature
+- `fix:` — bug fix
+- `docs:` — documentation only
+- `improve:` — refactor or enhancement without behavior change
+- `chore:` — build/tooling
+
+## Coding standards
+
+- Python 3.11+, type-hinted.
+- `ruff` clean, `pytest` green.
+- TDD where feasible — test first, then implement.
+- Keep the public API (`MemoryClient`) stable; add rather than break.
+
+## Pull requests
+
+- One logical change per PR.
+- Link the issue if applicable.
+- CI must pass before merge.
+
+## Testing
+
+Run the full suite (SQLite + unit tests) locally:
+
+```bash
+python -m pytest          # ~200+ tests, green without any external service
+python -m ruff check src tests
+```
+
+Coverage (must stay ≥ 90%):
+
+```bash
+python -m pytest --cov=luminary_memory --cov-report=term
+```
+
+### Postgres / pgvector integration tests
+
+`tests/test_backend_pgvector.py` contains real-Postgres round-trips that are
+**skipped unless `LUMINARY_PG_DSN` is set** — CI currently does not provide
+Postgres, so the pgvector path is the least-covered module (59%). If you're
+working on the pgvector backend, run them locally with:
+
+```bash
+# spin up a throwaway Postgres with the pgvector extension
+docker run -d --name luminary-pg -p 5432:5432 \
+  -e POSTGRES_USER=luminary -e POSTGRES_PASSWORD=luminary -e POSTGRES_DB=luminary \
+  pgvector/pgvector:pg16
+
+# point the tests at it
+export LUMINARY_PG_DSN=postgresql://luminary:luminary@localhost:5432/luminary
+python -m pytest tests/test_backend_pgvector.py -v
+```
+
+See [issue #1](https://github.com/alertxsto/luminary-memory/issues/1) for
+adding a Postgres service to CI so these tests run automatically.

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: luminary-memory
-Version: 0.2.4
+Version: 0.2.6
 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
@@ -40,8 +40,8 @@ Description-Content-Type: text/markdown
 [![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)
+[![Tests](https://img.shields.io/badge/tests-190%2B%20passing-8ab4e8)](https://github.com/alertxsto/luminary-memory/actions)
+[![Coverage](https://img.shields.io/badge/coverage-90%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**
@@ -132,6 +132,8 @@ Every setting has a `LUMINARY_*` env var or a `Settings` object.
 | `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` |
+| `consolidate_semantic` | `LUMINARY_CONSOLIDATE_SEMANTIC` | `true` |
+| `importance_auto` | `LUMINARY_IMPORTANCE_AUTO` | `true` |
 
 See [hermes/SKILL.md](hermes/SKILL.md) for the full provider config table (18 settings).
 
@@ -166,7 +168,7 @@ Built-in lifecycle keeps the store lean. LLM maintenance (optional) keeps it acc
 | [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 |
+| [Roadmap](ROADMAP.md) | v0.2.6 → v1.0.0 |
 | [Benchmarks](benchmarks/RESULTS.md) | 230 ms recall @ 5k, 0 LLM tokens |
 
 ---

luminary_memory-0.2.6/PLAN-v0.2.5.md

@@ -0,0 +1,120 @@
+# PLAN v0.2.5 — Semantic Consolidation + Auto Importance
+
+**Version:** 0.2.5 · **Milestone:** Smarter self-maintenance (roadmap v0.3.0 items #4 + #5)
+**Goal:** Replace token-overlap consolidation with semantic (embedding) merging, and auto-estimate memory importance so pruning and health scores reflect real value.
+
+---
+
+## Background (verified from code)
+
+- `lifecycle/consolidate.py` uses **Jaccard token overlap only** (`recall/dedup.py:jaccard_similarity`). Two memories with the same meaning but different wording ("deploy target is staging" vs "deploy target is production cluster") are **not** merged → semantic duplicates accumulate.
+- `lifecycle/prune.py` uses **static `m.importance`** (default `0.2`), never estimated from behavior → pruning is blunt.
+- `MemoryClient` has `self.engine.embed()` (fastembed) available — can compute embeddings for consolidation without new deps.
+- `types.py:Memory` has `importance`, `access_count`, `created_at`, `last_accessed_at`, `metadata`.
+
+---
+
+## Phase 1 — Semantic Consolidation (T1–T4)
+
+### T1 — cosine helper in `recall/dedup.py`
+
+Add `cosine_similarity(a: list[float], b: list[float]) -> float` (pure math, no deps). Reuse in consolidation; keep `jaccard_similarity` for dedup.
+
+- Test: identical vectors → 1.0; orthogonal → 0.0; empty → 0.0; negative → clamped.
+
+### T2 — semantic merge in `lifecycle/consolidate.py`
+
+Extend `consolidate(backend, threshold=0.9, semantic=True)`:
+
+- `semantic=True` (default): cluster by `cosine_similarity(embedding_a, embedding_b) >= semantic_threshold` (default 0.85), **falling back to Jaccard** when embeddings are missing (legacy rows, pgvector without vectors).
+- `semantic=False`: current Jaccard behavior (back-compat).
+- Keep existing merge logic (longest content as master, sum access, union tags).
+
+- Tests: two memories same meaning different words → merged (embedding similarity high); two unrelated → kept; missing embeddings → falls back to Jaccard; `semantic=False` → Jaccard only.
+
+### T3 — CLI flag
+
+`luminary-memory lifecycle --semantic/--no-semantic` (default semantic on). Wire through `run_lifecycle()` → `consolidate(semantic=...)`.
+
+- Test: CLI flag parse + passes through.
+
+### T4 — runner integration
+
+`lifecycle/runner.py:run_lifecycle()` passes `semantic` from settings (`LUMINARY_CONSOLIDATE_SEMANTIC`, default `true`). New env var documented.
+
+- Test: runner respects env var.
+
+---
+
+## Phase 2 — Auto Importance Estimation (T5–T8)
+
+### T5 — estimator module `lifecycle/importance.py`
+
+```python
+def estimate_importance(
+    memory, now=None,
+    half_life_hours: float = 24.0,       # recency decay
+    access_weight: float = 0.4,
+    recency_weight: float = 0.3,
+    centrality_weight: float = 0.3,
+) -> float:
+```
+
+`importance = access_norm * access_weight + recency_norm * recency_weight + centrality_norm * centrality_weight`
+
+- `access_norm` — `log1p(access_count) / log1p(max_access_in_store)`.
+- `recency_norm` — `exp(-age_hours / half_life_hours)` (same decay shape as temporal recall).
+- `centrality_norm` — graph degree / max degree (relations count; 0 when no graph table).
+- Clamp 0.0–1.0.
+
+- Tests: new memory → low importance; accessed many times → high; recent → high; old+never-accessed → low; clamp bounds.
+
+### T6 — call estimator on ingest + lifecycle
+
+- `api.py:ingest()` — after insert, if importance not explicitly set, `estimate_importance(memory)` and persist (needs backend update — cheap, one row).
+- `run_lifecycle()` — re-estimate all importances before prune so pruning reflects current value.
+- Guard: only when `LUMINARY_IMPORTANCE_AUTO` (default `true`).
+
+- Tests: ingest sets importance > 0; lifecycle re-estimates (old memory importance drops); disabled flag keeps static.
+
+### T7 — prune uses estimated importance (already does, but now fed live values)
+
+No structural change — prune already reads `m.importance`. Add test proving a low-importance memory gets pruned after re-estimation.
+
+### T8 — health score uses importance dimension (already reads it)
+
+`health_score()` `importance` dimension already uses `m.importance >= prune_min`. With auto-estimation the dimension becomes meaningful. Add test: fresh store → importance high → score contribution healthy.
+
+---
+
+## Phase 3 — Docs + Release (T9–T10)
+
+### T9 — Documentation sweep (REQUIRED before release — user rule)
+
+- `docs/lifecycle.md` — semantic consolidation section + importance auto-estimation + new env vars.
+- `docs/recall.md` — note cosine in consolidation (dedup still Jaccard).
+- `docs/architecture.md` — update lifecycle pipeline (importance estimation step).
+- `docs/cli.md` — `lifecycle --semantic/--no-semantic`.
+- `README.md` — badges if tests/coverage change; roadmap line v0.2.5.
+- `CHANGELOG.md` — 0.2.5 entry.
+- `ROADMAP.md` — header v0.2.5, tick items #4 (importance) + #5 (consolidation v2).
+- Website badge → v0.2.5.
+- Grep for stale versions across all docs before release.
+
+### T10 — Release v0.2.5
+
+- Bump `pyproject.toml` + `__init__.py` → 0.2.5.
+- `pytest -q` green, `ruff check` clean, coverage ≥ 90% (DoD).
+- Tag `v0.2.5` → push → GitHub release (Trusted Publisher auto-publishes PyPI).
+- Verify PyPI version + website redeploy.
+
+---
+
+## Definition of Done
+
+- [ ] Consolidation merges semantic near-duplicates (verified with same-meaning-different-words test)
+- [ ] Importance auto-estimated on ingest + lifecycle (verified with behavior tests)
+- [ ] Coverage ≥ 90%, ruff clean, all tests green
+- [ ] CLI `--semantic/--no-semantic` works
+- [ ] Docs sweep complete & versions consistent (user rule)
+- [ ] v0.2.5 released via Trusted Publisher (no twine)

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/README.md

@@ -6,8 +6,8 @@
 [![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)
+[![Tests](https://img.shields.io/badge/tests-190%2B%20passing-8ab4e8)](https://github.com/alertxsto/luminary-memory/actions)
+[![Coverage](https://img.shields.io/badge/coverage-90%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**
@@ -98,6 +98,8 @@ Every setting has a `LUMINARY_*` env var or a `Settings` object.
 | `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` |
+| `consolidate_semantic` | `LUMINARY_CONSOLIDATE_SEMANTIC` | `true` |
+| `importance_auto` | `LUMINARY_IMPORTANCE_AUTO` | `true` |
 
 See [hermes/SKILL.md](hermes/SKILL.md) for the full provider config table (18 settings).
 
@@ -132,7 +134,7 @@ Built-in lifecycle keeps the store lean. LLM maintenance (optional) keeps it acc
 | [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 |
+| [Roadmap](ROADMAP.md) | v0.2.6 → v1.0.0 |
 | [Benchmarks](benchmarks/RESULTS.md) | 230 ms recall @ 5k, 0 LLM tokens |
 
 ---

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/ROADMAP.md

@@ -2,7 +2,7 @@
 
 > **Tagline:** A lightweight, self-hosted memory layer for AI agents.
 
-**Current release:** v0.1.1 (bugfix) · **Tests:** 97 passing · **Coverage:** 91% · **License:** Apache-2.0
+**Current release:** v0.2.6 (polish & hardening) · **Tests:** 200+ passing · **Coverage:** 90% · **License:** Apache-2.0
 
 ---
 
@@ -33,7 +33,7 @@ Every AI agent deserves durable memory that lives on its own infrastructure. Lum
 | Packaging (PyPI, GitHub release, tags) | ✅ v0.1.1 |
 | Website (landing page) | ✅ v0.1.1 |
 | Hermes integration skill | ✅ v0.1.1 |
-| Test coverage | ✅ 91% total (pgvector 82%) |
+| Test coverage | ✅ 90% total |
 
 ---
 
@@ -102,10 +102,10 @@ Post-MVP audit hardening.
 **Goal:** Smarter memory — structure, insight, and visualization.
 
 - [ ] Knowledge graph visualization (entity relations browser)
-- [ ] Memory health score (duplicate rate, staleness, importance distribution)
+- [x] Memory health score (duplicate rate, staleness, importance distribution) — v0.2.4
 - [ ] Multi-user scoping (`user_id` per memory, per-user recall)
-- [ ] Memory importance auto-estimation (recency + access + semantic centrality)
-- [ ] Consolidation v2: semantic-aware merging (not just Jaccard token overlap)
+- [x] Memory importance auto-estimation (recency + access + semantic centrality) — v0.2.5
+- [x] Consolidation v2: semantic-aware merging (not just Jaccard token overlap) — v0.2.5
 
 ---
 

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/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`, `run_maintenance` (LLM curation), `stats`, `close`.
+- `MemoryClient` — `ingest`, `ingest_batch`, `recall` (tags + snippets + planner), `search`, `get`/`update`/`delete`, `list`, `export`/`import_memories`, `run_lifecycle`, `run_maintenance` (LLM curation), `health_score` (store health report), `stats`, `close`.
 - `Settings` — `LUMINARY_*` env vars, `as_dict()`.
 - `Memory`, `RecallResult` — `types.py`.
 - Subpackages `backends/`, `embeddings/`, `ingest/`, `recall/`, `lifecycle/`, `export`.

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/docs/architecture.md

@@ -42,5 +42,9 @@ See [backends.md](backends.md).
 Three maintenance passes, orchestrated by `run_lifecycle()`:
 
 - **cleanup** — remove TTL-expired memories.
-- **consolidate** — merge near-duplicates (Jaccard ≥ threshold).
-- **prune** — drop low-importance or least-recently-used memories.
+- **consolidate** — merge near-duplicates (Jaccard or embedding-cosine, semantic by default).
+- **prune** — drop low-importance or least-recently-used memories (importance auto-estimated from access, recency, centrality).
+
+Optional **LLM maintenance** (`run_maintenance()`, or provider `auto_maintain`)
+reviews the whole store and keeps/updates/deletes facts semantically.
+`health_score()` reports store quality (0-100) across five dimensions.

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/docs/cli.md

@@ -46,9 +46,30 @@ Most recent first.
 
 ```bash
 luminary-memory lifecycle
+luminary-memory lifecycle --no-semantic   # Jaccard-only consolidation
 ```
 
-Runs cleanup + consolidate + prune, prints counts.
+Runs cleanup + consolidate + prune (plus importance re-estimation), prints
+counts. `--semantic/--no-semantic` toggles embedding-cosine consolidation
+(default: semantic on).
+
+### export
+
+```bash
+luminary-memory export --path backup.json
+luminary-memory export --path backup.json --no-embeddings
+```
+
+Exports all memories to a JSON file (backup/migration). `--no-embeddings`
+skips embedding vectors to keep the file small.
+
+### import
+
+```bash
+luminary-memory import --path backup.json
+```
+
+Imports memories from a JSON export (recomputes embeddings when absent).
 
 ### stats
 
@@ -58,6 +79,17 @@ luminary-memory stats
 
 Prints store statistics as JSON.
 
+### health
+
+```bash
+luminary-memory health
+luminary-memory health --json
+```
+
+Prints a 0-100 store health score with a per-dimension breakdown (duplicate
+rate, staleness, importance, graph density, size) and actionable
+recommendations. `--json` emits the raw report.
+
 ## Exit codes
 
 - `0` — success.

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

@@ -96,6 +96,8 @@ cp hermes/SKILL.md ~/.hermes/skills/luminary-memory/SKILL.md
 1. **Ingest on tool call** — after learning a durable fact (preference, environment detail), call `client.ingest(...)`.
 2. **Recall into the system prompt** — before answering, call `client.recall(query)` and inject the top memories as context.
 3. **Lifecycle via cron** — schedule `luminary-memory lifecycle` to keep the store clean.
+4. **Monitor health** — `luminary-memory health` (or `client.health_score()`) reports store quality; run it in a cron to catch drift.
+5. **LLM curation (optional)** — with `ingest_llm` + `auto_maintain`, turns are curated and stale facts pruned automatically.
 
 ## Example
 

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/docs/index.md

@@ -12,6 +12,8 @@ A lightweight, self-hosted memory layer for AI agents.
 
 - Four retrieval strategies fused into one ranked recall (semantic, keyword, temporal, graph).
 - **First-class Hermes Agent memory provider** — auto-recall every turn, auto-save every session, zero LLM tokens per turn (`memory.provider: luminary`).
+- **LLM memory curation** — optional `ingest_llm` drops chit-chat and stores factual summaries; `auto_maintain` prunes stale/duplicate facts at session end.
+- **Health score** — `health_score()` / `luminary-memory health` reports store quality (0-100) with recommendations.
 - SQLite out of the box, optional pgvector for scale.
 - Local CPU embeddings via ONNX — no GPU, no cloud.
 - Configurable token budget so memory never overflows the agent's context.

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/docs/lifecycle.md

@@ -11,7 +11,22 @@ 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.
+Clusters memories by Jaccard similarity (`LUMINARY_CONSOLIDATE_JACCARD_THRESHOLD`, default 0.9) **or embedding-cosine similarity** (`LUMINARY_CONSOLIDATE_SEMANTIC`, default `true`) and merges each cluster into a single memory — keeping the longest content, summing access counts, and unioning tags. Semantic mode (default) merges paraphrases that token overlap would miss; it falls back to Jaccard when embeddings are missing. Disable with `LUMINARY_CONSOLIDATE_SEMANTIC=false` or `luminary-memory lifecycle --no-semantic`.
+
+### importance — auto-estimation
+
+On ingest and before each prune, each memory's importance is estimated from behavior:
+
+```
+importance = access_norm × 0.4 + recency_norm × 0.3 + centrality_norm × 0.3
+```
+
+- `access_norm` — `log1p(access_count)` normalized to the store's max.
+- `recency_norm` — `exp(-age_hours / 24h)` (fresh memories score higher).
+- `centrality_norm` — graph relation degree normalized (0 when no graph).
+
+Disable with `LUMINARY_IMPORTANCE_AUTO=false`. Pruning and the health score's
+importance dimension both use these live values.
 
 ### prune — drop low-value memories
 

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/docs/quickstart.md

@@ -31,6 +31,9 @@ for memory, score in zip(result.memories, result.scores):
 # 3. maintain the store
 client.run_lifecycle()
 
+# 4. check store health (0-100 score + recommendations)
+print(client.health_score())
+
 client.close()
 ```
 
@@ -40,8 +43,44 @@ client.close()
 luminary-memory add "The deploy target is the staging cluster" --tags deploy
 luminary-memory recall "where do we deploy?" --json
 luminary-memory stats
+luminary-memory health
+```
+
+## Backup & restore
+
+```bash
+luminary-memory export --path backup.json
+luminary-memory import --path backup.json
+```
+
+`export` writes all memories to a JSON file (migration/backup); `import`
+restores them (recomputing embeddings when absent).
+
+## Optional: LLM memory curation
+
+By default every ingest is stored verbatim (zero LLM cost). To have an LLM
+evaluate each turn — dropping chit-chat and storing concise factual summaries
+instead of raw transcripts — enable `ingest_llm` and `auto_maintain`:
+
+```bash
+pip install "luminary-memory[hermes]"
 ```
 
+```json
+// ~/.hermes/luminary/config.json (Hermes provider)
+{
+  "ingest_llm": true,
+  "auto_maintain": true,
+  "llm_base_url": "https://api.commandcode.ai/provider/v1",
+  "llm_model": "deepseek/deepseek-v4-flash",
+  "llm_api_key": "your-key"
+}
+```
+
+Any OpenAI-compatible endpoint works. `auto_maintain` reviews the store at
+session end — keeping current facts, updating changed ones, deleting stale or
+duplicate memories.
+
 ## Configuration
 
 All settings accept a `LUMINARY_*` env var:

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

@@ -86,11 +86,15 @@ client.run_lifecycle()
 
 # LLM review: keep current facts, update changed ones, delete stale/duplicates
 client.run_maintenance()   # requires an LLM enricher (ingest_llm)
+
+# health check: 0-100 score with per-dimension breakdown + recommendations
+report = client.health_score()
 ```
 
 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`.
+needed. Results are logged to `~/.hermes/luminary/luminary.log`. CLI:
+`luminary-memory health` (human bar) or `--json`.
 
 ## Configuration — Tweaks
 

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "luminary-memory"
-version = "0.2.4"
+version = "0.2.6"
 description = "A lightweight, self-hosted memory layer for AI agents"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/src/luminary_memory/__init__.py

@@ -1,4 +1,4 @@
 from luminary_memory.api import MemoryClient
 
-__version__ = "0.2.4"
+__version__ = "0.2.6"
 __all__ = ["MemoryClient", "__version__"]

{luminary_memory-0.2.4 → luminary_memory-0.2.6}/src/luminary_memory/api.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 from datetime import UTC
 from typing import TYPE_CHECKING
 
@@ -11,18 +12,16 @@ from luminary_memory.ingest.llm import LLMEnricher, NoopEnricher
 from luminary_memory.ingest.whitelist import WhitelistFilter
 from luminary_memory.types import Memory, RecallResult
 
+logger = logging.getLogger(__name__)
 
-def _try_index_graph(backend, memory: Memory) -> None:
-    import logging
 
+def _try_index_graph(backend, memory: Memory) -> None:
     from luminary_memory.recall.graph import index_memory_entities
 
     try:
         index_memory_entities(backend, memory)
     except Exception:  # noqa: BLE001 -- graph indexing is best-effort; never abort ingest
-        logging.getLogger(__name__).warning(
-            "graph indexing failed for memory %s (non-fatal)", memory.id
-        )
+        logger.warning("graph indexing failed for memory %s (non-fatal)", memory.id)
 
 if TYPE_CHECKING:
     from luminary_memory.backends.base import MemoryBackend
@@ -77,6 +76,10 @@ class MemoryClient:
             ttl_seconds=self.settings.ttl_default_seconds,
             embedding=self.engine.embed(content),
         )
+        if self.settings.importance_auto:
+            from luminary_memory.lifecycle.importance import estimate_importance
+
+            m.importance = estimate_importance(m)
         mid = self.backend.add(m)
         m.id = mid
         _try_index_graph(self.backend, m)
@@ -250,10 +253,10 @@ class MemoryClient:
     def count(self) -> int:
         return self.backend.count()
 
-    def run_lifecycle(self) -> dict[str, int]:
+    def run_lifecycle(self, semantic: bool | None = None) -> dict[str, int]:
         from luminary_memory.lifecycle.runner import run_lifecycle
 
-        return run_lifecycle(self.backend, self.settings)
+        return run_lifecycle(self.backend, self.settings, semantic=semantic)
 
     def health_score(self) -> dict:
         """Store health report: overall 0-100 plus per-dimension breakdown.
@@ -419,7 +422,11 @@ class MemoryClient:
         """Import memories from *path* (recomputes embeddings when absent)."""
         from luminary_memory.export import import_memories
 
-        return import_memories(self.backend, path, engine=self.engine)
+        try:
+            return import_memories(self.backend, path, engine=self.engine)
+        except Exception:
+            logger.exception("import_memories failed for %s", path)
+            raise
 
     def close(self) -> None:
         self.backend.close()
@@ -435,7 +442,7 @@ class MemoryClient:
         if n_limit < 0:
             raise ValueError("limit must be >= 0 (0 means unlimited)")
         if n_limit == 0:
-            n_limit = 10_000  # unlimited — large enough for any realistic store
+            n_limit = None  # unlimited — backends treat None as "no limit"
         from luminary_memory.recall.dedup import dedup_jaccard
         from luminary_memory.recall.fusion import reciprocal_rank_fusion
         from luminary_memory.recall.graph import graph_recall
@@ -450,6 +457,7 @@ class MemoryClient:
         planner_threshold = float(getattr(self.settings, "query_planner_keyword_threshold", 0.9))
 
         eff = n_limit
+        temporal_limit = (eff * 2) if eff is not None else None
         enabled = None
 
         strategies: list[list[tuple]] = []
@@ -457,7 +465,7 @@ class MemoryClient:
         strat_fns = [
             ("semantic", lambda: semantic_recall(self.backend, self.engine, query, limit=eff)),
             ("keyword", lambda: keyword_recall(self.backend, query, limit=eff)),
-            ("temporal", lambda: temporal_recall(self.backend, limit=eff * 2)),
+            ("temporal", lambda: temporal_recall(self.backend, limit=temporal_limit)),
             ("graph", lambda: graph_recall(self.backend, query, limit=eff)),
         ]