Metadata-Version: 2.5
Name: hermes-local-rag
Version: 1.5.0
Summary: Private local hybrid text and visual memory provider for Hermes Agent
Project-URL: Repository, https://github.com/condr-at/hermes-local-rag
Project-URL: Issues, https://github.com/condr-at/hermes-local-rag/issues
Author: condr-at
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: ai-edge-litert<3,>=2.1; platform_system == 'Darwin' or platform_system == 'Linux'
Requires-Dist: huggingface-hub<2,>=0.34
Requires-Dist: jsonschema<5,>=4
Requires-Dist: numpy<3,>=2.0
Requires-Dist: onnxruntime<2,>=1.20
Requires-Dist: pillow<13,>=11
Requires-Dist: tokenizers<1,>=0.22
Description-Content-Type: text/markdown

# Hermes Local RAG

> **1.5.0:** atomic memory corrections, scoped deletion, and stronger retrieval/evidence guidance.
> Read [CHANGELOG.md](CHANGELOG.md) for changes and limitations, and
> [UPGRADE.md](UPGRADE.md) for the shared-inference and curated-image migration introduced in 1.4.0.
> See the [synthetic benchmark and its limitations](evaluation/README.md).

[![Hermes Local RAG — private local memory that keeps the useful card and bins the noise](https://raw.githubusercontent.com/condr-at/hermes-local-rag/main/assets/branding/local-rag-preview-1600x900.webp)](https://github.com/condr-at/hermes-local-rag)

Private, fully local hybrid text and visual memory for [Hermes Agent](https://github.com/NousResearch/hermes-agent), implemented through the official `MemoryProvider` extension point.

## Features

- EmbeddingGemma 300M through LiteRT/XNNPACK, with configurable 128/256/512/768-dimensional Matryoshka embeddings (512d default)
- SQLite + FTS5 + vector similarity, score thresholds, freshness/importance boosts, source diversity, and bounded context injection
- Physical profile/user namespaces before retrieval
- Explicit contextual admission through `local_rag_remember`, with normalized atomic items instead of raw turns
- In-place `local_rag_update` corrections with exact-text conflict detection, stable identity, immutable scope/provenance, and transactional rollback
- Selective historical backfill with pre-LLM filtering, structured extraction, resumable preview, human review, and explicit apply
- Independent scope, durability, status, confidence, importance, provenance, deduplication, deletion, migrations, and backups
- Project- and session-aware retrieval boundaries; built-in Markdown memory is mirrored as global durable context
- Project-root-confined text-file indexing with secret and prompt-injection rejection
- Optional CLIP ViT-B/32 ONNX visual index in a separate 512d vector space
- Button-driven setup inside Hermes Dashboard; no vector database server or Hermes core patch. One private local inference service starts on the first embedding request (see UPGRADE.md).

## Install

Published package: [hermes-local-rag on PyPI](https://pypi.org/project/hermes-local-rag/)

For packaged-provider discovery, install it into the same Python environment that runs Hermes:

> Upgrading from 1.3.2 or older: stop every Hermes Desktop and gateway process first. Version 1.4.0 performs a one-time, integrity-checked migration from `memory.sqlite` / `visual.sqlite` to backup-safe `.db` files and removes the legacy files after success.

```bash
python -m pip install hermes-local-rag==1.5.0
hermes config set memory.provider local_rag
```

The package exposes `local_rag -> local_rag:register` through the official `hermes_agent.memory_providers` entry-point group. Model download and initial configuration are still required; the Dashboard plugin flow below is the recommended guided setup.

### Install without Terminal

Prerequisite: an existing Hermes Agent installation.

1. Open **Hermes Dashboard → Plugins → Install**.
2. Install `condr-at/hermes-local-rag/local_rag`.
3. Open the new **Local RAG** tab.
4. Click **Install dependencies**.
5. Open and accept the required Gemma Terms, create a read-only Hugging Face token, paste it into the password field, and click **Sign in**.
6. Choose **Text only** or **Text + visual**, then click **Download selected models**.
7. Optionally create a historical preview, edit and accept individual candidates, then explicitly apply the reviewed subset.
8. Save the memory settings and click **Activate Local RAG**.
9. Click **Run health check**.

The dashboard never displays or logs the Hugging Face token. Model downloads and setup subprocesses use fixed argument lists and a controlled environment rather than a user shell. Gemma Terms acceptance is explicit and cannot be bypassed by the installer.

The setup wizard:

1. installs pinned runtime dependencies into the Hermes venv;
2. downloads selected model artifacts to `$HERMES_HOME/models`;
3. writes configuration atomically;
4. activates `memory.provider=local_rag`;
5. checks runtime imports, models, the database, and provider availability.

It never deletes `$HERMES_HOME/local-rag`, where indexes and configuration live. Backfill is off by default and requires explicit confirmation.

### Terminal fallback

The technical installer remains available for development and recovery:

```bash
git clone https://github.com/condr-at/hermes-local-rag.git
cd hermes-local-rag
python3 install.py
```

Verify after installation or a Hermes update:

```bash
python3 install.py --check
```

Then restart the gateway, or start a new Desktop session.

## Configuration

`~/.hermes/local-rag/config.json`:

```json
{
  "embedding_dimensions": 512,
  "episodic_ttl_days": null,
  "summary_ttl_days": null
}
```

`null` means infinite retention. Changing `embedding_dimensions` requires explicit reindexing; startup fails loudly rather than mixing incompatible vectors.

## Backfill

Raw transcript backfill is disabled. Historical sessions pass through role filtering, credential and prompt-injection rejection, bounded structured extraction, and strict validation. Preview writes only a mode-`0600` review artifact; every candidate starts rejected, and only explicitly accepted items can be applied. Namespace, project, session, timestamps, and source-message provenance come from the trusted export rather than the model.

The Dashboard owns the normal preview → edit/accept → apply flow. The equivalent recovery CLI is:

```bash
hermes local_rag preview --plan /path/to/review.json
# Edit only accepted flags/text after reviewing the artifact.
hermes local_rag apply --plan /path/to/review.json
```

Preview is resumable by session and never writes the memory database. Re-applying a reviewed plan is idempotent through scope-aware exact deduplication.

## Maintenance

The provider exposes tools for status, search, deletion, candidate review, file/session ingestion, pruning, and visual search. A standalone CLI is also installed as `hermes-local-rag`.

See [`local_rag/README.md`](local_rag/README.md) for architecture, policies, tools, and recovery details.

## Privacy and licensing

No indexed data, model weights, credentials, or session exports belong in this repository. Model weights are downloaded directly from their upstream repositories and retain their own terms. EmbeddingGemma is governed by Gemma Terms. Plugin code is MIT licensed.
