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

{luminary_memory-0.2.0 → luminary_memory-0.2.2}/.github/workflows/publish.yml

@@ -3,6 +3,7 @@ name: Publish
 on:
   push:
     tags: ["v*"]
+  workflow_dispatch:
 
 permissions:
   contents: write
@@ -29,9 +30,9 @@ jobs:
           python -m build
       - name: Build Hermes skill artifact
         run: |
-          mkdir -p dist
-          zip -j dist/luminary-memory-skill.zip hermes/SKILL.md hermes/README.md
-          ls -lh dist/luminary-memory-skill.zip
+          mkdir -p skill_asset
+          zip -j skill_asset/luminary-memory-skill.zip hermes/SKILL.md hermes/README.md
+          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
@@ -40,5 +41,4 @@ jobs:
       - name: Attach skill asset to GitHub Release
         uses: softprops/action-gh-release@v2
         with:
-          files: dist/luminary-memory-skill.zip
-          generate_release_notes: true
+          files: skill_asset/luminary-memory-skill.zip

{luminary_memory-0.2.0 → luminary_memory-0.2.2}/.gitignore

@@ -102,3 +102,6 @@ docs/api/
 website/screenshot_*.png
 website/test_*.png
 website/*.png
+
+# ---- Internal plan files ----
+website/plan.md

luminary_memory-0.2.2/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+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.2] - 2026-08-18
+
+### Added
+
+- **LLM memory curation** — with `ingest_llm: true`, the provider's enricher evaluates every retained turn:
+  - `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.
+- **`OpenAICompatibleEnricher` User-Agent header** — required by some OpenAI-compatible gateways (e.g. Command Code 403s without it).
+
+### Fixed
+
+- **Shutdown SQLite thread-affinity crash** — the writer thread now closes its own client (closing from the main thread raised `sqlite3.ProgrammingError`).
+- **Hermes installer** — `hermes/install.sh` gains `--llm` (enables memory curation), handles a missing `config.yaml`, and no longer warns about the missing `[hermes]` extra (now declared).
+
+## [0.2.1] - 2026-08-18
+
+### Added
+
+- **Hermes Memory Provider** — `LuminaryMemoryProvider` plugging into Hermes via the `hermes_agent.memory_providers` entry-point group; registered as a standalone package.
+  - **Auto-recall every turn** — warm background prefetch (`queue_prefetch` → cached `prefetch`) or synchronous recall (`recall_sync`), formatted as a deterministic context block.
+  - **Auto-save every session** — buffered `sync_turn` on a single writer thread, batched by `retain_every_n_turns`, with session/parent/platform/agent lineage tags.
+  - **Session-boundary handling** — `on_session_end` flush + `on_session_switch` rebind with reset guard.
+  - **Explicit tools** — `luminary_recall`, `luminary_ingest`, `luminary_list` (OpenAI-format schemas, JSON dispatch, local error helper).
+  - **Deterministic indicator** — `RecallStatus("Luminary", count, 🌙)` surfaced via `recall_status()`.
+  - **Config layer** — `$HERMES_HOME/luminary/config.json` (0600, atomic write), `get_config_schema()`, dashboard `config_schema.py` (pure data).
+  - **Lifecycle hooks** — `is_available`, `initialize`, `shutdown`, `system_prompt_block`, `on_memory_write`, `on_delegation`, `on_pre_compress`, `backup_paths`.
+  - **Packaging** — entry point + `plugin.yaml` directory-install fallback.
+  - **Test harness** — `tests/hermes_stubs/agent/memory_provider.py` ABC stub injected via `tests/conftest.py` so tests run without a hermes-agent install.
+- **`MemoryClient.ingest(metadata=...)`** — optional metadata dict merged into stored memory metadata (backward compatible).
+
+### Performance (identical results, no approximation)
+
+- **Vectorized cosine similarity** — per-row numpy loop → single matmul; recall @ 5k memories **3,400 ms → 832 ms (4.1×)**.
+- **SQL graph aggregation** — 210k relation rows → `SUM/COUNT ... GROUP BY` in the database.
+- **`temporal_scan()`** — temporal recall fetches only `(id, created_at, access_count)`; **486 ms → 62 ms (7.8×)**.
+- **Relation cap (8/memory) + indexes** — dense graph (280k rows) → sparse (80k); store 3.5× smaller; ingest 1.6× faster.
+
+### Fixed
+
+- `config_schema.py` import fallback — module now imports standalone (no hermes runtime) so CI is green on 3.11/3.12.
+- Publish workflow — skill zip moved out of `dist/` (invalid distribution); dropped `generate_release_notes` (permission).
+
+## [0.2.0] - 2026-08-18
+
+### Added
+
+- **Query planner** — skips graph/temporal strategies when not needed (conservative v1; semantic + keyword never skipped).
+- **Batch ingest** — `ingest_batch()` with single `embed_batch` call and per-item whitelist/enrichment.
+- **Export / import** — versioned JSON backup/restore (`export`, `import_memories`, `--include-embeddings`).
+- **LLM enricher (provider-agnostic)** — `OpenAICompatibleEnricher` over any OpenAI-compatible endpoint; stdlib-only, passthrough on failure.
+- **Result snippets** — matched-fragment highlights attached to recall results.
+- **Tag-scoped recall** — `recall(query, tags=[...])`.
+- **HNSW index** for pgvector (`pg_hnsw_*` settings, idempotent `build_index()`).
+- **Benchmark suite** — `benchmarks/` (latency p50/p95 per strategy + recall@k/MRR, deterministic).
+- **CLI JSON output** for `search` and `list` (parity with `recall --json`).
+- **`--limit 0` semantics** — unlimited; negative values raise.
+- **`updated_at` auto-bump** in `update()`.
+- **API docs** generated from docstrings (pdoc → `docs/api/`).
+- **GitHub Pages workflow** (`pages.yml` → `/website`).
+- **PyPI auto-publish workflow** (`publish.yml`, trusted publishing/OIDC, tag `v*`) + Hermes skill zip release asset.
+
+### Fixed
+
+- Ruff lint: unused-variable in HNSW tests, missing `noqa` on intentional defensive excepts (CI now green).
+
+## [0.1.1] - 2026-08-17
+
+### Fixed
+
+- `MemoryClient.ingest` crashed when `ingest_llm=True` (enricher could be `None`). Now always falls back to a no-op enricher.
+- `_parse_dt` crashed on corrupt/non-ISO timestamps in lifecycle and temporal recall. Now falls back safely.
+- FTS5 keyword search accepted raw query syntax (`*`, `NEAR`, `OR`, quotes) which could alter query semantics or raise. Queries are now sanitized to plain terms.
+- `list()` loaded and sorted all memories in memory; now uses SQL-level pagination (`recent()`).
+- CLI commands could print raw tracebacks on backend errors; now caught with a clean error message. `--limit` values are clamped to `>= 1`.
+- `WhitelistFilter` crashed on an invalid regex pattern; invalid patterns are now skipped.
+- pgvector integration smoke test was a no-op; now a real add/get/search/delete round-trip.
+
+### Added
+
+- Test coverage for pgvector backend raised from 51% to 82% (get/update/delete/count/row parsing).
+
+## [0.1.0] - 2026-08-17
+
+### Added
+
+- SQLite backend with FTS5 keyword search and in-process vector search.
+- Optional pgvector backend (HNSW-ready).
+- Four-strategy recall: semantic, keyword, temporal, graph.
+- Reciprocal Rank Fusion (RRF) + Jaccard dedup + token budget.
+- Ingest pipeline with whitelist filter and optional LLM enrichment.
+- Lifecycle: TTL cleanup, near-duplicate consolidation, low-value pruning.
+- Python API (`MemoryClient`) and CLI (`luminary-memory`).
+- Environment-variable configuration (`LUMINARY_*`).

{luminary_memory-0.2.0 → luminary_memory-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: luminary-memory
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -29,6 +29,7 @@ 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
 
 <div align="center">
@@ -41,8 +42,8 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/luminary-memory?color=8ab4e8&logo=python&logoColor=white)](https://pypi.org/project/luminary-memory)
 [![License](https://img.shields.io/github/license/alertxsto/luminary-memory?color=8ab4e8)](https://github.com/alertxsto/luminary-memory/blob/main/LICENSE)
 [![CI](https://img.shields.io/github/actions/workflow/status/alertxsto/luminary-memory/ci.yml?color=8ab4e8&label=CI&logo=github)](https://github.com/alertxsto/luminary-memory/actions)
-[![Tests](https://img.shields.io/badge/tests-101%20passing-8ab4e8)](https://github.com/alertxsto/luminary-memory/actions)
-[![Coverage](https://img.shields.io/badge/coverage-89%25-8ab4e8)](https://github.com/alertxsto/luminary-memory)
+[![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&logo=github)](https://github.com/alertxsto/luminary-memory)
 
 **Self-hosted · Private · Budget-aware · Self-maintaining**
@@ -68,6 +69,40 @@ Agents are only as good as what they remember. A stateless agent re-learns the s
 
 ---
 
+## 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**.
+
+```bash
+pip install "luminary-memory[hermes]"
+```
+
+Enable it in your Hermes `config.yaml`:
+
+```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.
+
+---
+
 ## Quickstart
 
 ### Install
@@ -227,7 +262,7 @@ Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Roadmap
 
-See [ROADMAP.md](ROADMAP.md) for the full product roadmap — v0.2.0 (quality & scale), v0.3.0 (intelligence), and v1.0.0 (stable).
+See [ROADMAP.md](ROADMAP.md) for the full product roadmap — v0.2.1 (Hermes memory provider), v0.3.0 (intelligence), and v1.0.0 (stable).
 
 ---