From 3fd7cd6faf6bbed4fd0723d5ae86786cefcafeca Mon Sep 17 00:00:00 2001 From: ClaudioDrews Date: Wed, 3 Jun 2026 15:46:31 -0300 Subject: [PATCH] =?UTF-8?q?docs:=20Fase=20C=20=E2=80=94=20R3=20(Ollama),?= =?UTF-8?q?=20R4=20(cron=20jobs),=20R5=20(agent=20name),=20R6=20(Qdrant)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit R3: .env.example — Embedding backend reestruturado com Option A (Ollama, recomendado para produção) e Option B (OpenRouter). install.md passo 4 atualizado para mencionar Ollama como opção local. R4: install.md passo 8 — adicionados 3 cron jobs stack-base na tabela e nos exemplos CLI: holographic-memory-backup (backup semanal do memory_store.db), wiki-raw-ingest-monitor (detecção de drift em raw/), maas-heartbeat (healthcheck Qdrant/Redis/ARQ). R5: .env.example + install.md passo 6 — adicionado HERMES_AGENT_NAME. state.py write_entry agora loga warning quando AGENT_NAME não está definido. R6: install.md Troubleshooting — nota sobre coexistência de coleções Qdrant (knowledge_base + outras coleções de agentes externos). --- .env.example | 23 +++++++++++++---------- icarus/state.py | 5 +++++ setup/install.md | 37 +++++++++++++++++++++++++++++++++++++ 3 files changed, 55 insertions(+), 10 deletions(-) diff --git a/.env.example b/.env.example index 1ee62c1..31e8c22 100644 --- a/.env.example +++ b/.env.example @@ -4,10 +4,6 @@ # ── Required ────────────────────────────────────────── -# OpenRouter API key — REQUIRED only when EMBEDDING_API_BASE points to OpenRouter. -# For local providers (Ollama, vLLM, llama.cpp) leave unset or comment out. -OPENROUTER_API_KEY=sk-or-... - # Redis password (generate with: openssl rand -hex 16) REDIS_PASSWORD= @@ -49,12 +45,14 @@ MAA_ENV_PATH=/home/your-user/.env # ── Embedding Backend ───────────────────────────────── -# Default: OpenRouter with Qwen3-Embedding-8B. -# Recommended model: multilingual (excellent for non-English content), -# high-quality 4096d embeddings, fast inference, affordable pricing. -# To use a local model (Ollama, vLLM, llama.cpp), set both vars: -# EMBEDDING_API_BASE=http://host.docker.internal:11434/v1 -# EMBEDDING_MODEL=nomic-embed-text +# Choose ONE backend. If both are set, Ollama takes priority (local, zero cost). +# +# Option A: Ollama (recommended for production, local, zero latency) +OLLAMA_BASE_URL=http://localhost:11434 +OLLAMA_EMBEDDING_MODEL=nomic-embed-text +# +# Option B: OpenRouter (cloud, pay-per-use, multilingual Qwen3-Embedding-8B) +# OPENROUTER_API_KEY=sk-or-... # EMBEDDING_API_BASE=https://openrouter.ai/api/v1 # EMBEDDING_MODEL=qwen/qwen3-embedding-8b @@ -65,6 +63,11 @@ MAA_ENV_PATH=/home/your-user/.env # ── Strongly Recommended ────────────────────────────── +# Agent identity — distinguishes this agent in fabric entries and cross-agent +# handoffs. Without this, fabric entries use "agent" as a fallback and +# multi-agent deployments cannot tell agents apart. +HERMES_AGENT_NAME=hermes + # LLM extraction token limit — 1024 is too small, causes fabric truncation ICARUS_EXTRACTION_MAX_TOKENS=4096 diff --git a/icarus/state.py b/icarus/state.py index 3b16c6a..cb50742 100644 --- a/icarus/state.py +++ b/icarus/state.py @@ -313,6 +313,11 @@ def write_entry(entry_type, content, summary, tier="hot", tags="", platform="cli ts = now.strftime("%Y-%m-%dT%H%MZ") ts_iso = now.strftime("%Y-%m-%dT%H:%M:%SZ") agent = AGENT_NAME or "agent" + if not AGENT_NAME: + logger.warning( + "icarus: HERMES_AGENT_NAME not set — fabric entries will use agent=\"agent\". " + "Set HERMES_AGENT_NAME= in .env for multi-agent deployments." + ) suffix = secrets.token_hex(2) # derive a short slug from the summary for human-readable filenames slug = re.sub(r"[^a-z0-9]+", "-", summary.lower().strip())[:40].strip("-") diff --git a/setup/install.md b/setup/install.md index 3b64f71..a328964 100644 --- a/setup/install.md +++ b/setup/install.md @@ -165,6 +165,11 @@ Execution Agent protocol — insert it after the referenced section. **`SOUL.md`** — add Ground Truth level 2 (injected memory) and context injection convention as documented in `modifications/soul-rulebook.md`. +**`~/.hermes/.env`** — set `HERMES_AGENT_NAME=hermes` (or any unique name). +This distinguishes your agent in fabric entries and enables multi-agent +handoff. Without it, all entries use the fallback `agent: "agent"` and +cross-agent features are disabled. + These modifications ensure the agent treats injected memory as more authoritative than training knowledge, and knows where to find persisted information without re-discovering it. @@ -215,6 +220,9 @@ that keep the memory stack healthy. Copy them to a location of your choice | `pre_validator.py` | On-demand | Semantic linter — queries knowledge_base before I/O actions | | `reflection_trigger.py` | Every 5 min | Triggers micro_reflection when ARQ worker is idle | | `bulk_wiki_ingest.py` | One-shot | Initial bulk ingestion of existing wiki content | +| `holographic-memory-backup.py` | Weekly (Mon 4am) | Dump and compress `memory_store.db` to backup directory | +| `wiki-raw-ingest-monitor.py` | Twice/week (Mon/Thu 3am) | Detects new or drifted files in `raw/` vs FTS5 index | +| `maas-heartbeat.py` | Every 6 hours | Health-check ping against Qdrant, Redis, and ARQ queue depth | **Using Hermes cron (recommended):** @@ -246,6 +254,27 @@ hermes cron create \ --script /path/to/scripts/semantic_dedup.py \ --no-agent \ --deliver local + +hermes cron create \ + --name "holographic-memory-backup" \ + --schedule "0 4 * * 1" \ + --script /path/to/scripts/holographic-memory-backup.py \ + --no-agent \ + --deliver local + +hermes cron create \ + --name "wiki-raw-ingest-monitor" \ + --schedule "0 3 * * 1,4" \ + --script /path/to/scripts/wiki-raw-ingest-monitor.py \ + --no-agent \ + --deliver local + +hermes cron create \ + --name "maas-heartbeat" \ + --schedule "0 */6 * * *" \ + --script /path/to/scripts/maas-heartbeat.py \ + --no-agent \ + --deliver local ``` **Before enabling decay scanner:** run `backfill_decay_metadata.py` once to @@ -307,3 +336,11 @@ Check: OpenRouter API key is set, `context_enhancer.py` can import, gateway rest ### Decay scanner produces "0 archived" every week Most likely: point payloads missing `last_accessed_at` or `importance_score` metadata. Run backfill before enabling decay. + +### Multiple collections in Qdrant dashboard + +The Memory OS uses the `knowledge_base` collection exclusively. Other +collections you may see (e.g., from other Hermes agent plugins or standalone +agents) are safe to coexist — Qdrant isolates each collection at the storage +and query level. Do NOT delete collections you did not create — they may +belong to other agents sharing the same Qdrant instance.