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

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

@@ -42,4 +42,3 @@ jobs:
         uses: softprops/action-gh-release@v2
         with:
           files: skill_asset/luminary-memory-skill.zip
-          generate_release_notes: true

{luminary_memory-0.2.1 → 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.1 → luminary_memory-0.2.2}/CHANGELOG.md

@@ -2,7 +2,23 @@
 
 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.1] - Unreleased
+## [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
 
@@ -18,6 +34,18 @@ All notable changes to this project are documented in this file. The format foll
   - **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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: luminary-memory
-Version: 0.2.1
+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

{luminary_memory-0.2.1 → luminary_memory-0.2.2}/README.md

@@ -8,8 +8,8 @@
 [![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**
@@ -35,6 +35,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

{luminary_memory-0.2.1 → luminary_memory-0.2.2}/ROADMAP.md

@@ -121,17 +121,18 @@ Post-MVP audit hardening.
 
 ---
 
-### v0.2.1 — Hermes Memory Provider
+### v0.2.1 — Hermes Memory Provider ✅ released
 
 **Goal:** Luminary becomes a first-class Hermes memory provider — auto-recall every turn, auto-save every session, matching (and beating) Hindsight's integration with a fraction of the resources.
 
-- [ ] Implement `MemoryProvider` ABC as a Hermes plugin (`plugins/memory/luminary/`)
-- [ ] `prefetch()` / `queue_prefetch()` — auto-recall into agent context each turn
-- [ ] `on_session_end()` — auto-save conversation turns
-- [ ] `get_tool_schemas()` — expose `luminary_recall` / `luminary_ingest` tools
-- [ ] `system_prompt_block()` — provider context injection
-- [ ] Register provider: `memory.provider = luminary`
-- [ ] Benchmark vs Hindsight: resource usage, recall latency, recall quality
+- [x] Implement `MemoryProvider` ABC as a standalone pip entry-point provider (`luminary_memory.hermes`)
+- [x] `prefetch()` / `queue_prefetch()` — auto-recall into agent context each turn
+- [x] `on_session_end()` — auto-save conversation turns (buffered `sync_turn`, session-boundary flush)
+- [x] `get_tool_schemas()` — expose `luminary_recall` / `luminary_ingest` / `luminary_list` tools
+- [x] `system_prompt_block()` — provider context injection
+- [x] Register provider: `memory.provider = luminary`
+- [x] Benchmark — 230 ms recall p50 @ 5k, 179 MB RSS, **0 LLM tokens** (see `benchmarks/RESULTS.md`)
+- [x] Performance: recall 4.1× faster, temporal 7.8×, graph store 3.5× smaller
 
 ---
 

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

@@ -42,14 +42,35 @@ The provider reads `$HERMES_HOME/luminary/config.json` (created on first save wi
 | `recall_sync` | `false` | Synchronous (live) recall instead of warm prefetch |
 | `auto_retain` | `true` | Enable per-turn auto-save |
 | `retain_every_n_turns` | `1` | Batch N turns into one store write |
-| `ingest_llm` | `false` | Opt-in LLM enrichment on retain |
+| `ingest_llm` | `false` | **LLM memory curation on retain** — the enricher decides whether a turn is worth saving (drops chit-chat) and stores a factual summary instead of the raw transcript |
+| `llm_base_url` | `""` | OpenAI-compatible endpoint for the enricher (e.g. `https://api.commandcode.ai/provider/v1`) |
+| `llm_model` | `""` | Enricher model (e.g. `deepseek/deepseek-v4-flash`) |
+| `llm_api_key` | `""` | Enricher API key |
+| `llm_timeout` | `60` | Enricher request timeout (seconds) |
+| `recall_indicator` | `true` | Show `🌙 Luminary — recalled N memories` |
+| `retain_indicator` | `true` | Show `🌙 Luminary — memory saved` |
+
+### LLM memory curation (v0.2.2+)
+
+With `ingest_llm: true`, every retained turn is sent to the enricher, which
+returns:
+
+- **`worth_saving`** — `false` drops the turn entirely (chit-chat, greetings,
+  trivial acknowledgements never reach the store).
+- **`summary`** — a concise factual summary in the turn's language that
+  becomes the stored content, instead of the raw `User: ... / Assistant: ...`
+  transcript.
+- **`entities` / `tags`** — attached as metadata/tags for richer recall.
+
+Without `ingest_llm` (default), turns are stored verbatim — zero LLM cost.
 
 ### Store layout
 
 ```
 $HERMES_HOME/luminary/
 ├── config.json          # provider config — 0600
-└── memory.db            # SQLite store (created by MemoryClient)
+├── memory.db            # SQLite store (created by MemoryClient)
+└── luminary.log         # transparency log (initialize/recall/retain/errors)
 ```
 
 The store is profile-scoped and picked up by `hermes backup` automatically. If you

{luminary_memory-0.2.1 → luminary_memory-0.2.2}/docs/index.md

@@ -11,6 +11,7 @@ A lightweight, self-hosted memory layer for AI agents.
 ## Key features
 
 - 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`).
 - 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.2/hermes/README.md

@@ -0,0 +1,104 @@
+# luminary-memory — Hermes integration
+
+One-shot installer for using luminary-memory as a first-class Hermes Agent
+memory provider: auto-recall every turn, auto-save every session, zero LLM
+tokens per turn — plus an optional chat-activity hook and a skill.
+
+## Quick install
+
+```bash
+git clone https://github.com/alertxsto/luminary-memory.git
+cd luminary-memory
+bash hermes/install.sh
+```
+
+That installs everything:
+
+| Component | What it does |
+|-----------|--------------|
+| **Provider** | `pip install luminary-memory[hermes]` + `memory.provider: luminary` in Hermes config |
+| **Hook** | `luminary-activity` — posts `🌙 Luminary — N memories recalled/stored` to chat |
+| **Skill** | `luminary-memory` skill for agent use |
+
+Then restart your gateway:
+
+```bash
+bash ~/.hermes/scripts/restart-bots.sh
+```
+
+## Installer options
+
+```bash
+bash hermes/install.sh --hook      # hook only
+bash hermes/install.sh --skill     # skill only
+bash hermes/install.sh --llm       # also enable LLM memory curation (ingest_llm)
+bash hermes/install.sh --no-hook --no-skill   # provider only
+```
+
+## LLM memory curation (optional but recommended)
+
+By default the provider stores every turn verbatim (zero LLM cost). With LLM
+curation enabled, an enricher evaluates each turn and:
+
+- **Drops chit-chat** — greetings, "ok", trivial acknowledgements never reach
+  the store (`worth_saving: false`).
+- **Stores factual summaries** — kept turns are saved as concise facts (e.g.
+  `"Deploy target is the staging cluster."`) instead of raw transcripts.
+
+Enable it (after `bash hermes/install.sh --llm`, edit
+`~/.hermes/luminary/config.json`):
+
+```json
+{
+  "ingest_llm": 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. 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.
+
+## Manual install (no script)
+
+```bash
+pip install "luminary-memory[hermes]>=0.2.1"
+
+# config.yaml — add under memory:
+#   provider: luminary
+
+# hook
+mkdir -p ~/.hermes/hooks/luminary-activity
+cp hermes/hooks/luminary-activity/handler.py ~/.hermes/hooks/luminary-activity/
+cp hermes/hooks/luminary-activity/HOOK.yaml ~/.hermes/hooks/luminary-activity/
+
+# skill
+mkdir -p ~/.hermes/skills/luminary-memory
+cp hermes/SKILL.md ~/.hermes/skills/luminary-memory/SKILL.md
+```
+
+## What you get
+
+- 🌙 **Auto-recall** — relevant memories retrieved in the background and
+  injected into agent context every turn.
+- 💾 **Auto-save** — completed turns persisted automatically; session
+  boundaries flush buffered turns.
+- 🛠️ **Explicit tools** — `luminary_recall` / `luminary_ingest` /
+  `luminary_list` on demand.
+- 📋 **Deterministic indicator** — `🌙 Luminary — recalled N memories` in the
+  agent UI.
+- 🔔 **Chat activity hook** — optional mirror of store activity to your chat.
+- 🧠 **Skill** — agent-side guidance for store usage.
+- 📜 **Transparency log** — `~/.hermes/luminary/luminary.log` records every
+  recall, retain, and error (initialize/recall/retain lines), so you can see
+  exactly what the provider is doing and whether anything failed.
+
+## Requirements
+
+- Python 3.11+ (Hermes venv recommended)
+- Hermes Agent with `memory.provider` support (external providers)
+
+See `docs/hermes-integration.md` in the repo root for the full configuration
+table and the legacy standalone-skill path.

luminary_memory-0.2.2/hermes/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: luminary-memory
+description: "Use luminary-memory for agent memory: auto-recall context, auto-save turns, explicit recall/ingest/list tools, config tweaks."
+version: 2.0.0
+author: Dwiky Candra
+license: Apache-2.0
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [memory, recall, self-hosted, sqlite, pgvector, provider]
+---
+
+# luminary-memory (Hermes integration)
+
+**luminary-memory** is a self-hosted memory layer that plugs into Hermes as a
+first-class memory provider. It gives agents durable cross-session memory:
+auto-recall relevant context every turn, auto-save completed turns, and
+explicit tools for on-demand memory access — all local, zero LLM tokens.
+
+**What your agent remembers is what it becomes.**
+
+## When to Use
+
+- **Recall context** — when the current task depends on things said or done in
+  earlier sessions (preferences, decisions, environment details, past fixes).
+- **Store durable facts** — after learning something that will matter later
+  (a user preference, a project convention, a config decision).
+- **Inspect the store** — list what luminary currently remembers, or check
+  whether a fact is already known before storing it again.
+- **Troubleshoot** — when memory seems stale or missing, check the store and
+  the transparency log.
+
+## How It Works (3 ways to interact)
+
+| Path | When | Trigger |
+|------|------|---------|
+| **Auto-recall** | Every turn | `memory.provider: luminary` — background recall injected into context (🌙 indicator) |
+| **Auto-retain** | After each turn | provider saves `User: ... / Assistant: ...` to the store |
+| **Explicit tools** | On demand | `luminary_recall` / `luminary_ingest` / `luminary_list` |
+
+## Agent Usage — Explicit Tools
+
+### Recall relevant memories
+
+```python
+# when the task needs earlier context
+result = client.recall("what deploy target do we use?", limit=5)
+for memory, score in zip(result.memories, result.scores):
+    print(f"[{score:.2f}] {memory.content}")
+```
+
+Prefer the injected auto-recall context when present; use the tool when you
+need a targeted query the auto-recall didn't cover.
+
+### Store a durable fact
+
+```python
+# after learning something that will matter across sessions
+client.ingest(
+    "The deploy target is the staging cluster",
+    tags=["deploy", "infra"],
+    source="hermes",
+)
+```
+
+Good candidates: user preferences, project conventions, environment details,
+decisions with reasons. Skip: one-off trivia, content already in context that
+will not matter later.
+
+### List what's stored
+
+```python
+client.list(limit=20)   # most recent first
+```
+
+Use this before re-ingesting — if a fact is already stored, update instead of
+duplicating.
+
+## Configuration — Tweaks
+
+Provider config lives in `~/.hermes/luminary/config.json` (auto-created,
+0600 perms). Defaults work out of the box; tweak only what you need.
+
+| Key | Default | What it does |
+|-----|---------|--------------|
+| `mode` | `hybrid` | `context` (auto-inject only) · `tools` (tools only) · `hybrid` (both) |
+| `auto_recall` | `true` | Auto-recall every turn (background) |
+| `recall_sync` | `false` | `true` = recall synchronously against the current message (higher relevance, adds latency) |
+| `recall_limit` | `10` | Max memories injected per recall |
+| `token_budget` | `2048` | Max tokens of injected memory |
+| `auto_retain` | `true` | Auto-save turns to the store |
+| `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 |
+| `recall_indicator` | `true` | Show `🌙 Luminary — recalled N memories` |
+| `retain_indicator` | `true` | Show `🌙 Luminary — memory saved` |
+| `backend` | `sqlite` | `sqlite` (zero config) or `pgvector` (scale) |
+
+**LLM memory curation:** with `ingest_llm: true`, the enricher evaluates each
+turn and keeps only durable facts — greetings, chit-chat, and trivial
+acknowledgements 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. Without it (default), turns are
+stored verbatim with zero LLM cost.
+
+Example — save less often, no indicators:
+
+```json
+{
+  "retain_every_n_turns": 5,
+  "recall_indicator": false,
+  "retain_indicator": false
+}
+```
+
+### Env vars
+
+| Var | Purpose |
+|-----|---------|
+| `LUMINARY_BACKEND` | `sqlite` / `pgvector` |
+| `LUMINARY_EMBEDDING_MODEL` | ONNX model (default `BAAI/bge-small-en-v1.5`) |
+| `LUMINARY_HOOK_CHAT_ID` | Chat for the activity hook (defaults to home channel) |
+| `LUMINARY_DB_PATH` | Override store location (hook) |
+
+## Transparency Log
+
+`~/.hermes/luminary/luminary.log` records every recall, retain, and error:
+
+```
+2026-08-18 04:26:37 INFO initialize session=... platform=telegram agent=default
+2026-08-18 04:26:40 INFO recall query='deploy target' limit=10 -> 5 memories (142ms)
+2026-08-18 04:26:45 INFO retain stored len=312 tags=['session:...', 'platform:telegram']
+```
+
+Check this first when memory seems wrong or missing.
+
+## Troubleshooting
+
+| Symptom | Cause / Fix |
+|---------|-------------|
+| No 🌙 indicator | `recall_indicator` off, or store empty, or provider not active (`hermes memory status`) |
+| Recall returns nothing | Store empty; or `auto_recall` / mode `tools` disables auto-injection (use the tool) |
+| Turns not saved | `auto_retain` off, or `retain_every_n_turns` batching — wait N turns |
+| Slow first recall | ONNX model loads on first use (one-time cost) |
+| Errors | Check `~/.hermes/luminary/luminary.log` |
+
+## Install
+
+### One-shot (recommended)
+
+```bash
+git clone https://github.com/alertxsto/luminary-memory.git
+cd luminary-memory && bash hermes/install.sh
+bash ~/.hermes/scripts/restart-bots.sh
+```
+
+### Manual
+
+```bash
+pip install "luminary-memory[hermes]>=0.2.1"
+# config.yaml → memory: provider: luminary
+mkdir -p ~/.hermes/hooks/luminary-activity
+cp hermes/hooks/luminary-activity/*.py hermes/hooks/luminary-activity/HOOK.yaml ~/.hermes/hooks/luminary-activity/
+mkdir -p ~/.hermes/skills/luminary-memory && cp hermes/SKILL.md ~/.hermes/skills/luminary-memory/
+```
+
+## Notes
+
+- Default backend SQLite (zero config); pgvector via `LUMINARY_BACKEND=pgvector`.
+- Recall runs four strategies (semantic, keyword, temporal, graph) fused by RRF.
+- The store is local; no data leaves the machine. Zero LLM tokens per turn.

luminary_memory-0.2.2/hermes/hooks/luminary-activity/HOOK.yaml

@@ -0,0 +1,4 @@
+name: luminary-activity
+description: Surface luminary-memory activity (recalls, stores) to the chat as a compact status line
+events:
+  - agent:end

luminary_memory-0.2.2/hermes/hooks/luminary-activity/README.md

@@ -0,0 +1,47 @@
+# Luminary Activity Hook
+
+Surfaces what luminary-memory is doing — recalls, stores, lifecycle — as a
+compact status line in your chat, so you can *see* the memory layer working.
+
+```
+🌙 Luminary — 12 memories recalled
+🌙 Luminary — 3 memories stored
+```
+
+## Install
+
+```bash
+# 1. copy the hook into your Hermes hooks directory
+mkdir -p ~/.hermes/hooks/luminary-activity
+cp hermes/hooks/luminary-activity/handler.py ~/.hermes/hooks/luminary-activity/
+cp hermes/hooks/luminary-activity/HOOK.yaml ~/.hermes/hooks/luminary-activity/
+
+# 2. env vars (in ~/.hermes/.env)
+echo "LUMINARY_HOOK_CHAT_ID=<your chat id>" >> ~/.hermes/.env
+# TELEGRAM_BOT_TOKEN + TELEGRAM_HOME_CHANNEL are usually already set
+
+# 3. restart your Hermes gateway
+bash ~/.hermes/scripts/restart-bots.sh
+```
+
+## What it shows
+
+- **agent:end** — after a turn, if the luminary store was touched in the last
+  30s (a recall updated access timestamps, or an ingest added a memory), a
+  one-line status is posted.
+
+## Configuration (env vars)
+
+| Var | Default | Description |
+|-----|---------|-------------|
+| `LUMINARY_HOOK_CHAT_ID` | `TELEGRAM_HOME_CHANNEL` | Chat to post activity to |
+| `LUMINARY_DB_PATH` | `~/.hermes/luminary/memory.db` | Luminary store to watch |
+
+## Notes
+
+- **Non-blocking** — hooks never block the agent; failures are logged to
+  `~/.hermes/hooks/luminary-activity/hook.log` and swallowed.
+- **Quiet by default** — only posts when the store was actually active.
+- The provider's built-in indicators (`recall_indicator`, `retain_indicator`,
+  `recall_status()`) already surface a `🌙` status line in the agent UI; this
+  hook is the opt-in *chat* mirror for group/DM workflows.