hermes-local-rag 1.3.1__tar.gz

hermes_local_rag-1.3.1/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: uv sync --all-groups
+      - run: uv run pytest
+      - run: uv build

hermes_local_rag-1.3.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,28 @@
+name: publish-pypi
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/hermes-local-rag/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0d8abe699bfb85fec6de9f7adb5ae17292296ff # v6
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.11"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

hermes_local_rag-1.3.1/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+dist/
+!local_rag/dashboard/dist/
+!local_rag/dashboard/dist/**
+build/
+*.egg-info/
+.DS_Store
+.coverage
+assets/*.zip
+
+# Never commit local memory, models, exports, or credentials
+local-rag/
+models/
+*.sqlite*
+*.jsonl
+.env*

hermes_local_rag-1.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 condr-at
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_local_rag-1.3.1/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: hermes-local-rag
+Version: 1.3.1
+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
+
+[![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
+- 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 model server, vector database server, or Hermes core patch
+
+## 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.

hermes_local_rag-1.3.1/README.md

@@ -0,0 +1,100 @@
+# Hermes Local RAG
+
+[![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
+- 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 model server, vector database server, or Hermes core patch
+
+## 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.

hermes_local_rag-1.3.1/assets/branding/local-rag-mark.svg

@@ -0,0 +1,36 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-labelledby="title desc">
+  <title id="title">Local RAG memory drawer</title>
+  <desc id="desc">A dark archive drawer holding an ivory memory card, with an amber node mark and a rejected crumpled note.</desc>
+  <defs>
+    <linearGradient id="body" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#343330"/>
+      <stop offset="1" stop-color="#151615"/>
+    </linearGradient>
+    <linearGradient id="paper" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#fff4da"/>
+      <stop offset="1" stop-color="#e9d7b5"/>
+    </linearGradient>
+    <filter id="shadow" x="-30%" y="-30%" width="160%" height="180%">
+      <feDropShadow dx="0" dy="18" stdDeviation="18" flood-color="#000" flood-opacity=".28"/>
+    </filter>
+  </defs>
+  <g filter="url(#shadow)">
+    <rect x="89" y="78" width="334" height="340" rx="44" fill="url(#body)"/>
+    <rect x="119" y="116" width="274" height="224" rx="26" fill="#0e0f0e"/>
+    <rect x="139" y="137" width="234" height="170" rx="24" fill="url(#paper)"/>
+    <rect x="112" y="249" width="288" height="180" rx="27" fill="url(#body)" stroke="#4a4843" stroke-width="5"/>
+    <path d="M112 268h95c10 0 12 28 28 28h42c16 0 18-28 28-28h95v-19H112z" fill="#232321"/>
+    <rect x="188" y="334" width="136" height="44" rx="10" fill="#101110" stroke="#535049" stroke-width="5"/>
+    <circle cx="256" cy="403" r="17" fill="#252522" stroke="#55524c" stroke-width="4"/>
+  </g>
+  <g fill="none" stroke="#d98b14" stroke-width="10" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M286 191l-34 49m34-49l38 49m-72 0h72"/>
+    <circle cx="286" cy="181" r="14" fill="#fff4da"/>
+    <circle cx="245" cy="249" r="14" fill="#fff4da"/>
+    <circle cx="331" cy="249" r="14" fill="#fff4da"/>
+  </g>
+  <g transform="translate(405 295) rotate(8)">
+    <path d="M0 20l19-18 17 12 17-8 12 22-12 17 7 19-23 10-15-12-22 5-8-23z" fill="#e8d8ba" stroke="#c7b28d" stroke-width="4"/>
+    <path d="M5 24l17 15 14-21 15 29" fill="none" stroke="#baa27b" stroke-width="3"/>
+  </g>
+</svg>

hermes_local_rag-1.3.1/conftest.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import shutil
+import sys
+import types
+
+try:
+    import agent.memory_provider  # noqa: F401
+except ImportError:
+    agent = types.ModuleType("agent")
+    memory_provider = types.ModuleType("agent.memory_provider")
+
+    class MemoryProvider:
+        pass
+
+    memory_provider.MemoryProvider = MemoryProvider
+    agent.memory_provider = memory_provider
+    sys.modules["agent"] = agent
+    sys.modules["agent.memory_provider"] = memory_provider
+
+
+def pytest_sessionfinish(session, exitstatus):
+    for name in (".pytest_cache",):
+        shutil.rmtree(name, ignore_errors=True)

hermes_local_rag-1.3.1/install.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+TEXT_REPO = "litert-community/embeddinggemma-300m"
+TEXT_FILES = ["embeddinggemma-300M_seq512_mixed-precision.tflite"]
+TOKENIZER_REPO = "google/embeddinggemma-300m"
+TOKENIZER_FILES = ["tokenizer.json", "tokenizer_config.json", "special_tokens_map.json"]
+VISUAL_REPO = "Xenova/clip-vit-base-patch32"
+VISUAL_FILES = [
+    "onnx/vision_model_quantized.onnx",
+    "onnx/text_model_quantized.onnx",
+    "tokenizer.json",
+    "tokenizer_config.json",
+    "config.json",
+    "preprocessor_config.json",
+]
+
+
+def run(command: list[str], **kwargs) -> None:
+    print("+", " ".join(command))
+    subprocess.run(command, check=True, **kwargs)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Install Hermes Local RAG without touching the Hermes checkout")
+    parser.add_argument("--home", default=os.environ.get("HERMES_HOME", str(Path.home() / ".hermes")))
+    parser.add_argument("--skip-models", action="store_true", help="Install code and dependencies without downloading model artifacts")
+    parser.add_argument("--check", action="store_true", help="Only verify an existing installation")
+    args = parser.parse_args()
+
+    home = Path(args.home).expanduser().resolve()
+    checkout = home / "hermes-agent"
+    python = Path(os.environ.get("HERMES_PYTHON", checkout / "venv" / "bin" / "python"))
+    hermes = shutil.which("hermes")
+    if not python.is_file() or not hermes:
+        raise SystemExit("Hermes installation not found. Install Hermes Agent first or set HERMES_HOME/HERMES_PYTHON.")
+
+    plugin_target = home / "plugins" / "local_rag"
+    text_target = home / "models" / "embeddinggemma-litert"
+    visual_target = home / "models" / "clip-onnx"
+    required = [plugin_target / "plugin.yaml", text_target / TEXT_FILES[0], visual_target / VISUAL_FILES[0], visual_target / VISUAL_FILES[1]]
+    if args.check:
+        missing = [str(path) for path in required if not path.exists()]
+        run([hermes, "memory", "status"])
+        if missing:
+            raise SystemExit("Missing installation artifacts:\n" + "\n".join(missing))
+        env = {**os.environ, "PYTHONPATH": str(home / "plugins")}
+        run([str(python), "-c", "from local_rag import LocalRagProvider; assert LocalRagProvider().is_available()"], env=env)
+        print("Hermes Local RAG installation is healthy.")
+        return 0
+
+    uv = shutil.which("uv")
+    if not uv:
+        raise SystemExit("uv is required because Hermes venvs may not include pip")
+    repository = Path(__file__).resolve().parent
+    run([uv, "pip", "install", "--python", str(python), str(repository)])
+
+    plugin_target.parent.mkdir(parents=True, exist_ok=True)
+    temporary = plugin_target.with_name("local_rag.installing")
+    shutil.rmtree(temporary, ignore_errors=True)
+    shutil.copytree(repository / "local_rag", temporary, ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+    if plugin_target.exists():
+        backup = plugin_target.with_name("local_rag.previous")
+        shutil.rmtree(backup, ignore_errors=True)
+        plugin_target.replace(backup)
+    temporary.replace(plugin_target)
+
+    if not args.skip_models:
+        hf = python.parent / "hf"
+        if not hf.is_file():
+            raise SystemExit("Hugging Face CLI was not installed into the Hermes venv")
+        text_target.mkdir(parents=True, exist_ok=True)
+        visual_target.mkdir(parents=True, exist_ok=True)
+        try:
+            run([str(hf), "download", TEXT_REPO, *TEXT_FILES, "--local-dir", str(text_target)])
+            run([str(hf), "download", TOKENIZER_REPO, *TOKENIZER_FILES, "--local-dir", str(text_target)])
+            run([str(hf), "download", VISUAL_REPO, *VISUAL_FILES, "--local-dir", str(visual_target)])
+        except subprocess.CalledProcessError as exc:
+            raise SystemExit(
+                "Model download failed. EmbeddingGemma is gated: accept Gemma Terms on Hugging Face and run `hf auth login`, then rerun install.py."
+            ) from exc
+
+    run([hermes, "config", "set", "memory.provider", "local_rag"])
+    print("Installed. Restart the Hermes gateway or start a new Desktop session, then run: python install.py --check")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hermes_local_rag-1.3.1/local_rag/README.md

@@ -0,0 +1,57 @@
+# Hermes Local RAG
+
+User-local `MemoryProvider` for private hybrid recall. It lives outside the Hermes checkout and survives normal updates.
+
+## Storage and isolation
+
+- Text: `~/.hermes/local-rag/memory.sqlite` (SQLite WAL + FTS5 + local vectors)
+- Images: `~/.hermes/local-rag/visual.sqlite`
+- Namespace: `<profile>:<platform-user>`, with Desktop/CLI mapped to `<profile>:local`
+- Model weights are shared read-only; records are always filtered by namespace before ranking.
+
+## Models
+
+- Text: EmbeddingGemma 300M LiteRT `seq512`, 512-dimensional Matryoshka output by default; configurable to 128/256/512/768.
+- Visual: quantized CLIP ViT-B/32 ONNX, 512 dimensions. Loaded lazily only for visual tools.
+
+The 512-token artifact is intentional. Normal chunks are at most 384 words with 64-word overlap; context injection has a separate 3,200-character hard budget. A 2048-token model would increase interactive work without improving these bounded chunks.
+
+Model weights are not distributed by this plugin. EmbeddingGemma remains subject to Gemma Terms; CLIP artifacts retain their upstream license.
+
+## Dashboard setup
+
+After installing the plugin from **Hermes Dashboard → Plugins**, open the **Local RAG** tab. The wizard installs dependencies, accepts a read-only Hugging Face token through a local password field, downloads the selected models, saves retention and embedding settings, activates the provider, and performs a health check. No Terminal is required for the normal path.
+
+The token is passed directly to `huggingface_hub.login`, is never placed in a subprocess argument, response, config file, or setup log, and remains governed by Hugging Face's credential storage. Gemma Terms must still be accepted by the user in the browser.
+
+## Ingestion
+
+- User turns and session summaries are retained indefinitely by default.
+- `~/.hermes/local-rag/config.json` can set `episodic_ttl_days` and `summary_ttl_days` to positive day counts; `null` means no expiry.
+- Explicit preferences, decisions, and environment statements enter a review queue.
+- Approved candidates and built-in Hermes memory writes become durable records.
+- Assistant claims and raw tool output are never promoted as user facts.
+- Secret-like content, `.env`, private keys, unsupported/binary files, oversized files, and paths outside the current project root are rejected before embedding.
+
+## Retrieval
+
+Hybrid ranking combines semantic similarity, FTS5 exact matches, importance, freshness, and a durable-memory boost. Low-scoring matches are omitted. Context injection includes provenance, limits repeated sources, and labels all retrieved text as untrusted data rather than instructions.
+
+## Agent tools
+
+`local_rag_remember`, `local_rag_search`, `local_rag_status`, `local_rag_forget`, `local_rag_review`, `local_rag_approve`, `local_rag_reject`, `local_rag_index_file`, `local_rag_prune`, `local_rag_index_image`, `local_rag_search_images`, `local_rag_forget_image`.
+
+## Maintenance CLI
+
+From the Hermes checkout:
+
+```sh
+PYTHONPATH="$HOME/.hermes/plugins" venv/bin/python -m local_rag.cli status
+PYTHONPATH="$HOME/.hermes/plugins" venv/bin/python -m local_rag.cli --namespace default:local search "query"
+```
+
+Raw transcript backfill is disabled. Historical sessions must first undergo selective semantic extraction into normalized memory items; raw user turns, assistant output, and extractive summaries are never indexed automatically.
+
+## Recovery
+
+Hermes backup discovers `local-rag/` through `backup_paths()`. Schema upgrades create `memory.pre-v2.sqlite` before the first v2 migration. A changed embedding dimension stops startup with an explicit reindex error instead of corrupting existing vectors.