feat(cli): hermes memory setup/status with auto-discovery

Adds 'hermes memory setup' interactive wizard and 'hermes memory status'
command. Auto-detects installed memory plugins via the plugin system.

Setup flow:
1. Lists available providers (auto-detected from plugins)
2. User picks one (or built-in only)
3. Walks through provider's config schema (get_config_schema())
4. Writes non-secrets to config.yaml under memory.<name>
5. Writes secrets (API keys) to .env
6. Sets memory.provider in config.yaml

Status shows: current provider, config values, plugin availability,
missing credentials with URLs to get them.

Also adds get_config_schema() to MemoryProvider ABC and implements
it for all 6 providers with their specific config fields.

AGENTS.md

@@ -210,6 +210,10 @@ registry.register(
 
 The registry handles schema collection, dispatch, availability checking, and error wrapping. All handlers MUST return a JSON string.
 
+**Path references in tool schemas**: If the schema description mentions file paths (e.g. default output directories), use `display_hermes_home()` to make them profile-aware. The schema is generated at import time, which is after `_apply_profile_override()` sets `HERMES_HOME`.
+
+**State files**: If a tool stores persistent state (caches, logs, checkpoints), use `get_hermes_home()` for the base directory — never `Path.home() / ".hermes"`. This ensures each profile gets its own state.
+
 **Agent-level tools** (todo, memory): intercepted by `run_agent.py` before `handle_function_call()`. See `todo_tool.py` for the pattern.
 
 ---
@@ -358,8 +362,69 @@ in config.yaml (or `HERMES_BACKGROUND_NOTIFICATIONS` env var):
 
 ---
 
+## Profiles: Multi-Instance Support
+
+Hermes supports **profiles** — multiple fully isolated instances, each with its own
+`HERMES_HOME` directory (config, API keys, memory, sessions, skills, gateway, etc.).
+
+The core mechanism: `_apply_profile_override()` in `hermes_cli/main.py` sets
+`HERMES_HOME` before any module imports. All 119+ references to `get_hermes_home()`
+automatically scope to the active profile.
+
+### Rules for profile-safe code
+
+1. **Use `get_hermes_home()` for all HERMES_HOME paths.** Import from `hermes_constants`.
+   NEVER hardcode `~/.hermes` or `Path.home() / ".hermes"` in code that reads/writes state.
+   ```python
+   # GOOD
+   from hermes_constants import get_hermes_home
+   config_path = get_hermes_home() / "config.yaml"
+
+   # BAD — breaks profiles
+   config_path = Path.home() / ".hermes" / "config.yaml"
+   ```
+
+2. **Use `display_hermes_home()` for user-facing messages.** Import from `hermes_constants`.
+   This returns `~/.hermes` for default or `~/.hermes/profiles/<name>` for profiles.
+   ```python
+   # GOOD
+   from hermes_constants import display_hermes_home
+   print(f"Config saved to {display_hermes_home()}/config.yaml")
+
+   # BAD — shows wrong path for profiles
+   print("Config saved to ~/.hermes/config.yaml")
+   ```
+
+3. **Module-level constants are fine** — they cache `get_hermes_home()` at import time,
+   which is AFTER `_apply_profile_override()` sets the env var. Just use `get_hermes_home()`,
+   not `Path.home() / ".hermes"`.
+
+4. **Tests that mock `Path.home()` must also set `HERMES_HOME`** — since code now uses
+   `get_hermes_home()` (reads env var), not `Path.home() / ".hermes"`:
+   ```python
+   with patch.object(Path, "home", return_value=tmp_path), \
+        patch.dict(os.environ, {"HERMES_HOME": str(tmp_path / ".hermes")}):
+       ...
+   ```
+
+5. **Gateway platform adapters should use token locks** — if the adapter connects with
+   a unique credential (bot token, API key), call `acquire_scoped_lock()` from
+   `gateway.status` in the `connect()`/`start()` method and `release_scoped_lock()` in
+   `disconnect()`/`stop()`. This prevents two profiles from using the same credential.
+   See `gateway/platforms/telegram.py` for the canonical pattern.
+
+6. **Profile operations are HOME-anchored, not HERMES_HOME-anchored** — `_get_profiles_root()`
+   returns `Path.home() / ".hermes" / "profiles"`, NOT `get_hermes_home() / "profiles"`.
+   This is intentional — it lets `hermes -p coder profile list` see all profiles regardless
+   of which one is active.
+
 ## Known Pitfalls
 
+### DO NOT hardcode `~/.hermes` paths
+Use `get_hermes_home()` from `hermes_constants` for code paths. Use `display_hermes_home()`
+for user-facing print/log messages. Hardcoding `~/.hermes` breaks profiles — each profile
+has its own `HERMES_HOME` directory. This was the source of 5 bugs fixed in PR #3575.
+
 ### DO NOT use `simple_term_menu` for interactive menus
 Rendering bugs in tmux/iTerm2 — ghosting on scroll. Use `curses` (stdlib) instead. See `hermes_cli/tools_config.py` for the pattern.
 
@@ -375,6 +440,19 @@ Tool schema descriptions must not mention tools from other toolsets by name (e.g
 ### Tests must not write to `~/.hermes/`
 The `_isolate_hermes_home` autouse fixture in `tests/conftest.py` redirects `HERMES_HOME` to a temp dir. Never hardcode `~/.hermes/` paths in tests.
 
+**Profile tests**: When testing profile features, also mock `Path.home()` so that
+`_get_profiles_root()` and `_get_default_hermes_home()` resolve within the temp dir.
+Use the pattern from `tests/hermes_cli/test_profiles.py`:
+```python
+@pytest.fixture
+def profile_env(tmp_path, monkeypatch):
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    return home
+```
+
 ---
 
 ## Testing

acp_adapter/entry.py

@@ -74,7 +74,7 @@ def main() -> None:
 
     agent = HermesACPAgent()
     try:
-        asyncio.run(acp.run_agent(agent))
+        asyncio.run(acp.run_agent(agent, use_unstable_protocol=True))
     except KeyboardInterrupt:
         logger.info("Shutting down (KeyboardInterrupt)")
     except Exception:

acp_adapter/server.py

@@ -25,6 +25,9 @@ from acp.schema import (
     NewSessionResponse,
     PromptResponse,
     ResumeSessionResponse,
+    SetSessionConfigOptionResponse,
+    SetSessionModelResponse,
+    SetSessionModeResponse,
     ResourceContentBlock,
     SessionCapabilities,
     SessionForkCapabilities,
@@ -94,11 +97,14 @@ class HermesACPAgent(acp.Agent):
 
     async def initialize(
         self,
-        protocol_version: int,
+        protocol_version: int | None = None,
         client_capabilities: ClientCapabilities | None = None,
         client_info: Implementation | None = None,
         **kwargs: Any,
     ) -> InitializeResponse:
+        resolved_protocol_version = (
+            protocol_version if isinstance(protocol_version, int) else acp.PROTOCOL_VERSION
+        )
         provider = detect_provider()
         auth_methods = None
         if provider:
@@ -111,7 +117,11 @@ class HermesACPAgent(acp.Agent):
             ]
 
         client_name = client_info.name if client_info else "unknown"
-        logger.info("Initialize from %s (protocol v%s)", client_name, protocol_version)
+        logger.info(
+            "Initialize from %s (protocol v%s)",
+            client_name,
+            resolved_protocol_version,
+        )
 
         return InitializeResponse(
             protocol_version=acp.PROTOCOL_VERSION,
@@ -471,7 +481,7 @@ class HermesACPAgent(acp.Agent):
 
     async def set_session_model(
         self, model_id: str, session_id: str, **kwargs: Any
-    ):
+    ) -> SetSessionModelResponse | None:
         """Switch the model for a session (called by ACP protocol)."""
         state = self.session_manager.get_session(session_id)
         if state:
@@ -489,4 +499,37 @@ class HermesACPAgent(acp.Agent):
             )
             self.session_manager.save_session(session_id)
             logger.info("Session %s: model switched to %s", session_id, model_id)
+            return SetSessionModelResponse()
+        logger.warning("Session %s: model switch requested for missing session", session_id)
         return None
+
+    async def set_session_mode(
+        self, mode_id: str, session_id: str, **kwargs: Any
+    ) -> SetSessionModeResponse | None:
+        """Persist the editor-requested mode so ACP clients do not fail on mode switches."""
+        state = self.session_manager.get_session(session_id)
+        if state is None:
+            logger.warning("Session %s: mode switch requested for missing session", session_id)
+            return None
+        setattr(state, "mode", mode_id)
+        self.session_manager.save_session(session_id)
+        logger.info("Session %s: mode switched to %s", session_id, mode_id)
+        return SetSessionModeResponse()
+
+    async def set_config_option(
+        self, config_id: str, session_id: str, value: str, **kwargs: Any
+    ) -> SetSessionConfigOptionResponse | None:
+        """Accept ACP config option updates even when Hermes has no typed ACP config surface yet."""
+        state = self.session_manager.get_session(session_id)
+        if state is None:
+            logger.warning("Session %s: config update requested for missing session", session_id)
+            return None
+
+        options = getattr(state, "config_options", None)
+        if not isinstance(options, dict):
+            options = {}
+        options[str(config_id)] = value
+        setattr(state, "config_options", options)
+        self.session_manager.save_session(session_id)
+        logger.info("Session %s: config option %s updated", session_id, config_id)
+        return SetSessionConfigOptionResponse(config_options=[])

agent/builtin_memory_provider.py

@@ -0,0 +1,113 @@
+"""BuiltinMemoryProvider — wraps MEMORY.md / USER.md as a MemoryProvider.
+
+Always registered as the first provider. Cannot be disabled or removed.
+This is the existing Hermes memory system exposed through the provider
+interface for compatibility with the MemoryManager.
+
+The actual storage logic lives in tools/memory_tool.py (MemoryStore).
+This provider is a thin adapter that delegates to MemoryStore and
+exposes the memory tool schema.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+from agent.memory_provider import MemoryProvider
+
+logger = logging.getLogger(__name__)
+
+
+class BuiltinMemoryProvider(MemoryProvider):
+    """Built-in file-backed memory (MEMORY.md + USER.md).
+
+    Always active, never disabled by other providers. The `memory` tool
+    is handled by run_agent.py's agent-level tool interception (not through
+    the normal registry), so get_tool_schemas() returns an empty list —
+    the memory tool is already wired separately.
+    """
+
+    def __init__(
+        self,
+        memory_store=None,
+        memory_enabled: bool = False,
+        user_profile_enabled: bool = False,
+    ):
+        self._store = memory_store
+        self._memory_enabled = memory_enabled
+        self._user_profile_enabled = user_profile_enabled
+
+    @property
+    def name(self) -> str:
+        return "builtin"
+
+    def is_available(self) -> bool:
+        """Built-in memory is always available."""
+        return True
+
+    def initialize(self, session_id: str, **kwargs) -> None:
+        """Load memory from disk if not already loaded."""
+        if self._store is not None:
+            self._store.load_from_disk()
+
+    def system_prompt_block(self) -> str:
+        """Return MEMORY.md and USER.md content for the system prompt.
+
+        Uses the frozen snapshot captured at load time. This ensures the
+        system prompt stays stable throughout a session (preserving the
+        prompt cache), even though the live entries may change via tool calls.
+        """
+        if not self._store:
+            return ""
+
+        parts = []
+        if self._memory_enabled:
+            mem_block = self._store.format_for_system_prompt("memory")
+            if mem_block:
+                parts.append(mem_block)
+        if self._user_profile_enabled:
+            user_block = self._store.format_for_system_prompt("user")
+            if user_block:
+                parts.append(user_block)
+
+        return "\n\n".join(parts)
+
+    def prefetch(self, query: str) -> str:
+        """Built-in memory doesn't do query-based recall — it's injected via system_prompt_block."""
+        return ""
+
+    def sync_turn(self, user_content: str, assistant_content: str) -> None:
+        """Built-in memory doesn't auto-sync turns — writes happen via the memory tool."""
+
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        """Return empty list.
+
+        The `memory` tool is an agent-level intercepted tool, handled
+        specially in run_agent.py before normal tool dispatch. It's not
+        part of the standard tool registry. We don't duplicate it here.
+        """
+        return []
+
+    def handle_tool_call(self, tool_name: str, args: Dict[str, Any], **kwargs) -> str:
+        """Not used — the memory tool is intercepted in run_agent.py."""
+        return json.dumps({"error": "Built-in memory tool is handled by the agent loop"})
+
+    def shutdown(self) -> None:
+        """No cleanup needed — files are saved on every write."""
+
+    # -- Property access for backward compatibility --------------------------
+
+    @property
+    def store(self):
+        """Access the underlying MemoryStore for legacy code paths."""
+        return self._store
+
+    @property
+    def memory_enabled(self) -> bool:
+        return self._memory_enabled
+
+    @property
+    def user_profile_enabled(self) -> bool:
+        return self._user_profile_enabled

agent/memory_manager.py

@@ -0,0 +1,281 @@
+"""MemoryManager — orchestrates multiple memory providers.
+
+Single integration point in run_agent.py. Replaces scattered per-backend
+code with one manager that delegates to all registered providers.
+
+The BuiltinMemoryProvider is always registered first and cannot be removed.
+External providers are additive — they never disable the built-in store.
+
+Usage in run_agent.py:
+    self._memory_manager = MemoryManager()
+    self._memory_manager.add_provider(BuiltinMemoryProvider(...))
+    if honcho_configured:
+        self._memory_manager.add_provider(HonchoProvider(...))
+    # Plugin providers are added via register_memory_provider()
+
+    # System prompt
+    prompt_parts.append(self._memory_manager.build_system_prompt())
+
+    # Pre-turn
+    context = self._memory_manager.prefetch_all(user_message)
+
+    # Post-turn
+    self._memory_manager.sync_all(user_msg, assistant_response)
+    self._memory_manager.queue_prefetch_all(user_msg)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+from agent.memory_provider import MemoryProvider
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryManager:
+    """Orchestrates multiple memory providers.
+
+    Providers are called in registration order. The builtin provider
+    is always first. Failures in one provider never block others.
+    """
+
+    def __init__(self) -> None:
+        self._providers: List[MemoryProvider] = []
+        self._tool_to_provider: Dict[str, MemoryProvider] = {}
+
+    # -- Registration --------------------------------------------------------
+
+    def add_provider(self, provider: MemoryProvider) -> None:
+        """Register a memory provider.
+
+        Providers are called in registration order for all operations.
+        Tool name conflicts are resolved first-registered-wins.
+        """
+        self._providers.append(provider)
+
+        # Index tool names → provider for routing
+        for schema in provider.get_tool_schemas():
+            tool_name = schema.get("name", "")
+            if tool_name and tool_name not in self._tool_to_provider:
+                self._tool_to_provider[tool_name] = provider
+            elif tool_name in self._tool_to_provider:
+                logger.warning(
+                    "Memory tool name conflict: '%s' already registered by %s, "
+                    "ignoring from %s",
+                    tool_name,
+                    self._tool_to_provider[tool_name].name,
+                    provider.name,
+                )
+
+        logger.info(
+            "Memory provider '%s' registered (%d tools)",
+            provider.name,
+            len(provider.get_tool_schemas()),
+        )
+
+    @property
+    def providers(self) -> List[MemoryProvider]:
+        """All registered providers in order."""
+        return list(self._providers)
+
+    @property
+    def provider_names(self) -> List[str]:
+        """Names of all registered providers."""
+        return [p.name for p in self._providers]
+
+    def get_provider(self, name: str) -> Optional[MemoryProvider]:
+        """Get a provider by name, or None if not registered."""
+        for p in self._providers:
+            if p.name == name:
+                return p
+        return None
+
+    # -- System prompt -------------------------------------------------------
+
+    def build_system_prompt(self) -> str:
+        """Collect system prompt blocks from all providers.
+
+        Returns combined text, or empty string if no providers contribute.
+        Each non-empty block is labeled with the provider name.
+        """
+        blocks = []
+        for provider in self._providers:
+            try:
+                block = provider.system_prompt_block()
+                if block and block.strip():
+                    blocks.append(block)
+            except Exception as e:
+                logger.warning(
+                    "Memory provider '%s' system_prompt_block() failed: %s",
+                    provider.name, e,
+                )
+        return "\n\n".join(blocks)
+
+    # -- Prefetch / recall ---------------------------------------------------
+
+    def prefetch_all(self, query: str) -> str:
+        """Collect prefetch context from all providers.
+
+        Returns merged context text labeled by provider. Empty providers
+        are skipped. Failures in one provider don't block others.
+        """
+        parts = []
+        for provider in self._providers:
+            try:
+                result = provider.prefetch(query)
+                if result and result.strip():
+                    parts.append(result)
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' prefetch failed (non-fatal): %s",
+                    provider.name, e,
+                )
+        return "\n\n".join(parts)
+
+    def queue_prefetch_all(self, query: str) -> None:
+        """Queue background prefetch on all providers for the next turn."""
+        for provider in self._providers:
+            try:
+                provider.queue_prefetch(query)
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' queue_prefetch failed (non-fatal): %s",
+                    provider.name, e,
+                )
+
+    # -- Sync ----------------------------------------------------------------
+
+    def sync_all(self, user_content: str, assistant_content: str) -> None:
+        """Sync a completed turn to all providers."""
+        for provider in self._providers:
+            try:
+                provider.sync_turn(user_content, assistant_content)
+            except Exception as e:
+                logger.warning(
+                    "Memory provider '%s' sync_turn failed: %s",
+                    provider.name, e,
+                )
+
+    # -- Tools ---------------------------------------------------------------
+
+    def get_all_tool_schemas(self) -> List[Dict[str, Any]]:
+        """Collect tool schemas from all providers."""
+        schemas = []
+        seen = set()
+        for provider in self._providers:
+            try:
+                for schema in provider.get_tool_schemas():
+                    name = schema.get("name", "")
+                    if name and name not in seen:
+                        schemas.append(schema)
+                        seen.add(name)
+            except Exception as e:
+                logger.warning(
+                    "Memory provider '%s' get_tool_schemas() failed: %s",
+                    provider.name, e,
+                )
+        return schemas
+
+    def get_all_tool_names(self) -> set:
+        """Return set of all tool names across all providers."""
+        return set(self._tool_to_provider.keys())
+
+    def has_tool(self, tool_name: str) -> bool:
+        """Check if any provider handles this tool."""
+        return tool_name in self._tool_to_provider
+
+    def handle_tool_call(
+        self, tool_name: str, args: Dict[str, Any], **kwargs
+    ) -> str:
+        """Route a tool call to the correct provider.
+
+        Returns JSON string result. Raises ValueError if no provider
+        handles the tool.
+        """
+        provider = self._tool_to_provider.get(tool_name)
+        if provider is None:
+            return json.dumps({"error": f"No memory provider handles tool '{tool_name}'"})
+        try:
+            return provider.handle_tool_call(tool_name, args, **kwargs)
+        except Exception as e:
+            logger.error(
+                "Memory provider '%s' handle_tool_call(%s) failed: %s",
+                provider.name, tool_name, e,
+            )
+            return json.dumps({"error": f"Memory tool '{tool_name}' failed: {e}"})
+
+    # -- Lifecycle hooks -----------------------------------------------------
+
+    def on_turn_start(self, turn_number: int, message: str) -> None:
+        """Notify all providers of a new turn."""
+        for provider in self._providers:
+            try:
+                provider.on_turn_start(turn_number, message)
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' on_turn_start failed: %s",
+                    provider.name, e,
+                )
+
+    def on_session_end(self, messages: List[Dict[str, Any]]) -> None:
+        """Notify all providers of session end."""
+        for provider in self._providers:
+            try:
+                provider.on_session_end(messages)
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' on_session_end failed: %s",
+                    provider.name, e,
+                )
+
+    def on_pre_compress(self, messages: List[Dict[str, Any]]) -> None:
+        """Notify all providers before context compression."""
+        for provider in self._providers:
+            try:
+                provider.on_pre_compress(messages)
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' on_pre_compress failed: %s",
+                    provider.name, e,
+                )
+
+    def on_memory_write(self, action: str, target: str, content: str) -> None:
+        """Notify external providers when the built-in memory tool writes.
+
+        Skips the builtin provider itself (it's the source of the write).
+        """
+        for provider in self._providers:
+            if provider.name == "builtin":
+                continue
+            try:
+                provider.on_memory_write(action, target, content)
+            except Exception as e:
+                logger.debug(
+                    "Memory provider '%s' on_memory_write failed: %s",
+                    provider.name, e,
+                )
+
+    def shutdown_all(self) -> None:
+        """Shut down all providers (reverse order for clean teardown)."""
+        for provider in reversed(self._providers):
+            try:
+                provider.shutdown()
+            except Exception as e:
+                logger.warning(
+                    "Memory provider '%s' shutdown failed: %s",
+                    provider.name, e,
+                )
+
+    def initialize_all(self, session_id: str, **kwargs) -> None:
+        """Initialize all providers."""
+        for provider in self._providers:
+            try:
+                provider.initialize(session_id=session_id, **kwargs)
+            except Exception as e:
+                logger.warning(
+                    "Memory provider '%s' initialize failed: %s",
+                    provider.name, e,
+                )

agent/memory_provider.py

@@ -0,0 +1,171 @@
+"""Abstract base class for pluggable memory providers.
+
+Memory providers give the agent persistent recall across sessions. Multiple
+providers can be active simultaneously — the MemoryManager orchestrates them.
+
+Built-in memory (MEMORY.md / USER.md) is always active as the first provider.
+External providers (Honcho, Hindsight, Mem0, etc.) are additive — they never
+disable the built-in store.
+
+Three registration paths:
+  1. Built-in: BuiltinMemoryProvider — always present, not removable.
+  2. First-party: Ship with the repo, activated by config (e.g. Honcho).
+  3. Plugin: External packages register via ctx.register_memory_provider().
+
+Lifecycle (called by MemoryManager, wired in run_agent.py):
+  initialize()          — connect, create resources, warm up
+  system_prompt_block()  — static text for the system prompt
+  prefetch(query)        — background recall before each turn
+  sync_turn(user, asst)  — async write after each turn
+  get_tool_schemas()     — tool schemas to expose to the model
+  handle_tool_call()     — dispatch a tool call
+  shutdown()             — clean exit
+
+Optional hooks (override to opt in):
+  on_turn_start(turn, message)     — per-turn tick (scope cooling, etc.)
+  on_session_end(messages)         — end-of-session extraction
+  on_pre_compress(messages)        — extract before context compression
+  on_memory_write(action, target, content) — mirror built-in memory writes
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryProvider(ABC):
+    """Abstract base class for memory providers."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Short identifier for this provider (e.g. 'builtin', 'honcho', 'hindsight')."""
+
+    # -- Core lifecycle (implement these) ------------------------------------
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Return True if this provider is configured, has credentials, and is ready.
+
+        Called during agent init to decide whether to activate the provider.
+        Should not make network calls — just check config and installed deps.
+        """
+
+    @abstractmethod
+    def initialize(self, session_id: str, **kwargs) -> None:
+        """Initialize for a session.
+
+        Called once at agent startup. May create resources (banks, tables),
+        establish connections, start background threads, etc.
+
+        kwargs may include: platform, model, user_id, and other session context.
+        """
+
+    def system_prompt_block(self) -> str:
+        """Return text to include in the system prompt.
+
+        Called during system prompt assembly. Return empty string to skip.
+        This is for STATIC provider info (instructions, status). Prefetched
+        recall context is injected separately via prefetch().
+        """
+        return ""
+
+    def prefetch(self, query: str) -> str:
+        """Recall relevant context for the upcoming turn.
+
+        Called before each API call. Return formatted text to inject as
+        context, or empty string if nothing relevant. Implementations
+        should be fast — use background threads for the actual recall
+        and return cached results here.
+        """
+        return ""
+
+    def queue_prefetch(self, query: str) -> None:
+        """Queue a background recall for the NEXT turn.
+
+        Called after each turn completes. The result will be consumed
+        by prefetch() on the next turn. Default is no-op — providers
+        that do background prefetching should override this.
+        """
+
+    def sync_turn(self, user_content: str, assistant_content: str) -> None:
+        """Persist a completed turn to the backend.
+
+        Called after each turn. Should be non-blocking — queue for
+        background processing if the backend has latency.
+        """
+
+    @abstractmethod
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        """Return tool schemas this provider exposes.
+
+        Each schema follows the OpenAI function calling format:
+        {"name": "...", "description": "...", "parameters": {...}}
+
+        Return empty list if this provider has no tools (context-only).
+        """
+
+    def handle_tool_call(self, tool_name: str, args: Dict[str, Any], **kwargs) -> str:
+        """Handle a tool call for one of this provider's tools.
+
+        Must return a JSON string (the tool result).
+        Only called for tool names returned by get_tool_schemas().
+        """
+        raise NotImplementedError(f"Provider {self.name} does not handle tool {tool_name}")
+
+    def shutdown(self) -> None:
+        """Clean shutdown — flush queues, close connections."""
+
+    # -- Optional hooks (override to opt in) ---------------------------------
+
+    def on_turn_start(self, turn_number: int, message: str) -> None:
+        """Called at the start of each turn with the user message.
+
+        Use for turn-counting, scope management, periodic maintenance.
+        """
+
+    def on_session_end(self, messages: List[Dict[str, Any]]) -> None:
+        """Called when a session ends (explicit exit or timeout).
+
+        Use for end-of-session fact extraction, summarization, etc.
+        messages is the full conversation history.
+        """
+
+    def on_pre_compress(self, messages: List[Dict[str, Any]]) -> None:
+        """Called before context compression discards old messages.
+
+        Use to extract insights from messages about to be compressed.
+        messages is the list that will be summarized/discarded.
+        """
+
+    def get_config_schema(self) -> List[Dict[str, Any]]:
+        """Return config fields this provider needs for setup.
+
+        Used by 'hermes memory setup' to walk the user through configuration.
+        Each field is a dict with:
+          key:         config key name (e.g. 'api_key', 'mode')
+          description: human-readable description
+          secret:      True if this should go to .env (default: False)
+          required:    True if required (default: False)
+          default:     default value (optional)
+          choices:     list of valid values (optional)
+          url:         URL where user can get this credential (optional)
+          env_var:     explicit env var name for secrets (default: auto-generated)
+
+        Return empty list if no config needed (e.g. local-only providers).
+        """
+        return []
+
+    def on_memory_write(self, action: str, target: str, content: str) -> None:
+        """Called when the built-in memory tool writes an entry.
+
+        action: 'add', 'replace', or 'remove'
+        target: 'memory' or 'user'
+        content: the entry content
+
+        Use to mirror built-in memory writes to your backend.
+        """

agent/prompt_builder.py

@@ -18,6 +18,7 @@ from typing import Optional
 from agent.skill_utils import (
     extract_skill_conditions,
     extract_skill_description,
+    get_all_skills_dirs,
     get_disabled_skill_names,
     iter_skill_index_files,
     parse_frontmatter,
@@ -444,16 +445,23 @@ def build_skills_system_prompt(
          mtime/size manifest — survives process restarts
 
     Falls back to a full filesystem scan when both layers miss.
+
+    External skill directories (``skills.external_dirs`` in config.yaml) are
+    scanned alongside the local ``~/.hermes/skills/`` directory.  External dirs
+    are read-only — they appear in the index but new skills are always created
+    in the local dir.  Local skills take precedence when names collide.
     """
     hermes_home = get_hermes_home()
     skills_dir = hermes_home / "skills"
+    external_dirs = get_all_skills_dirs()[1:]  # skip local (index 0)
 
-    if not skills_dir.exists():
+    if not skills_dir.exists() and not external_dirs:
         return ""
 
     # ── Layer 1: in-process LRU cache ─────────────────────────────────
     cache_key = (
         str(skills_dir.resolve()),
+        tuple(str(d) for d in external_dirs),
         tuple(sorted(str(t) for t in (available_tools or set()))),
         tuple(sorted(str(ts) for ts in (available_toolsets or set()))),
     )
@@ -540,6 +548,56 @@ def build_skills_system_prompt(
             category_descriptions,
         )
 
+    # ── External skill directories ─────────────────────────────────────
+    # Scan external dirs directly (no snapshot caching — they're read-only
+    # and typically small).  Local skills already in skills_by_category take
+    # precedence: we track seen names and skip duplicates from external dirs.
+    seen_skill_names: set[str] = set()
+    for cat_skills in skills_by_category.values():
+        for name, _desc in cat_skills:
+            seen_skill_names.add(name)
+
+    for ext_dir in external_dirs:
+        if not ext_dir.exists():
+            continue
+        for skill_file in iter_skill_index_files(ext_dir, "SKILL.md"):
+            try:
+                is_compatible, frontmatter, desc = _parse_skill_file(skill_file)
+                if not is_compatible:
+                    continue
+                entry = _build_snapshot_entry(skill_file, ext_dir, frontmatter, desc)
+                skill_name = entry["skill_name"]
+                if skill_name in seen_skill_names:
+                    continue
+                if entry["frontmatter_name"] in disabled or skill_name in disabled:
+                    continue
+                if not _skill_should_show(
+                    extract_skill_conditions(frontmatter),
+                    available_tools,
+                    available_toolsets,
+                ):
+                    continue
+                seen_skill_names.add(skill_name)
+                skills_by_category.setdefault(entry["category"], []).append(
+                    (skill_name, entry["description"])
+                )
+            except Exception as e:
+                logger.debug("Error reading external skill %s: %s", skill_file, e)
+
+        # External category descriptions
+        for desc_file in iter_skill_index_files(ext_dir, "DESCRIPTION.md"):
+            try:
+                content = desc_file.read_text(encoding="utf-8")
+                fm, _ = parse_frontmatter(content)
+                cat_desc = fm.get("description")
+                if not cat_desc:
+                    continue
+                rel = desc_file.relative_to(ext_dir)
+                cat = "/".join(rel.parts[:-1]) if len(rel.parts) > 1 else "general"
+                category_descriptions.setdefault(cat, str(cat_desc).strip().strip("'\""))
+            except Exception as e:
+                logger.debug("Could not read external skill description %s: %s", desc_file, e)
+
     if not skills_by_category:
         result = ""
     else:

agent/skill_commands.py

@@ -128,7 +128,11 @@ def _build_skill_message(
                         supporting.append(rel)
 
     if supporting and skill_dir:
-        skill_view_target = str(skill_dir.relative_to(SKILLS_DIR))
+        try:
+            skill_view_target = str(skill_dir.relative_to(SKILLS_DIR))
+        except ValueError:
+            # Skill is from an external dir — use the skill name instead
+            skill_view_target = skill_dir.name
         parts.append("")
         parts.append("[This skill has supporting files you can load with the skill_view tool:]")
         for sf in supporting:
@@ -158,38 +162,49 @@ def scan_skill_commands() -> Dict[str, Dict[str, Any]]:
     _skill_commands = {}
     try:
         from tools.skills_tool import SKILLS_DIR, _parse_frontmatter, skill_matches_platform, _get_disabled_skill_names
-        if not SKILLS_DIR.exists():
-            return _skill_commands
+        from agent.skill_utils import get_external_skills_dirs
         disabled = _get_disabled_skill_names()
-        for skill_md in SKILLS_DIR.rglob("SKILL.md"):
-            if any(part in ('.git', '.github', '.hub') for part in skill_md.parts):
-                continue
-            try:
-                content = skill_md.read_text(encoding='utf-8')
-                frontmatter, body = _parse_frontmatter(content)
-                # Skip skills incompatible with the current OS platform
-                if not skill_matches_platform(frontmatter):
+        seen_names: set = set()
+
+        # Scan local dir first, then external dirs
+        dirs_to_scan = []
+        if SKILLS_DIR.exists():
+            dirs_to_scan.append(SKILLS_DIR)
+        dirs_to_scan.extend(get_external_skills_dirs())
+
+        for scan_dir in dirs_to_scan:
+            for skill_md in scan_dir.rglob("SKILL.md"):
+                if any(part in ('.git', '.github', '.hub') for part in skill_md.parts):
                     continue
-                name = frontmatter.get('name', skill_md.parent.name)
-                # Respect user's disabled skills config
-                if name in disabled:
+                try:
+                    content = skill_md.read_text(encoding='utf-8')
+                    frontmatter, body = _parse_frontmatter(content)
+                    # Skip skills incompatible with the current OS platform
+                    if not skill_matches_platform(frontmatter):
+                        continue
+                    name = frontmatter.get('name', skill_md.parent.name)
+                    if name in seen_names:
+                        continue
+                    # Respect user's disabled skills config
+                    if name in disabled:
+                        continue
+                    description = frontmatter.get('description', '')
+                    if not description:
+                        for line in body.strip().split('\n'):
+                            line = line.strip()
+                            if line and not line.startswith('#'):
+                                description = line[:80]
+                                break
+                    seen_names.add(name)
+                    cmd_name = name.lower().replace(' ', '-').replace('_', '-')
+                    _skill_commands[f"/{cmd_name}"] = {
+                        "name": name,
+                        "description": description or f"Invoke the {name} skill",
+                        "skill_md_path": str(skill_md),
+                        "skill_dir": str(skill_md.parent),
+                    }
+                except Exception:
                     continue
-                description = frontmatter.get('description', '')
-                if not description:
-                    for line in body.strip().split('\n'):
-                        line = line.strip()
-                        if line and not line.startswith('#'):
-                            description = line[:80]
-                            break
-                cmd_name = name.lower().replace(' ', '-').replace('_', '-')
-                _skill_commands[f"/{cmd_name}"] = {
-                    "name": name,
-                    "description": description or f"Invoke the {name} skill",
-                    "skill_md_path": str(skill_md),
-                    "skill_dir": str(skill_md.parent),
-                }
-            except Exception:
-                continue
     except Exception:
         pass
     return _skill_commands

agent/skill_utils.py

@@ -158,6 +158,73 @@ def _normalize_string_set(values) -> Set[str]:
     return {str(v).strip() for v in values if str(v).strip()}
 
 
+# ── External skills directories ──────────────────────────────────────────
+
+
+def get_external_skills_dirs() -> List[Path]:
+    """Read ``skills.external_dirs`` from config.yaml and return validated paths.
+
+    Each entry is expanded (``~`` and ``${VAR}``) and resolved to an absolute
+    path.  Only directories that actually exist are returned.  Duplicates and
+    paths that resolve to the local ``~/.hermes/skills/`` are silently skipped.
+    """
+    config_path = get_hermes_home() / "config.yaml"
+    if not config_path.exists():
+        return []
+    try:
+        parsed = yaml_load(config_path.read_text(encoding="utf-8"))
+    except Exception:
+        return []
+    if not isinstance(parsed, dict):
+        return []
+
+    skills_cfg = parsed.get("skills")
+    if not isinstance(skills_cfg, dict):
+        return []
+
+    raw_dirs = skills_cfg.get("external_dirs")
+    if not raw_dirs:
+        return []
+    if isinstance(raw_dirs, str):
+        raw_dirs = [raw_dirs]
+    if not isinstance(raw_dirs, list):
+        return []
+
+    local_skills = (get_hermes_home() / "skills").resolve()
+    seen: Set[Path] = set()
+    result: List[Path] = []
+
+    for entry in raw_dirs:
+        entry = str(entry).strip()
+        if not entry:
+            continue
+        # Expand ~ and environment variables
+        expanded = os.path.expanduser(os.path.expandvars(entry))
+        p = Path(expanded).resolve()
+        if p == local_skills:
+            continue
+        if p in seen:
+            continue
+        if p.is_dir():
+            seen.add(p)
+            result.append(p)
+        else:
+            logger.debug("External skills dir does not exist, skipping: %s", p)
+
+    return result
+
+
+def get_all_skills_dirs() -> List[Path]:
+    """Return all skill directories: local ``~/.hermes/skills/`` first, then external.
+
+    The local dir is always first (and always included even if it doesn't exist
+    yet — callers handle that).  External dirs follow in config order.
+    """
+    dirs = [get_hermes_home() / "skills"]
+    dirs.extend(get_external_skills_dirs())
+    return dirs
+
+
 # ── Condition extraction ──────────────────────────────────────────────────
 
 

cli-config.yaml.example

@@ -402,6 +402,15 @@ skills:
   # Set to 0 to disable.
   creation_nudge_interval: 15
 
+  # External skill directories — share skills across tools/agents without
+  # copying them into ~/.hermes/skills/.  Each path is expanded (~ and ${VAR})
+  # and resolved to an absolute path.  External dirs are read-only: skill
+  # creation always writes to ~/.hermes/skills/.  Local skills take precedence
+  # when names collide.
+  # external_dirs:
+  #   - ~/.agents/skills
+  #   - /home/shared/team-skills
+
 # =============================================================================
 # Agent Behavior
 # =============================================================================

cli.py

@@ -70,7 +70,7 @@ _COMMAND_SPINNER_FRAMES = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧
 
 # Load .env from ~/.hermes/.env first, then project root as dev fallback.
 # User-managed env files should override stale shell exports on restart.
-from hermes_constants import get_hermes_home, OPENROUTER_BASE_URL
+from hermes_constants import get_hermes_home, display_hermes_home, OPENROUTER_BASE_URL
 from hermes_cli.env_loader import load_hermes_dotenv
 
 _hermes_home = get_hermes_home()
@@ -3594,7 +3594,7 @@ class HermesCLI:
             print("  To start the gateway:")
             print("    python cli.py --gateway")
             print()
-            print("  Configuration file: ~/.hermes/config.yaml")
+            print(f"  Configuration file: {display_hermes_home()}/config.yaml")
             print()
             
         except Exception as e:
@@ -3604,7 +3604,7 @@ class HermesCLI:
             print("    1. Set environment variables:")
             print("       TELEGRAM_BOT_TOKEN=your_token")
             print("       DISCORD_BOT_TOKEN=your_token")
-            print("    2. Or configure settings in ~/.hermes/config.yaml")
+            print(f"    2. Or configure settings in {display_hermes_home()}/config.yaml")
             print()
     
     def process_command(self, command: str) -> bool:
@@ -3811,7 +3811,7 @@ class HermesCLI:
                 plugins = mgr.list_plugins()
                 if not plugins:
                     print("No plugins installed.")
-                    print("Drop plugin directories into ~/.hermes/plugins/ to get started.")
+                    print(f"Drop plugin directories into {display_hermes_home()}/plugins/ to get started.")
                 else:
                     print(f"Plugins ({len(plugins)}):")
                     for p in plugins:
@@ -4340,7 +4340,7 @@ class HermesCLI:
                 source = f" ({s['source']})" if s["source"] == "user" else ""
                 print(f"   {marker} {s['name']}{source} — {s['description']}")
             print("\n  Usage: /skin <name>")
-            print("  Custom skins: drop a YAML file in ~/.hermes/skins/\n")
+            print(f"  Custom skins: drop a YAML file in {display_hermes_home()}/skins/\n")
             return
 
         new_skin = parts[1].strip().lower()
@@ -5944,6 +5944,9 @@ class HermesCLI:
         ``normal_prompt`` is the full ``branding.prompt_symbol``.
         ``state_suffix`` is what special states (sudo/secret/approval/agent)
         should render after their leading icon.
+
+        When a profile is active (not "default"), the profile name is
+        prepended to the prompt symbol: ``coder ❯`` instead of ``❯``.
         """
         try:
             from hermes_cli.skin_engine import get_active_prompt_symbol
@@ -5952,6 +5955,15 @@ class HermesCLI:
             symbol = "❯ "
 
         symbol = (symbol or "❯ ").rstrip() + " "
+
+        # Prepend profile name when not default
+        try:
+            from hermes_cli.profiles import get_active_profile_name
+            profile = get_active_profile_name()
+            if profile not in ("default", "custom"):
+                symbol = f"{profile} {symbol}"
+        except Exception:
+            pass
         stripped = symbol.rstrip()
         if not stripped:
             return "❯ ", "❯ "

docker/entrypoint.sh

@@ -5,8 +5,11 @@ set -e
 HERMES_HOME="/opt/data"
 INSTALL_DIR="/opt/hermes"
 
-# Create directory structure
-mkdir -p "$HERMES_HOME"/{cron,sessions,logs,pairing,hooks,image_cache,audio_cache,memories,skills,whatsapp/session}
+# Create essential directory structure.  Cache and platform directories
+# (cache/images, cache/audio, platforms/whatsapp, etc.) are created on
+# demand by the application — don't pre-create them here so new installs
+# get the consolidated layout from get_hermes_dir().
+mkdir -p "$HERMES_HOME"/{cron,sessions,logs,hooks,memories,skills}
 
 # .env
 if [ ! -f "$HERMES_HOME/.env" ]; then

gateway/builtin_hooks/__init__.py

@@ -0,0 +1 @@
+"""Built-in gateway hooks that are always registered."""

gateway/builtin_hooks/boot_md.py

@@ -0,0 +1,86 @@
+"""Built-in boot-md hook — run ~/.hermes/BOOT.md on gateway startup.
+
+This hook is always registered. It silently skips if no BOOT.md exists.
+To activate, create ``~/.hermes/BOOT.md`` with instructions for the
+agent to execute on every gateway restart.
+
+Example BOOT.md::
+
+    # Startup Checklist
+
+    1. Check if any cron jobs failed overnight
+    2. Send a status update to Discord #general
+    3. If there are errors in /opt/app/deploy.log, summarize them
+
+The agent runs in a background thread so it doesn't block gateway
+startup. If nothing needs attention, it replies with [SILENT] to
+suppress delivery.
+"""
+
+import logging
+import os
+import threading
+from pathlib import Path
+
+logger = logging.getLogger("hooks.boot-md")
+
+HERMES_HOME = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
+BOOT_FILE = HERMES_HOME / "BOOT.md"
+
+
+def _build_boot_prompt(content: str) -> str:
+    """Wrap BOOT.md content in a system-level instruction."""
+    return (
+        "You are running a startup boot checklist. Follow the BOOT.md "
+        "instructions below exactly.\n\n"
+        "---\n"
+        f"{content}\n"
+        "---\n\n"
+        "Execute each instruction. If you need to send a message to a "
+        "platform, use the send_message tool.\n"
+        "If nothing needs attention and there is nothing to report, "
+        "reply with ONLY: [SILENT]"
+    )
+
+
+def _run_boot_agent(content: str) -> None:
+    """Spawn a one-shot agent session to execute the boot instructions."""
+    try:
+        from run_agent import AIAgent
+
+        prompt = _build_boot_prompt(content)
+        agent = AIAgent(
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+            max_iterations=20,
+        )
+        result = agent.run_conversation(prompt)
+        response = result.get("final_response", "")
+        if response and "[SILENT]" not in response:
+            logger.info("boot-md completed: %s", response[:200])
+        else:
+            logger.info("boot-md completed (nothing to report)")
+    except Exception as e:
+        logger.error("boot-md agent failed: %s", e)
+
+
+async def handle(event_type: str, context: dict) -> None:
+    """Gateway startup handler — run BOOT.md if it exists."""
+    if not BOOT_FILE.exists():
+        return
+
+    content = BOOT_FILE.read_text(encoding="utf-8").strip()
+    if not content:
+        return
+
+    logger.info("Running BOOT.md (%d chars)", len(content))
+
+    # Run in a background thread so we don't block gateway startup.
+    thread = threading.Thread(
+        target=_run_boot_agent,
+        args=(content,),
+        name="boot-md",
+        daemon=True,
+    )
+    thread.start()

gateway/hooks.py

@@ -51,14 +51,33 @@ class HookRegistry:
         """Return metadata about all loaded hooks."""
         return list(self._loaded_hooks)
 
+    def _register_builtin_hooks(self) -> None:
+        """Register built-in hooks that are always active."""
+        try:
+            from gateway.builtin_hooks.boot_md import handle as boot_md_handle
+
+            self._handlers.setdefault("gateway:startup", []).append(boot_md_handle)
+            self._loaded_hooks.append({
+                "name": "boot-md",
+                "description": "Run ~/.hermes/BOOT.md on gateway startup",
+                "events": ["gateway:startup"],
+                "path": "(builtin)",
+            })
+        except Exception as e:
+            print(f"[hooks] Could not load built-in boot-md hook: {e}", flush=True)
+
     def discover_and_load(self) -> None:
         """
         Scan the hooks directory for hook directories and load their handlers.
 
+        Also registers built-in hooks that are always active.
+
         Each hook directory must contain:
           - HOOK.yaml with at least 'name' and 'events' keys
           - handler.py with a top-level 'handle' function (sync or async)
         """
+        self._register_builtin_hooks()
+
         if not HOOKS_DIR.exists():
             return
 

gateway/platforms/api_server.py

@@ -1261,6 +1261,17 @@ class APIServerAdapter(BasePlatformAdapter):
             self._app.router.add_post("/api/jobs/{job_id}/resume", self._handle_resume_job)
             self._app.router.add_post("/api/jobs/{job_id}/run", self._handle_run_job)
 
+            # Port conflict detection — fail fast if port is already in use
+            import socket as _socket
+            try:
+                with _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM) as _s:
+                    _s.settimeout(1)
+                    _s.connect(('127.0.0.1', self._port))
+                logger.error('[%s] Port %d already in use. Set a different port in config.yaml: platforms.api_server.port', self.name, self._port)
+                return False
+            except (ConnectionRefusedError, OSError):
+                pass  # port is free
+
             self._runner = web.AppRunner(self._app)
             await self._runner.setup()
             self._site = web.TCPSite(self._runner, self._host, self._port)

gateway/platforms/base.py

@@ -1005,7 +1005,7 @@ class BasePlatformAdapter(ABC):
             # simultaneous messages. Queue them without interrupting the active run,
             # then process them immediately after the current task finishes.
             if event.message_type == MessageType.PHOTO:
-                print(f"[{self.name}] 🖼️ Queuing photo follow-up for session {session_key} without interrupt")
+                logger.debug("[%s] Queuing photo follow-up for session %s without interrupt", self.name, session_key)
                 existing = self._pending_messages.get(session_key)
                 if existing and existing.message_type == MessageType.PHOTO:
                     existing.media_urls.extend(event.media_urls)
@@ -1020,7 +1020,7 @@ class BasePlatformAdapter(ABC):
                 return  # Don't interrupt now - will run after current task completes
 
             # Default behavior for non-photo follow-ups: interrupt the running agent
-            print(f"[{self.name}] ⚡ New message while session {session_key} is active - triggering interrupt")
+            logger.debug("[%s] New message while session %s is active — triggering interrupt", self.name, session_key)
             self._pending_messages[session_key] = event
             # Signal the interrupt (the processing task checks this)
             self._active_sessions[session_key].set()
@@ -1206,9 +1206,9 @@ class BasePlatformAdapter(ABC):
                             )
 
                         if not media_result.success:
-                            print(f"[{self.name}] Failed to send media ({ext}): {media_result.error}")
+                            logger.warning("[%s] Failed to send media (%s): %s", self.name, ext, media_result.error)
                     except Exception as media_err:
-                        print(f"[{self.name}] Error sending media: {media_err}")
+                        logger.warning("[%s] Error sending media: %s", self.name, media_err)
 
                 # Send auto-detected local files as native attachments
                 for file_path in local_files:
@@ -1240,7 +1240,7 @@ class BasePlatformAdapter(ABC):
             # Check if there's a pending message that was queued during our processing
             if session_key in self._pending_messages:
                 pending_event = self._pending_messages.pop(session_key)
-                print(f"[{self.name}] 📨 Processing queued message from interrupt")
+                logger.debug("[%s] Processing queued message from interrupt", self.name)
                 # Clean up current session before processing pending
                 if session_key in self._active_sessions:
                     del self._active_sessions[session_key]
@@ -1254,9 +1254,7 @@ class BasePlatformAdapter(ABC):
                 return  # Already cleaned up
                 
         except Exception as e:
-            print(f"[{self.name}] Error handling message: {e}")
-            import traceback
-            traceback.print_exc()
+            logger.error("[%s] Error handling message: %s", self.name, e, exc_info=True)
             # Send the error to the user so they aren't left with radio silence
             try:
                 error_type = type(e).__name__

gateway/platforms/discord.py

@@ -486,6 +486,17 @@ class DiscordAdapter(BasePlatformAdapter):
             return False
         
         try:
+            # Acquire scoped lock to prevent duplicate bot token usage
+            from gateway.status import acquire_scoped_lock
+            self._token_lock_identity = self.config.token
+            acquired, existing = acquire_scoped_lock('discord-bot-token', self._token_lock_identity, metadata={'platform': 'discord'})
+            if not acquired:
+                owner_pid = existing.get('pid') if isinstance(existing, dict) else None
+                message = f'Discord bot token already in use' + (f' (PID {owner_pid})' if owner_pid else '') + '. Stop the other gateway first.'
+                logger.error('[%s] %s', self.name, message)
+                self._set_fatal_error('discord_token_lock', message, retryable=False)
+                return False
+
             # Set up intents -- members intent needed for username-to-ID resolution
             intents = Intents.default()
             intents.message_content = True
@@ -638,6 +649,16 @@ class DiscordAdapter(BasePlatformAdapter):
         self._running = False
         self._client = None
         self._ready_event.clear()
+
+        # Release the token lock
+        try:
+            from gateway.status import release_scoped_lock
+            if getattr(self, '_token_lock_identity', None):
+                release_scoped_lock('discord-bot-token', self._token_lock_identity)
+                self._token_lock_identity = None
+        except Exception:
+            pass
+
         logger.info("[%s] Disconnected", self.name)
     
     async def send(
@@ -1429,15 +1450,23 @@ class DiscordAdapter(BasePlatformAdapter):
         command_text: str,
         followup_msg: str | None = None,
     ) -> None:
-        """Common handler for simple slash commands that dispatch a command string."""
+        """Common handler for simple slash commands that dispatch a command string.
+
+        Defers the interaction (shows "thinking..."), dispatches the command,
+        then cleans up the deferred response.  If *followup_msg* is provided
+        the "thinking..." indicator is replaced with that text; otherwise it
+        is deleted so the channel isn't cluttered.
+        """
         await interaction.response.defer(ephemeral=True)
         event = self._build_slash_event(interaction, command_text)
         await self.handle_message(event)
-        if followup_msg:
-            try:
-                await interaction.followup.send(followup_msg, ephemeral=True)
-            except Exception as e:
-                logger.debug("Discord followup failed: %s", e)
+        try:
+            if followup_msg:
+                await interaction.edit_original_response(content=followup_msg)
+            else:
+                await interaction.delete_original_response()
+        except Exception as e:
+            logger.debug("Discord interaction cleanup failed: %s", e)
 
     def _register_slash_commands(self) -> None:
         """Register Discord slash commands on the command tree."""
@@ -1462,9 +1491,7 @@ class DiscordAdapter(BasePlatformAdapter):
         @tree.command(name="reasoning", description="Show or change reasoning effort")
         @discord.app_commands.describe(effort="Reasoning effort: xhigh, high, medium, low, minimal, or none.")
         async def slash_reasoning(interaction: discord.Interaction, effort: str = ""):
-            await interaction.response.defer(ephemeral=True)
-            event = self._build_slash_event(interaction, f"/reasoning {effort}".strip())
-            await self.handle_message(event)
+            await self._run_simple_slash(interaction, f"/reasoning {effort}".strip())
 
         @tree.command(name="personality", description="Set a personality")
         @discord.app_commands.describe(name="Personality name. Leave empty to list available.")
@@ -1537,9 +1564,7 @@ class DiscordAdapter(BasePlatformAdapter):
             discord.app_commands.Choice(name="status — show current mode", value="status"),
         ])
         async def slash_voice(interaction: discord.Interaction, mode: str = ""):
-            await interaction.response.defer(ephemeral=True)
-            event = self._build_slash_event(interaction, f"/voice {mode}".strip())
-            await self.handle_message(event)
+            await self._run_simple_slash(interaction, f"/voice {mode}".strip())
 
         @tree.command(name="update", description="Update Hermes Agent to the latest version")
         async def slash_update(interaction: discord.Interaction):

gateway/platforms/mattermost.py

@@ -603,9 +603,19 @@ class MattermostAdapter(BasePlatformAdapter):
         # For DMs, user_id is sufficient.  For channels, check for @mention.
         message_text = post.get("message", "")
 
-        # Mention-only mode: skip channel messages that don't @mention the bot.
-        # DMs (type "D") are always processed.
+        # Mention-gating for non-DM channels.
+        # Config (env vars):
+        #   MATTERMOST_REQUIRE_MENTION: Require @mention in channels (default: true)
+        #   MATTERMOST_FREE_RESPONSE_CHANNELS: Channel IDs where bot responds without mention
         if channel_type_raw != "D":
+            require_mention = os.getenv(
+                "MATTERMOST_REQUIRE_MENTION", "true"
+            ).lower() not in ("false", "0", "no")
+
+            free_channels_raw = os.getenv("MATTERMOST_FREE_RESPONSE_CHANNELS", "")
+            free_channels = {ch.strip() for ch in free_channels_raw.split(",") if ch.strip()}
+            is_free_channel = channel_id in free_channels
+
             mention_patterns = [
                 f"@{self._bot_username}",
                 f"@{self._bot_user_id}",
@@ -614,13 +624,21 @@ class MattermostAdapter(BasePlatformAdapter):
                 pattern.lower() in message_text.lower()
                 for pattern in mention_patterns
             )
-            if not has_mention:
+
+            if require_mention and not is_free_channel and not has_mention:
                 logger.debug(
                     "Mattermost: skipping non-DM message without @mention (channel=%s)",
                     channel_id,
                 )
                 return
 
+            # Strip @mention from the message text so the agent sees clean input.
+            if has_mention:
+                for pattern in mention_patterns:
+                    message_text = re.sub(
+                        re.escape(pattern), "", message_text, flags=re.IGNORECASE
+                    ).strip()
+
         # Resolve sender info.
         sender_id = post.get("user_id", "")
         sender_name = data.get("sender_name", "").lstrip("@") or sender_id

gateway/platforms/signal.py

@@ -22,7 +22,7 @@ import time
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Dict, List, Optional, Any
-from urllib.parse import unquote
+from urllib.parse import quote, unquote
 
 import httpx
 
@@ -184,6 +184,8 @@ class SignalAdapter(BasePlatformAdapter):
         self._recent_sent_timestamps: set = set()
         self._max_recent_timestamps = 50
 
+        self._phone_lock_identity: Optional[str] = None
+
         logger.info("Signal adapter initialized: url=%s account=%s groups=%s",
                      self.http_url, _redact_phone(self.account),
                      "enabled" if self.group_allow_from else "disabled")
@@ -198,6 +200,29 @@ class SignalAdapter(BasePlatformAdapter):
             logger.error("Signal: SIGNAL_HTTP_URL and SIGNAL_ACCOUNT are required")
             return False
 
+        # Acquire scoped lock to prevent duplicate Signal listeners for the same phone
+        try:
+            from gateway.status import acquire_scoped_lock
+
+            self._phone_lock_identity = self.account
+            acquired, existing = acquire_scoped_lock(
+                "signal-phone",
+                self._phone_lock_identity,
+                metadata={"platform": self.platform.value},
+            )
+            if not acquired:
+                owner_pid = existing.get("pid") if isinstance(existing, dict) else None
+                message = (
+                    "Another local Hermes gateway is already using this Signal account"
+                    + (f" (PID {owner_pid})." if owner_pid else ".")
+                    + " Stop the other gateway before starting a second Signal listener."
+                )
+                logger.error("Signal: %s", message)
+                self._set_fatal_error("signal_phone_lock", message, retryable=False)
+                return False
+        except Exception as e:
+            logger.warning("Signal: Could not acquire phone lock (non-fatal): %s", e)
+
         self.client = httpx.AsyncClient(timeout=30.0)
 
         # Health check — verify signal-cli daemon is reachable
@@ -245,6 +270,14 @@ class SignalAdapter(BasePlatformAdapter):
             await self.client.aclose()
             self.client = None
 
+        if self._phone_lock_identity:
+            try:
+                from gateway.status import release_scoped_lock
+                release_scoped_lock("signal-phone", self._phone_lock_identity)
+            except Exception as e:
+                logger.warning("Signal: Error releasing phone lock: %s", e, exc_info=True)
+            self._phone_lock_identity = None
+
         logger.info("Signal: disconnected")
 
     # ------------------------------------------------------------------
@@ -253,7 +286,7 @@ class SignalAdapter(BasePlatformAdapter):
 
     async def _sse_listener(self) -> None:
         """Listen for SSE events from signal-cli daemon."""
-        url = f"{self.http_url}/api/v1/events?account={self.account}"
+        url = f"{self.http_url}/api/v1/events?account={quote(self.account, safe='')}"
         backoff = SSE_RETRY_DELAY_INITIAL
 
         while self._running:
@@ -521,7 +554,7 @@ class SignalAdapter(BasePlatformAdapter):
         """Fetch an attachment via JSON-RPC and cache it. Returns (path, ext)."""
         result = await self._rpc("getAttachment", {
             "account": self.account,
-            "attachmentId": attachment_id,
+            "id": attachment_id,
         })
 
         if not result:

gateway/platforms/slack.py

@@ -93,6 +93,17 @@ class SlackAdapter(BasePlatformAdapter):
             return False
 
         try:
+            # Acquire scoped lock to prevent duplicate app token usage
+            from gateway.status import acquire_scoped_lock
+            self._token_lock_identity = app_token
+            acquired, existing = acquire_scoped_lock('slack-app-token', app_token, metadata={'platform': 'slack'})
+            if not acquired:
+                owner_pid = existing.get('pid') if isinstance(existing, dict) else None
+                message = f'Slack app token already in use' + (f' (PID {owner_pid})' if owner_pid else '') + '. Stop the other gateway first.'
+                logger.error('[%s] %s', self.name, message)
+                self._set_fatal_error('slack_token_lock', message, retryable=False)
+                return False
+
             self._app = AsyncApp(token=bot_token)
 
             # Get our own bot user ID for mention detection
@@ -138,6 +149,16 @@ class SlackAdapter(BasePlatformAdapter):
             except Exception as e:  # pragma: no cover - defensive logging
                 logger.warning("[Slack] Error while closing Socket Mode handler: %s", e, exc_info=True)
         self._running = False
+
+        # Release the token lock (use stored identity, not re-read env)
+        try:
+            from gateway.status import release_scoped_lock
+            if getattr(self, '_token_lock_identity', None):
+                release_scoped_lock('slack-app-token', self._token_lock_identity)
+                self._token_lock_identity = None
+        except Exception:
+            pass
+
         logger.info("[Slack] Disconnected")
 
     async def send(

gateway/platforms/webhook.py

@@ -118,6 +118,17 @@ class WebhookAdapter(BasePlatformAdapter):
         app.router.add_get("/health", self._handle_health)
         app.router.add_post("/webhooks/{route_name}", self._handle_webhook)
 
+        # Port conflict detection — fail fast if port is already in use
+        import socket as _socket
+        try:
+            with _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM) as _s:
+                _s.settimeout(1)
+                _s.connect(('127.0.0.1', self._port))
+            logger.error('[webhook] Port %d already in use. Set a different port in config.yaml: platforms.webhook.port', self._port)
+            return False
+        except (ConnectionRefusedError, OSError):
+            pass  # port is free
+
         self._runner = web.AppRunner(app)
         await self._runner.setup()
         site = web.TCPSite(self._runner, self._host, self._port)

gateway/platforms/whatsapp.py

@@ -142,6 +142,7 @@ class WhatsAppAdapter(BasePlatformAdapter):
         self._bridge_log_fh = None
         self._bridge_log: Optional[Path] = None
         self._poll_task: Optional[asyncio.Task] = None
+        self._session_lock_identity: Optional[str] = None
     
     async def connect(self) -> bool:
         """
@@ -160,6 +161,29 @@ class WhatsAppAdapter(BasePlatformAdapter):
         
         logger.info("[%s] Bridge found at %s", self.name, bridge_path)
         
+        # Acquire scoped lock to prevent duplicate sessions
+        try:
+            from gateway.status import acquire_scoped_lock
+
+            self._session_lock_identity = str(self._session_path)
+            acquired, existing = acquire_scoped_lock(
+                "whatsapp-session",
+                self._session_lock_identity,
+                metadata={"platform": self.platform.value},
+            )
+            if not acquired:
+                owner_pid = existing.get("pid") if isinstance(existing, dict) else None
+                message = (
+                    "Another local Hermes gateway is already using this WhatsApp session"
+                    + (f" (PID {owner_pid})." if owner_pid else ".")
+                    + " Stop the other gateway before starting a second WhatsApp bridge."
+                )
+                logger.error("[%s] %s", self.name, message)
+                self._set_fatal_error("whatsapp_session_lock", message, retryable=False)
+                return False
+        except Exception as e:
+            logger.warning("[%s] Could not acquire session lock (non-fatal): %s", self.name, e)
+
         # Auto-install npm dependencies if node_modules doesn't exist
         bridge_dir = bridge_path.parent
         if not (bridge_dir / "node_modules").exists():
@@ -313,6 +337,12 @@ class WhatsAppAdapter(BasePlatformAdapter):
             return True
             
         except Exception as e:
+            if self._session_lock_identity:
+                try:
+                    from gateway.status import release_scoped_lock
+                    release_scoped_lock("whatsapp-session", self._session_lock_identity)
+                except Exception:
+                    pass
             logger.error("[%s] Failed to start bridge: %s", self.name, e, exc_info=True)
             self._close_bridge_log()
             return False
@@ -371,9 +401,17 @@ class WhatsAppAdapter(BasePlatformAdapter):
             # Bridge was not started by us, don't kill it
             print(f"[{self.name}] Disconnecting (external bridge left running)")
         
+        if self._session_lock_identity:
+            try:
+                from gateway.status import release_scoped_lock
+                release_scoped_lock("whatsapp-session", self._session_lock_identity)
+            except Exception as e:
+                logger.warning("[%s] Error releasing WhatsApp session lock: %s", self.name, e, exc_info=True)
+
         self._mark_disconnected()
         self._bridge_process = None
         self._close_bridge_log()
+        self._session_lock_identity = None
         print(f"[{self.name}] Disconnected")
     
     async def send(

gateway/run.py

@@ -959,6 +959,13 @@ class GatewayRunner:
         """
         logger.info("Starting Hermes Gateway...")
         logger.info("Session storage: %s", self.config.sessions_dir)
+        try:
+            from hermes_cli.profiles import get_active_profile_name
+            _profile = get_active_profile_name()
+            if _profile and _profile != "default":
+                logger.info("Active profile: %s", _profile)
+        except Exception:
+            pass
         try:
             from gateway.status import write_runtime_status
             write_runtime_status(gateway_state="starting", exit_reason=None)

hermes_cli/auth.py

@@ -2021,7 +2021,8 @@ def _login_openai_codex(args, pconfig: ProviderConfig) -> None:
     config_path = _update_config_for_provider("openai-codex", creds.get("base_url", DEFAULT_CODEX_BASE_URL))
     print()
     print("Login successful!")
-    print("  Auth state: ~/.hermes/auth.json")
+    from hermes_constants import display_hermes_home as _dhh
+    print(f"  Auth state: {_dhh()}/auth.json")
     print(f"  Config updated: {config_path} (model.provider=openai-codex)")
 
 

hermes_cli/banner.py

@@ -403,6 +403,15 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
     if mcp_connected:
         summary_parts.append(f"{mcp_connected} MCP servers")
     summary_parts.append("/help for commands")
+    # Show active profile name when not 'default'
+    try:
+        from hermes_cli.profiles import get_active_profile_name
+        _profile_name = get_active_profile_name()
+        if _profile_name and _profile_name != "default":
+            right_lines.append(f"[bold {accent}]Profile:[/] [{text}]{_profile_name}[/]")
+    except Exception:
+        pass  # Never break the banner over a profiles.py bug
+
     right_lines.append(f"[dim {dim}]{' · '.join(summary_parts)}[/]")
 
     # Update check — use prefetched result if available

hermes_cli/callbacks.py

@@ -12,6 +12,7 @@ import getpass
 
 from hermes_cli.banner import cprint, _DIM, _RST
 from hermes_cli.config import save_env_value_secure
+from hermes_constants import display_hermes_home
 
 
 def clarify_callback(cli, question, choices):
@@ -131,7 +132,8 @@ def prompt_for_secret(cli, var_name: str, prompt: str, metadata=None) -> dict:
             }
 
         stored = save_env_value_secure(var_name, value)
-        cprint(f"\n{_DIM}  ✓ Stored secret in ~/.hermes/.env as {var_name}{_RST}")
+        _dhh = display_hermes_home()
+        cprint(f"\n{_DIM}  ✓ Stored secret in {_dhh}/.env as {var_name}{_RST}")
         return {
             **stored,
             "skipped": False,
@@ -183,7 +185,8 @@ def prompt_for_secret(cli, var_name: str, prompt: str, metadata=None) -> dict:
                 }
 
             stored = save_env_value_secure(var_name, value)
-            cprint(f"\n{_DIM}  ✓ Stored secret in ~/.hermes/.env as {var_name}{_RST}")
+            _dhh = display_hermes_home()
+            cprint(f"\n{_DIM}  ✓ Stored secret in {_dhh}/.env as {var_name}{_RST}")
             return {
                 **stored,
                 "skipped": False,

hermes_cli/config.py

@@ -346,6 +346,11 @@ DEFAULT_CONFIG = {
         "user_profile_enabled": True,
         "memory_char_limit": 2200,   # ~800 tokens at 2.75 chars/token
         "user_char_limit": 1375,     # ~500 tokens at 2.75 chars/token
+        # External memory provider (plugin). At most one active at a time.
+        # Set to the provider name (e.g. "holographic", "hindsight", "mem0")
+        # or leave empty for built-in only. Auto-detected from plugins that
+        # call ctx.register_memory_provider().
+        "provider": "",
     },
 
     # Subagent delegation — override the provider:model used by delegate_task
@@ -366,6 +371,13 @@ DEFAULT_CONFIG = {
     # Never saved to sessions, logs, or trajectories.
     "prefill_messages_file": "",
     
+    # Skills — external skill directories for sharing skills across tools/agents.
+    # Each path is expanded (~, ${VAR}) and resolved.  Read-only — skill creation
+    # always goes to ~/.hermes/skills/.
+    "skills": {
+        "external_dirs": [],   # e.g. ["~/.agents/skills", "/shared/team-skills"]
+    },
+
     # Honcho AI-native memory -- reads ~/.honcho/config.json as single source of truth.
     # This section is only needed for hermes-specific overrides; everything else
     # (apiKey, workspace, peerName, sessions, enabled) comes from the global config.
@@ -817,6 +829,20 @@ OPTIONAL_ENV_VARS = {
         "password": False,
         "category": "messaging",
     },
+    "MATTERMOST_REQUIRE_MENTION": {
+        "description": "Require @mention in Mattermost channels (default: true). Set to false to respond to all messages.",
+        "prompt": "Require @mention in channels",
+        "url": None,
+        "password": False,
+        "category": "messaging",
+    },
+    "MATTERMOST_FREE_RESPONSE_CHANNELS": {
+        "description": "Comma-separated Mattermost channel IDs where bot responds without @mention",
+        "prompt": "Free-response channel IDs (comma-separated)",
+        "url": None,
+        "password": False,
+        "category": "messaging",
+    },
     "MATRIX_HOMESERVER": {
         "description": "Matrix homeserver URL (e.g. https://matrix.example.org)",
         "prompt": "Matrix homeserver URL",

hermes_cli/doctor.py

@@ -10,9 +10,11 @@ import subprocess
 import shutil
 
 from hermes_cli.config import get_project_root, get_hermes_home, get_env_path
+from hermes_constants import display_hermes_home
 
 PROJECT_ROOT = get_project_root()
 HERMES_HOME = get_hermes_home()
+_DHH = display_hermes_home()  # user-facing display path (e.g. ~/.hermes or ~/.hermes/profiles/coder)
 
 # Load environment variables from ~/.hermes/.env so API key checks work
 from dotenv import load_dotenv
@@ -209,14 +211,14 @@ def run_doctor(args):
     # Check ~/.hermes/.env (primary location for user config)
     env_path = HERMES_HOME / '.env'
     if env_path.exists():
-        check_ok("~/.hermes/.env file exists")
+        check_ok(f"{_DHH}/.env file exists")
         
         # Check for common issues
         content = env_path.read_text()
         if _has_provider_env_config(content):
             check_ok("API key or custom endpoint configured")
         else:
-            check_warn("No API key found in ~/.hermes/.env")
+            check_warn(f"No API key found in {_DHH}/.env")
             issues.append("Run 'hermes setup' to configure API keys")
     else:
         # Also check project root as fallback
@@ -224,11 +226,11 @@ def run_doctor(args):
         if fallback_env.exists():
             check_ok(".env file exists (in project directory)")
         else:
-            check_fail("~/.hermes/.env file missing")
+            check_fail(f"{_DHH}/.env file missing")
             if should_fix:
                 env_path.parent.mkdir(parents=True, exist_ok=True)
                 env_path.touch()
-                check_ok("Created empty ~/.hermes/.env")
+                check_ok(f"Created empty {_DHH}/.env")
                 check_info("Run 'hermes setup' to configure API keys")
                 fixed_count += 1
             else:
@@ -238,7 +240,7 @@ def run_doctor(args):
     # Check ~/.hermes/config.yaml (primary) or project cli-config.yaml (fallback)
     config_path = HERMES_HOME / 'config.yaml'
     if config_path.exists():
-        check_ok("~/.hermes/config.yaml exists")
+        check_ok(f"{_DHH}/config.yaml exists")
     else:
         fallback_config = PROJECT_ROOT / 'cli-config.yaml'
         if fallback_config.exists():
@@ -248,11 +250,11 @@ def run_doctor(args):
             if should_fix and example_config.exists():
                 config_path.parent.mkdir(parents=True, exist_ok=True)
                 shutil.copy2(str(example_config), str(config_path))
-                check_ok("Created ~/.hermes/config.yaml from cli-config.yaml.example")
+                check_ok(f"Created {_DHH}/config.yaml from cli-config.yaml.example")
                 fixed_count += 1
             elif should_fix:
                 check_warn("config.yaml not found and no example to copy from")
-                manual_issues.append("Create ~/.hermes/config.yaml manually")
+                manual_issues.append(f"Create {_DHH}/config.yaml manually")
             else:
                 check_warn("config.yaml not found", "(using defaults)")
     
@@ -294,28 +296,28 @@ def run_doctor(args):
     
     hermes_home = HERMES_HOME
     if hermes_home.exists():
-        check_ok("~/.hermes directory exists")
+        check_ok(f"{_DHH} directory exists")
     else:
         if should_fix:
             hermes_home.mkdir(parents=True, exist_ok=True)
-            check_ok("Created ~/.hermes directory")
+            check_ok(f"Created {_DHH} directory")
             fixed_count += 1
         else:
-            check_warn("~/.hermes not found", "(will be created on first use)")
+            check_warn(f"{_DHH} not found", "(will be created on first use)")
     
     # Check expected subdirectories
     expected_subdirs = ["cron", "sessions", "logs", "skills", "memories"]
     for subdir_name in expected_subdirs:
         subdir_path = hermes_home / subdir_name
         if subdir_path.exists():
-            check_ok(f"~/.hermes/{subdir_name}/ exists")
+            check_ok(f"{_DHH}/{subdir_name}/ exists")
         else:
             if should_fix:
                 subdir_path.mkdir(parents=True, exist_ok=True)
-                check_ok(f"Created ~/.hermes/{subdir_name}/")
+                check_ok(f"Created {_DHH}/{subdir_name}/")
                 fixed_count += 1
             else:
-                check_warn(f"~/.hermes/{subdir_name}/ not found", "(will be created on first use)")
+                check_warn(f"{_DHH}/{subdir_name}/ not found", "(will be created on first use)")
     
     # Check for SOUL.md persona file
     soul_path = hermes_home / "SOUL.md"
@@ -324,11 +326,11 @@ def run_doctor(args):
         # Check if it's just the template comments (no real content)
         lines = [l for l in content.splitlines() if l.strip() and not l.strip().startswith(("<!--", "-->", "#"))]
         if lines:
-            check_ok("~/.hermes/SOUL.md exists (persona configured)")
+            check_ok(f"{_DHH}/SOUL.md exists (persona configured)")
         else:
-            check_info("~/.hermes/SOUL.md exists but is empty — edit it to customize personality")
+            check_info(f"{_DHH}/SOUL.md exists but is empty — edit it to customize personality")
     else:
-        check_warn("~/.hermes/SOUL.md not found", "(create it to give Hermes a custom personality)")
+        check_warn(f"{_DHH}/SOUL.md not found", "(create it to give Hermes a custom personality)")
         if should_fix:
             soul_path.parent.mkdir(parents=True, exist_ok=True)
             soul_path.write_text(
@@ -337,13 +339,13 @@ def run_doctor(args):
                 "You are Hermes, a helpful AI assistant.\n",
                 encoding="utf-8",
             )
-            check_ok("Created ~/.hermes/SOUL.md with basic template")
+            check_ok(f"Created {_DHH}/SOUL.md with basic template")
             fixed_count += 1
     
     # Check memory directory
     memories_dir = hermes_home / "memories"
     if memories_dir.exists():
-        check_ok("~/.hermes/memories/ directory exists")
+        check_ok(f"{_DHH}/memories/ directory exists")
         memory_file = memories_dir / "MEMORY.md"
         user_file = memories_dir / "USER.md"
         if memory_file.exists():
@@ -357,10 +359,10 @@ def run_doctor(args):
         else:
             check_info("USER.md not created yet (will be created when the agent first writes a memory)")
     else:
-        check_warn("~/.hermes/memories/ not found", "(will be created on first use)")
+        check_warn(f"{_DHH}/memories/ not found", "(will be created on first use)")
         if should_fix:
             memories_dir.mkdir(parents=True, exist_ok=True)
-            check_ok("Created ~/.hermes/memories/")
+            check_ok(f"Created {_DHH}/memories/")
             fixed_count += 1
     
     # Check SQLite session store
@@ -372,11 +374,11 @@ def run_doctor(args):
             cursor = conn.execute("SELECT COUNT(*) FROM sessions")
             count = cursor.fetchone()[0]
             conn.close()
-            check_ok(f"~/.hermes/state.db exists ({count} sessions)")
+            check_ok(f"{_DHH}/state.db exists ({count} sessions)")
         except Exception as e:
-            check_warn(f"~/.hermes/state.db exists but has issues: {e}")
+            check_warn(f"{_DHH}/state.db exists but has issues: {e}")
     else:
-        check_info("~/.hermes/state.db not created yet (will be created on first session)")
+        check_info(f"{_DHH}/state.db not created yet (will be created on first session)")
 
     _check_gateway_service_linger(issues)
     
@@ -691,7 +693,7 @@ def run_doctor(args):
     if github_token:
         check_ok("GitHub token configured (authenticated API access)")
     else:
-        check_warn("No GITHUB_TOKEN", "(60 req/hr rate limit — set in ~/.hermes/.env for better rates)")
+        check_warn("No GITHUB_TOKEN", f"(60 req/hr rate limit — set in {_DHH}/.env for better rates)")
 
     # =========================================================================
     # Honcho memory
@@ -728,6 +730,53 @@ def run_doctor(args):
     except Exception as _e:
         check_warn("Honcho check failed", str(_e))
 
+    # =========================================================================
+    # Profiles
+    # =========================================================================
+    try:
+        from hermes_cli.profiles import list_profiles, _get_wrapper_dir, profile_exists
+        import re as _re
+
+        named_profiles = [p for p in list_profiles() if not p.is_default]
+        if named_profiles:
+            print()
+            print(color("◆ Profiles", Colors.CYAN, Colors.BOLD))
+            check_ok(f"{len(named_profiles)} profile(s) found")
+            wrapper_dir = _get_wrapper_dir()
+            for p in named_profiles:
+                parts = []
+                if p.gateway_running:
+                    parts.append("gateway running")
+                if p.model:
+                    parts.append(p.model[:30])
+                if not (p.path / "config.yaml").exists():
+                    parts.append("⚠ missing config")
+                if not (p.path / ".env").exists():
+                    parts.append("no .env")
+                wrapper = wrapper_dir / p.name
+                if not wrapper.exists():
+                    parts.append("no alias")
+                status = ", ".join(parts) if parts else "configured"
+                check_ok(f"  {p.name}: {status}")
+
+            # Check for orphan wrappers
+            if wrapper_dir.is_dir():
+                for wrapper in wrapper_dir.iterdir():
+                    if not wrapper.is_file():
+                        continue
+                    try:
+                        content = wrapper.read_text()
+                        if "hermes -p" in content:
+                            _m = _re.search(r"hermes -p (\S+)", content)
+                            if _m and not profile_exists(_m.group(1)):
+                                check_warn(f"Orphan alias: {wrapper.name} → profile '{_m.group(1)}' no longer exists")
+                    except Exception:
+                        pass
+    except ImportError:
+        pass
+    except Exception as _e:
+        logger.debug("Profile health check failed: %s", _e)
+
     # =========================================================================
     # Summary
     # =========================================================================

hermes_cli/gateway.py

@@ -15,6 +15,8 @@ from pathlib import Path
 PROJECT_ROOT = Path(__file__).parent.parent.resolve()
 
 from hermes_cli.config import get_env_value, get_hermes_home, save_env_value, is_managed, managed_error
+# display_hermes_home is imported lazily at call sites to avoid ImportError
+# when hermes_constants is cached from a pre-update version during `hermes update`.
 from hermes_cli.setup import (
     print_header, print_info, print_success, print_warning, print_error,
     prompt, prompt_choice, prompt_yes_no,
@@ -935,7 +937,8 @@ def launchd_install(force: bool = False):
     print()
     print("Next steps:")
     print("  hermes gateway status             # Check status")
-    print("  tail -f ~/.hermes/logs/gateway.log  # View logs")
+    from hermes_constants import display_hermes_home as _dhh
+    print(f"  tail -f {_dhh()}/logs/gateway.log  # View logs")
 
 def launchd_uninstall():
     plist_path = get_launchd_plist_path()

hermes_cli/main.py

@@ -54,6 +54,71 @@ from typing import Optional
 PROJECT_ROOT = Path(__file__).parent.parent.resolve()
 sys.path.insert(0, str(PROJECT_ROOT))
 
+# ---------------------------------------------------------------------------
+# Profile override — MUST happen before any hermes module import.
+#
+# Many modules cache HERMES_HOME at import time (module-level constants).
+# We intercept --profile/-p from sys.argv here and set the env var so that
+# every subsequent ``os.getenv("HERMES_HOME", ...)`` resolves correctly.
+# The flag is stripped from sys.argv so argparse never sees it.
+# Falls back to ~/.hermes/active_profile for sticky default.
+# ---------------------------------------------------------------------------
+def _apply_profile_override() -> None:
+    """Pre-parse --profile/-p and set HERMES_HOME before module imports."""
+    argv = sys.argv[1:]
+    profile_name = None
+    consume = 0
+
+    # 1. Check for explicit -p / --profile flag
+    for i, arg in enumerate(argv):
+        if arg in ("--profile", "-p") and i + 1 < len(argv):
+            profile_name = argv[i + 1]
+            consume = 2
+            break
+        elif arg.startswith("--profile="):
+            profile_name = arg.split("=", 1)[1]
+            consume = 1
+            break
+
+    # 2. If no flag, check ~/.hermes/active_profile
+    if profile_name is None:
+        try:
+            active_path = Path.home() / ".hermes" / "active_profile"
+            if active_path.exists():
+                name = active_path.read_text().strip()
+                if name and name != "default":
+                    profile_name = name
+                    consume = 0  # don't strip anything from argv
+        except (UnicodeDecodeError, OSError):
+            pass  # corrupted file, skip
+
+    # 3. If we found a profile, resolve and set HERMES_HOME
+    if profile_name is not None:
+        try:
+            from hermes_cli.profiles import resolve_profile_env
+            hermes_home = resolve_profile_env(profile_name)
+        except (ValueError, FileNotFoundError) as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            sys.exit(1)
+        except Exception as exc:
+            # A bug in profiles.py must NEVER prevent hermes from starting
+            print(f"Warning: profile override failed ({exc}), using default", file=sys.stderr)
+            return
+        os.environ["HERMES_HOME"] = hermes_home
+        # Strip the flag from argv so argparse doesn't choke
+        if consume > 0:
+            for i, arg in enumerate(argv):
+                if arg in ("--profile", "-p"):
+                    start = i + 1  # +1 because argv is sys.argv[1:]
+                    sys.argv = sys.argv[:start] + sys.argv[start + consume:]
+                    break
+                elif arg.startswith("--profile="):
+                    start = i + 1
+                    sys.argv = sys.argv[:start] + sys.argv[start + 1:]
+                    break
+
+_apply_profile_override()
+
 # Load .env from ~/.hermes/.env first, then project root as dev fallback.
 # User-managed env files should override stale shell exports on restart.
 from hermes_cli.config import get_hermes_home
@@ -980,6 +1045,7 @@ def _model_flow_openrouter(config, current_model=""):
             cfg["model"] = model
         model["provider"] = "openrouter"
         model["base_url"] = OPENROUTER_BASE_URL
+        model["api_mode"] = "chat_completions"
         save_config(cfg)
         deactivate_provider()
         print(f"Default model set to: {selected} (via OpenRouter)")
@@ -1203,6 +1269,7 @@ def _model_flow_custom(config):
             cfg["model"] = model
         model["provider"] = "custom"
         model["base_url"] = effective_url
+        model["api_mode"] = "chat_completions"
         save_config(cfg)
         deactivate_provider()
 
@@ -1984,6 +2051,7 @@ def _model_flow_kimi(config, current_model=""):
             cfg["model"] = model
         model["provider"] = provider_id
         model["base_url"] = effective_base
+        model["api_mode"] = "chat_completions"
         save_config(cfg)
         deactivate_provider()
 
@@ -2090,6 +2158,7 @@ def _model_flow_api_key_provider(config, provider_id, current_model=""):
             cfg["model"] = model
         model["provider"] = provider_id
         model["base_url"] = effective_base
+        model["api_mode"] = "chat_completions"
         save_config(cfg)
         deactivate_provider()
 
@@ -2121,7 +2190,8 @@ def _run_anthropic_oauth_flow(save_env_value):
         ):
             use_anthropic_claude_code_credentials(save_fn=save_env_value)
             print("  ✓ Claude Code credentials linked.")
-            print("    Hermes will use Claude's credential store directly instead of copying a setup-token into ~/.hermes/.env.")
+            from hermes_constants import display_hermes_home as _dhh_fn
+            print(f"    Hermes will use Claude's credential store directly instead of copying a setup-token into {_dhh_fn()}/.env.")
             return True
         return False
 
@@ -2901,6 +2971,17 @@ def cmd_update(args):
         print()
         print("✓ Code updated!")
         
+        # After git pull, source files on disk are newer than cached Python
+        # modules in this process.  Reload hermes_constants so that any lazy
+        # import executed below (skills sync, gateway restart) sees new
+        # attributes like display_hermes_home() added since the last release.
+        try:
+            import importlib
+            import hermes_constants as _hc
+            importlib.reload(_hc)
+        except Exception:
+            pass  # non-fatal — worst case a lazy import fails gracefully
+        
         # Sync bundled skills (copies new, updates changed, respects user deletions)
         try:
             from tools.skills_sync import sync_skills
@@ -2919,7 +3000,35 @@ def cmd_update(args):
                 print("  ✓ Skills are up to date")
         except Exception as e:
             logger.debug("Skills sync during update failed: %s", e)
-        
+
+        # Sync bundled skills to all other profiles
+        try:
+            from hermes_cli.profiles import list_profiles, get_active_profile_name, seed_profile_skills
+            active = get_active_profile_name()
+            other_profiles = [p for p in list_profiles() if not p.is_default and p.name != active]
+            if other_profiles:
+                print()
+                print("→ Syncing bundled skills to other profiles...")
+                for p in other_profiles:
+                    try:
+                        r = seed_profile_skills(p.path, quiet=True)
+                        if r:
+                            copied = len(r.get("copied", []))
+                            updated = len(r.get("updated", []))
+                            modified = len(r.get("user_modified", []))
+                            parts = []
+                            if copied: parts.append(f"+{copied} new")
+                            if updated: parts.append(f"↑{updated} updated")
+                            if modified: parts.append(f"~{modified} user-modified")
+                            status = ", ".join(parts) if parts else "up to date"
+                        else:
+                            status = "sync failed"
+                        print(f"  {p.name}: {status}")
+                    except Exception as pe:
+                        print(f"  {p.name}: error ({pe})")
+        except Exception:
+            pass  # profiles module not available or no profiles
+
         # Check for config migrations
         print()
         print("→ Checking configuration for new options...")
@@ -3117,6 +3226,7 @@ def _coalesce_session_name_args(argv: list) -> list:
         "chat", "model", "gateway", "setup", "whatsapp", "login", "logout",
         "status", "cron", "doctor", "config", "pairing", "skills", "tools",
         "mcp", "sessions", "insights", "version", "update", "uninstall",
+        "profile",
     }
     _SESSION_FLAGS = {"-c", "--continue", "-r", "--resume"}
 
@@ -3140,6 +3250,253 @@ def _coalesce_session_name_args(argv: list) -> list:
     return result
 
 
+def cmd_profile(args):
+    """Profile management — create, delete, list, switch, alias."""
+    from hermes_cli.profiles import (
+        list_profiles, create_profile, delete_profile, seed_profile_skills,
+        get_active_profile, set_active_profile, get_active_profile_name,
+        check_alias_collision, create_wrapper_script, remove_wrapper_script,
+        _is_wrapper_dir_in_path, _get_wrapper_dir,
+    )
+    from hermes_constants import display_hermes_home
+
+    action = getattr(args, "profile_action", None)
+
+    if action is None:
+        # Bare `hermes profile` — show current profile status
+        profile_name = get_active_profile_name()
+        dhh = display_hermes_home()
+        print(f"\nActive profile: {profile_name}")
+        print(f"Path:           {dhh}")
+
+        profiles = list_profiles()
+        for p in profiles:
+            if p.name == profile_name or (profile_name == "default" and p.is_default):
+                if p.model:
+                    print(f"Model:          {p.model}" + (f" ({p.provider})" if p.provider else ""))
+                print(f"Gateway:        {'running' if p.gateway_running else 'stopped'}")
+                print(f"Skills:         {p.skill_count} installed")
+                if p.alias_path:
+                    print(f"Alias:          {p.name} → hermes -p {p.name}")
+                break
+        print()
+        return
+
+    if action == "list":
+        profiles = list_profiles()
+        active = get_active_profile_name()
+
+        if not profiles:
+            print("No profiles found.")
+            return
+
+        # Header
+        print(f"\n {'Profile':<16} {'Model':<28} {'Gateway':<12} {'Alias'}")
+        print(f" {'─' * 15}    {'─' * 27}    {'─' * 11}    {'─' * 12}")
+
+        for p in profiles:
+            marker = " ◆" if (p.name == active or (active == "default" and p.is_default)) else "  "
+            name = p.name
+            model = (p.model or "—")[:26]
+            gw = "running" if p.gateway_running else "stopped"
+            alias = p.name if p.alias_path else "—"
+            if p.is_default:
+                alias = "—"
+            print(f"{marker}{name:<15} {model:<28} {gw:<12} {alias}")
+        print()
+
+    elif action == "use":
+        name = args.profile_name
+        try:
+            set_active_profile(name)
+            if name == "default":
+                print(f"Switched to: default (~/.hermes)")
+            else:
+                print(f"Switched to: {name}")
+        except (ValueError, FileNotFoundError) as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+    elif action == "create":
+        name = args.profile_name
+        clone = getattr(args, "clone", False)
+        clone_all = getattr(args, "clone_all", False)
+        no_alias = getattr(args, "no_alias", False)
+
+        try:
+            clone_from = getattr(args, "clone_from", None)
+
+            profile_dir = create_profile(
+                name=name,
+                clone_from=clone_from,
+                clone_all=clone_all,
+                clone_config=clone,
+                no_alias=no_alias,
+            )
+            print(f"\nProfile '{name}' created at {profile_dir}")
+
+            if clone or clone_all:
+                source_label = getattr(args, "clone_from", None) or get_active_profile_name()
+                if clone_all:
+                    print(f"Full copy from {source_label}.")
+                else:
+                    print(f"Cloned config, .env, SOUL.md from {source_label}.")
+
+            # Seed bundled skills (skip if --clone-all already copied them)
+            if not clone_all:
+                result = seed_profile_skills(profile_dir)
+                if result:
+                    copied = len(result.get("copied", []))
+                    print(f"{copied} bundled skills synced.")
+                else:
+                    print("⚠ Skills could not be seeded. Run `{} update` to retry.".format(name))
+
+            # Create wrapper alias
+            if not no_alias:
+                collision = check_alias_collision(name)
+                if collision:
+                    print(f"\n⚠ Cannot create alias '{name}' — {collision}")
+                    print(f"  Choose a custom alias:  hermes profile alias {name} --name <custom>")
+                    print(f"  Or access via flag:     hermes -p {name} chat")
+                else:
+                    wrapper_path = create_wrapper_script(name)
+                    if wrapper_path:
+                        print(f"Wrapper created: {wrapper_path}")
+                        if not _is_wrapper_dir_in_path():
+                            print(f"\n⚠ {_get_wrapper_dir()} is not in your PATH.")
+                            print(f'  Add to your shell config (~/.bashrc or ~/.zshrc):')
+                            print(f'    export PATH="$HOME/.local/bin:$PATH"')
+
+            # Next steps
+            print(f"\nNext steps:")
+            print(f"  {name} setup              Configure API keys and model")
+            print(f"  {name} chat               Start chatting")
+            print(f"  {name} gateway start      Start the messaging gateway")
+            if clone or clone_all:
+                from hermes_constants import get_hermes_home
+                profile_dir_display = f"~/.hermes/profiles/{name}"
+                print(f"\n  Edit {profile_dir_display}/.env for different API keys")
+                print(f"  Edit {profile_dir_display}/SOUL.md for different personality")
+            print()
+
+        except (ValueError, FileExistsError, FileNotFoundError) as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+    elif action == "delete":
+        name = args.profile_name
+        yes = getattr(args, "yes", False)
+        try:
+            delete_profile(name, yes=yes)
+        except (ValueError, FileNotFoundError) as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+    elif action == "show":
+        name = args.profile_name
+        from hermes_cli.profiles import get_profile_dir, profile_exists, _read_config_model, _check_gateway_running, _count_skills
+        if not profile_exists(name):
+            print(f"Error: Profile '{name}' does not exist.")
+            sys.exit(1)
+        profile_dir = get_profile_dir(name)
+        model, provider = _read_config_model(profile_dir)
+        gw = _check_gateway_running(profile_dir)
+        skills = _count_skills(profile_dir)
+        wrapper = _get_wrapper_dir() / name
+
+        print(f"\nProfile: {name}")
+        print(f"Path:    {profile_dir}")
+        if model:
+            print(f"Model:   {model}" + (f" ({provider})" if provider else ""))
+        print(f"Gateway: {'running' if gw else 'stopped'}")
+        print(f"Skills:  {skills}")
+        print(f".env:    {'exists' if (profile_dir / '.env').exists() else 'not configured'}")
+        print(f"SOUL.md: {'exists' if (profile_dir / 'SOUL.md').exists() else 'not configured'}")
+        if wrapper.exists():
+            print(f"Alias:   {wrapper}")
+        print()
+
+    elif action == "alias":
+        name = args.profile_name
+        remove = getattr(args, "remove", False)
+        custom_name = getattr(args, "alias_name", None)
+
+        from hermes_cli.profiles import profile_exists
+        if not profile_exists(name):
+            print(f"Error: Profile '{name}' does not exist.")
+            sys.exit(1)
+
+        alias_name = custom_name or name
+
+        if remove:
+            if remove_wrapper_script(alias_name):
+                print(f"✓ Removed alias '{alias_name}'")
+            else:
+                print(f"No alias '{alias_name}' found to remove.")
+        else:
+            collision = check_alias_collision(alias_name)
+            if collision:
+                print(f"Error: {collision}")
+                sys.exit(1)
+            wrapper_path = create_wrapper_script(alias_name)
+            if wrapper_path:
+                # If custom name, write the profile name into the wrapper
+                if custom_name:
+                    wrapper_path.write_text(f'#!/bin/sh\nexec hermes -p {name} "$@"\n')
+                print(f"✓ Alias created: {wrapper_path}")
+                if not _is_wrapper_dir_in_path():
+                    print(f"⚠ {_get_wrapper_dir()} is not in your PATH.")
+
+    elif action == "rename":
+        from hermes_cli.profiles import rename_profile
+        try:
+            new_dir = rename_profile(args.old_name, args.new_name)
+            print(f"\nProfile renamed: {args.old_name} → {args.new_name}")
+            print(f"Path: {new_dir}\n")
+        except (ValueError, FileExistsError, FileNotFoundError) as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+    elif action == "export":
+        from hermes_cli.profiles import export_profile
+        name = args.profile_name
+        output = args.output or f"{name}.tar.gz"
+        try:
+            result_path = export_profile(name, output)
+            print(f"✓ Exported '{name}' to {result_path}")
+        except (ValueError, FileNotFoundError) as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+    elif action == "import":
+        from hermes_cli.profiles import import_profile
+        try:
+            profile_dir = import_profile(args.archive, name=getattr(args, "import_name", None))
+            name = profile_dir.name
+            print(f"✓ Imported profile '{name}' at {profile_dir}")
+
+            # Offer to create alias
+            collision = check_alias_collision(name)
+            if not collision:
+                wrapper_path = create_wrapper_script(name)
+                if wrapper_path:
+                    print(f"  Wrapper created: {wrapper_path}")
+            print()
+        except (ValueError, FileExistsError, FileNotFoundError) as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+
+def cmd_completion(args):
+    """Print shell completion script."""
+    from hermes_cli.profiles import generate_bash_completion, generate_zsh_completion
+    shell = getattr(args, "shell", "bash")
+    if shell == "zsh":
+        print(generate_zsh_completion())
+    else:
+        print(generate_bash_completion())
+
+
 def main():
     """Main entry point for hermes CLI."""
     parser = argparse.ArgumentParser(
@@ -3774,12 +4131,46 @@ For more help on a command:
 
     plugins_subparsers.add_parser("list", aliases=["ls"], help="List installed plugins")
 
+    plugins_enable = plugins_subparsers.add_parser(
+        "enable", help="Enable a disabled plugin"
+    )
+    plugins_enable.add_argument("name", help="Plugin name to enable")
+
+    plugins_disable = plugins_subparsers.add_parser(
+        "disable", help="Disable a plugin without removing it"
+    )
+    plugins_disable.add_argument("name", help="Plugin name to disable")
+
     def cmd_plugins(args):
         from hermes_cli.plugins_cmd import plugins_command
         plugins_command(args)
 
     plugins_parser.set_defaults(func=cmd_plugins)
 
+    # =========================================================================
+    # memory command
+    # =========================================================================
+    memory_parser = subparsers.add_parser(
+        "memory",
+        help="Manage memory provider plugins",
+        description=(
+            "Configure which memory provider plugin is active.\n\n"
+            "Memory providers give the agent persistent recall across sessions.\n"
+            "Built-in memory (MEMORY.md / USER.md) is always active.\n"
+            "One external provider can be active at a time."
+        ),
+        formatter_class=__import__("argparse").RawDescriptionHelpFormatter,
+    )
+    memory_subparsers = memory_parser.add_subparsers(dest="memory_command")
+    memory_subparsers.add_parser("setup", help="Interactive setup wizard")
+    memory_subparsers.add_parser("status", help="Show current provider and config")
+
+    def cmd_memory(args):
+        from hermes_cli.memory_setup import memory_command
+        memory_command(args)
+
+    memory_parser.set_defaults(func=cmd_memory)
+
     # =========================================================================
     # honcho command
     # =========================================================================
@@ -4327,7 +4718,75 @@ For more help on a command:
             sys.exit(1)
 
     acp_parser.set_defaults(func=cmd_acp)
-    
+
+    # =========================================================================
+    # profile command
+    # =========================================================================
+    profile_parser = subparsers.add_parser(
+        "profile",
+        help="Manage profiles — multiple isolated Hermes instances",
+    )
+    profile_subparsers = profile_parser.add_subparsers(dest="profile_action")
+
+    profile_list = profile_subparsers.add_parser("list", help="List all profiles")
+    profile_use = profile_subparsers.add_parser("use", help="Set sticky default profile")
+    profile_use.add_argument("profile_name", help="Profile name (or 'default')")
+
+    profile_create = profile_subparsers.add_parser("create", help="Create a new profile")
+    profile_create.add_argument("profile_name", help="Profile name (lowercase, alphanumeric)")
+    profile_create.add_argument("--clone", action="store_true",
+                                help="Copy config.yaml, .env, SOUL.md from active profile")
+    profile_create.add_argument("--clone-all", action="store_true",
+                                help="Full copy of active profile (all state)")
+    profile_create.add_argument("--clone-from", metavar="SOURCE",
+                                help="Source profile to clone from (default: active)")
+    profile_create.add_argument("--no-alias", action="store_true",
+                                help="Skip wrapper script creation")
+
+    profile_delete = profile_subparsers.add_parser("delete", help="Delete a profile")
+    profile_delete.add_argument("profile_name", help="Profile to delete")
+    profile_delete.add_argument("-y", "--yes", action="store_true",
+                                help="Skip confirmation prompt")
+
+    profile_show = profile_subparsers.add_parser("show", help="Show profile details")
+    profile_show.add_argument("profile_name", help="Profile to show")
+
+    profile_alias = profile_subparsers.add_parser("alias", help="Manage wrapper scripts")
+    profile_alias.add_argument("profile_name", help="Profile name")
+    profile_alias.add_argument("--remove", action="store_true",
+                               help="Remove the wrapper script")
+    profile_alias.add_argument("--name", dest="alias_name", metavar="NAME",
+                               help="Custom alias name (default: profile name)")
+
+    profile_rename = profile_subparsers.add_parser("rename", help="Rename a profile")
+    profile_rename.add_argument("old_name", help="Current profile name")
+    profile_rename.add_argument("new_name", help="New profile name")
+
+    profile_export = profile_subparsers.add_parser("export", help="Export a profile to archive")
+    profile_export.add_argument("profile_name", help="Profile to export")
+    profile_export.add_argument("-o", "--output", default=None,
+                                help="Output file (default: <name>.tar.gz)")
+
+    profile_import = profile_subparsers.add_parser("import", help="Import a profile from archive")
+    profile_import.add_argument("archive", help="Path to .tar.gz archive")
+    profile_import.add_argument("--name", dest="import_name", metavar="NAME",
+                                help="Profile name (default: inferred from archive)")
+
+    profile_parser.set_defaults(func=cmd_profile)
+
+    # =========================================================================
+    # completion command
+    # =========================================================================
+    completion_parser = subparsers.add_parser(
+        "completion",
+        help="Print shell completion script (bash or zsh)",
+    )
+    completion_parser.add_argument(
+        "shell", nargs="?", default="bash", choices=["bash", "zsh"],
+        help="Shell type (default: bash)",
+    )
+    completion_parser.set_defaults(func=cmd_completion)
+
     # =========================================================================
     # Parse and execute
     # =========================================================================

hermes_cli/mcp_config.py

@@ -24,6 +24,7 @@ from hermes_cli.config import (
     get_hermes_home,  # noqa: F401 — used by test mocks
 )
 from hermes_cli.colors import Colors, color
+from hermes_constants import display_hermes_home
 
 logger = logging.getLogger(__name__)
 
@@ -244,7 +245,7 @@ def cmd_mcp_add(args):
                     api_key = _prompt("API key / Bearer token", password=True)
                     if api_key:
                         save_env_value(env_key, api_key)
-                        _success(f"Saved to ~/.hermes/.env as {env_key}")
+                        _success(f"Saved to {display_hermes_home()}/.env as {env_key}")
 
                 # Set header with env var interpolation
                 if api_key or existing_key:
@@ -332,7 +333,7 @@ def cmd_mcp_add(args):
     _save_mcp_server(name, server_config)
 
     print()
-    _success(f"Saved '{name}' to ~/.hermes/config.yaml ({tool_count}/{total} tools enabled)")
+    _success(f"Saved '{name}' to {display_hermes_home()}/config.yaml ({tool_count}/{total} tools enabled)")
     _info("Start a new session to use these tools.")
 
 

hermes_cli/memory_setup.py

@@ -0,0 +1,357 @@
+"""hermes memory setup|status — configure memory provider plugins.
+
+Auto-detects installed memory providers via the plugin system.
+Interactive curses-based UI for provider selection, then walks through
+the provider's config schema. Writes config to config.yaml + .env.
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+import sys
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Curses-based interactive picker (same pattern as hermes tools)
+# ---------------------------------------------------------------------------
+
+def _curses_select(title: str, items: list[tuple[str, str]], default: int = 0) -> int:
+    """Interactive single-select with arrow keys.
+
+    items: list of (label, description) tuples.
+    Returns selected index, or default on escape/quit.
+    """
+    try:
+        import curses
+        result = [default]
+
+        def _menu(stdscr):
+            curses.curs_set(0)
+            if curses.has_colors():
+                curses.start_color()
+                curses.use_default_colors()
+                curses.init_pair(1, curses.COLOR_GREEN, -1)
+                curses.init_pair(2, curses.COLOR_YELLOW, -1)
+                curses.init_pair(3, curses.COLOR_CYAN, -1)
+            cursor = default
+
+            while True:
+                stdscr.clear()
+                max_y, max_x = stdscr.getmaxyx()
+
+                # Title
+                try:
+                    stdscr.addnstr(0, 0, title, max_x - 1,
+                                   curses.A_BOLD | (curses.color_pair(2) if curses.has_colors() else 0))
+                    stdscr.addnstr(1, 0, "  ↑↓ navigate  ⏎ select  q quit", max_x - 1,
+                                   curses.color_pair(3) if curses.has_colors() else curses.A_DIM)
+                except curses.error:
+                    pass
+
+                for i, (label, desc) in enumerate(items):
+                    y = i + 3
+                    if y >= max_y - 1:
+                        break
+                    arrow = "→" if i == cursor else " "
+                    line = f" {arrow}  {label}"
+                    if desc:
+                        line += f"  {desc}"
+
+                    attr = curses.A_NORMAL
+                    if i == cursor:
+                        attr = curses.A_BOLD
+                        if curses.has_colors():
+                            attr |= curses.color_pair(1)
+                    try:
+                        stdscr.addnstr(y, 0, line[:max_x - 1], max_x - 1, attr)
+                    except curses.error:
+                        pass
+
+                stdscr.refresh()
+                key = stdscr.getch()
+
+                if key in (curses.KEY_UP, ord('k')):
+                    cursor = (cursor - 1) % len(items)
+                elif key in (curses.KEY_DOWN, ord('j')):
+                    cursor = (cursor + 1) % len(items)
+                elif key in (curses.KEY_ENTER, 10, 13):
+                    result[0] = cursor
+                    return
+                elif key in (27, ord('q')):
+                    return
+
+        curses.wrapper(_menu)
+        return result[0]
+
+    except Exception:
+        # Fallback: numbered input
+        print(f"\n  {title}\n")
+        for i, (label, desc) in enumerate(items):
+            marker = "→" if i == default else " "
+            d = f"  {desc}" if desc else ""
+            print(f"  {marker} {i + 1}. {label}{d}")
+        while True:
+            try:
+                val = input(f"\n  Select [1-{len(items)}] ({default + 1}): ")
+                if not val:
+                    return default
+                idx = int(val) - 1
+                if 0 <= idx < len(items):
+                    return idx
+            except (ValueError, EOFError):
+                return default
+
+
+def _prompt(label: str, default: str | None = None, secret: bool = False) -> str:
+    """Prompt for a value with optional default and secret masking."""
+    suffix = f" [{default}]" if default else ""
+    if secret:
+        sys.stdout.write(f"  {label}{suffix}: ")
+        sys.stdout.flush()
+        if sys.stdin.isatty():
+            val = getpass.getpass(prompt="")
+        else:
+            val = sys.stdin.readline().strip()
+    else:
+        sys.stdout.write(f"  {label}{suffix}: ")
+        sys.stdout.flush()
+        val = sys.stdin.readline().strip()
+    return val or (default or "")
+
+
+# ---------------------------------------------------------------------------
+# Provider discovery
+# ---------------------------------------------------------------------------
+
+def _get_available_providers() -> list:
+    """Discover memory providers from installed plugins.
+
+    Returns list of (name, description, provider_instance) tuples.
+    """
+    try:
+        from hermes_cli.plugins import get_plugin_memory_providers
+        providers = get_plugin_memory_providers()
+    except Exception:
+        providers = []
+
+    results = []
+    for p in providers:
+        name = getattr(p, "name", "unknown")
+        schema = p.get_config_schema() if hasattr(p, "get_config_schema") else []
+        has_secrets = any(f.get("secret") for f in schema)
+        if has_secrets:
+            desc = "requires API key"
+        elif not schema:
+            desc = "no setup needed"
+        else:
+            desc = "local"
+        results.append((name, desc, p))
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Setup wizard
+# ---------------------------------------------------------------------------
+
+def cmd_setup(args) -> None:
+    """Interactive memory provider setup wizard."""
+    from hermes_cli.config import load_config, save_config
+
+    providers = _get_available_providers()
+
+    if not providers:
+        print("\n  No memory provider plugins detected.")
+        print("  Install a plugin to ~/.hermes/plugins/ and try again.\n")
+        return
+
+    # Build picker items
+    items = []
+    for name, desc, _ in providers:
+        items.append((name, f"— {desc}"))
+    items.append(("Built-in only", "— MEMORY.md / USER.md (default)"))
+
+    builtin_idx = len(items) - 1
+    selected = _curses_select("Memory provider setup", items, default=builtin_idx)
+
+    config = load_config()
+    if not isinstance(config.get("memory"), dict):
+        config["memory"] = {}
+
+    # Built-in only
+    if selected >= len(providers) or selected < 0:
+        config["memory"]["provider"] = ""
+        save_config(config)
+        print("\n  ✓ Memory provider: built-in only")
+        print("  Saved to config.yaml\n")
+        return
+
+    name, _, provider = providers[selected]
+    schema = provider.get_config_schema() if hasattr(provider, "get_config_schema") else []
+
+    # Provider config section
+    provider_config = config["memory"].get(name, {})
+    if not isinstance(provider_config, dict):
+        provider_config = {}
+
+    env_path = Path(os.environ.get("HERMES_HOME", os.path.expanduser("~/.hermes"))) / ".env"
+    env_writes = {}
+
+    if schema:
+        print(f"\n  Configuring {name}:\n")
+
+        for field in schema:
+            key = field["key"]
+            desc = field.get("description", key)
+            default = field.get("default")
+            is_secret = field.get("secret", False)
+            choices = field.get("choices")
+            env_var = field.get("env_var")
+            url = field.get("url")
+
+            if choices and not is_secret:
+                # Use curses picker for choice fields
+                choice_items = [(c, "") for c in choices]
+                current = provider_config.get(key, default)
+                current_idx = 0
+                if current and current in choices:
+                    current_idx = choices.index(current)
+                sel = _curses_select(f"  {desc}", choice_items, default=current_idx)
+                provider_config[key] = choices[sel]
+            elif is_secret:
+                # Prompt for secret
+                existing = os.environ.get(env_var, "") if env_var else ""
+                if existing:
+                    masked = f"...{existing[-4:]}" if len(existing) > 4 else "set"
+                    val = _prompt(f"{desc} (current: {masked}, blank to keep)", secret=True)
+                else:
+                    hint = f"  Get yours at {url}" if url else ""
+                    if hint:
+                        print(hint)
+                    val = _prompt(desc, secret=True)
+                if val and env_var:
+                    env_writes[env_var] = val
+            else:
+                # Regular text prompt
+                current = provider_config.get(key)
+                effective_default = current or default
+                val = _prompt(desc, default=str(effective_default) if effective_default else None)
+                if val:
+                    provider_config[key] = val
+
+    # Write config
+    config["memory"]["provider"] = name
+    config["memory"][name] = provider_config
+    save_config(config)
+
+    # Write secrets to .env
+    if env_writes:
+        _write_env_vars(env_path, env_writes)
+
+    print(f"\n  ✓ Memory provider: {name}")
+    print(f"  ✓ Config saved to config.yaml")
+    if env_writes:
+        print(f"  ✓ API keys saved to .env")
+    print(f"\n  Start a new session to activate.\n")
+
+
+def _write_env_vars(env_path: Path, env_writes: dict) -> None:
+    """Append or update env vars in .env file."""
+    env_path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing_lines = []
+    if env_path.exists():
+        existing_lines = env_path.read_text().splitlines()
+
+    updated_keys = set()
+    new_lines = []
+    for line in existing_lines:
+        key_match = line.split("=", 1)[0].strip() if "=" in line else ""
+        if key_match in env_writes:
+            new_lines.append(f"{key_match}={env_writes[key_match]}")
+            updated_keys.add(key_match)
+        else:
+            new_lines.append(line)
+
+    for key, val in env_writes.items():
+        if key not in updated_keys:
+            new_lines.append(f"{key}={val}")
+
+    env_path.write_text("\n".join(new_lines) + "\n")
+
+
+# ---------------------------------------------------------------------------
+# Status
+# ---------------------------------------------------------------------------
+
+def cmd_status(args) -> None:
+    """Show current memory provider config."""
+    from hermes_cli.config import load_config
+
+    config = load_config()
+    mem_config = config.get("memory", {})
+    provider_name = mem_config.get("provider", "")
+
+    print(f"\nMemory status\n" + "─" * 40)
+    print(f"  Built-in:  always active")
+    print(f"  Provider:  {provider_name or '(none — built-in only)'}")
+
+    if provider_name:
+        provider_config = mem_config.get(provider_name, {})
+        if provider_config:
+            print(f"\n  {provider_name} config:")
+            for key, val in provider_config.items():
+                print(f"    {key}: {val}")
+
+        providers = _get_available_providers()
+        found = any(name == provider_name for name, _, _ in providers)
+        if found:
+            print(f"\n  Plugin:    installed ✓")
+            for pname, _, p in providers:
+                if pname == provider_name:
+                    if p.is_available():
+                        print(f"  Status:    available ✓")
+                    else:
+                        print(f"  Status:    not available ✗")
+                        schema = p.get_config_schema() if hasattr(p, "get_config_schema") else []
+                        secrets = [f for f in schema if f.get("secret")]
+                        if secrets:
+                            print(f"  Missing:")
+                            for s in secrets:
+                                env_var = s.get("env_var", "")
+                                url = s.get("url", "")
+                                is_set = bool(os.environ.get(env_var))
+                                mark = "✓" if is_set else "✗"
+                                line = f"    {mark} {env_var}"
+                                if url and not is_set:
+                                    line += f"  → {url}"
+                                print(line)
+                    break
+        else:
+            print(f"\n  Plugin:    NOT installed ✗")
+            print(f"  Install the '{provider_name}' memory plugin to ~/.hermes/plugins/")
+
+    providers = _get_available_providers()
+    if providers:
+        print(f"\n  Installed plugins:")
+        for pname, desc, _ in providers:
+            active = " ← active" if pname == provider_name else ""
+            print(f"    • {pname}  ({desc}){active}")
+
+    print()
+
+
+# ---------------------------------------------------------------------------
+# Router
+# ---------------------------------------------------------------------------
+
+def memory_command(args) -> None:
+    """Route memory subcommands."""
+    sub = getattr(args, "memory_command", None)
+    if sub == "setup":
+        cmd_setup(args)
+    elif sub == "status":
+        cmd_status(args)
+    else:
+        cmd_status(args)

hermes_cli/plugins.py

@@ -68,6 +68,17 @@ def _env_enabled(name: str) -> bool:
     return os.getenv(name, "").strip().lower() in {"1", "true", "yes", "on"}
 
 
+def _get_disabled_plugins() -> set:
+    """Read the disabled plugins list from config.yaml."""
+    try:
+        from hermes_cli.config import load_config
+        config = load_config()
+        disabled = config.get("plugins", {}).get("disabled", [])
+        return set(disabled) if isinstance(disabled, list) else set()
+    except Exception:
+        return set()
+
+
 # ---------------------------------------------------------------------------
 # Data classes
 # ---------------------------------------------------------------------------
@@ -141,6 +152,28 @@ class PluginContext:
         self._manager._plugin_tool_names.add(name)
         logger.debug("Plugin %s registered tool: %s", self.manifest.name, name)
 
+    # -- memory provider registration ----------------------------------------
+
+    def register_memory_provider(self, provider) -> None:
+        """Register a memory provider (must implement MemoryProvider ABC).
+
+        The provider will be added to the MemoryManager during agent init.
+        Providers registered this way are additive — they never disable
+        the built-in MEMORY.md/USER.md store.
+
+        Example plugin __init__.py::
+
+            from my_memory_backend import MyMemoryProvider
+
+            def register(ctx):
+                ctx.register_memory_provider(MyMemoryProvider())
+        """
+        self._manager._memory_providers.append(provider)
+        logger.debug(
+            "Plugin %s registered memory provider: %s",
+            self.manifest.name, getattr(provider, "name", "unknown"),
+        )
+
     # -- hook registration --------------------------------------------------
 
     def register_hook(self, hook_name: str, callback: Callable) -> None:
@@ -172,6 +205,7 @@ class PluginManager:
         self._plugins: Dict[str, LoadedPlugin] = {}
         self._hooks: Dict[str, List[Callable]] = {}
         self._plugin_tool_names: Set[str] = set()
+        self._memory_providers: List = []  # MemoryProvider instances from plugins
         self._discovered: bool = False
 
     # -----------------------------------------------------------------------
@@ -199,8 +233,15 @@ class PluginManager:
         # 3. Pip / entry-point plugins
         manifests.extend(self._scan_entry_points())
 
-        # Load each manifest
+        # Load each manifest (skip user-disabled plugins)
+        disabled = _get_disabled_plugins()
         for manifest in manifests:
+            if manifest.name in disabled:
+                loaded = LoadedPlugin(manifest=manifest, enabled=False)
+                loaded.error = "disabled via config"
+                self._plugins[manifest.name] = loaded
+                logger.debug("Skipping disabled plugin '%s'", manifest.name)
+                continue
             self._load_plugin(manifest)
 
         if manifests:
@@ -510,3 +551,13 @@ def get_plugin_toolsets() -> List[tuple]:
         result.append((ts_key, label, desc))
 
     return result
+
+
+def get_plugin_memory_providers() -> List:
+    """Return MemoryProvider instances registered by plugins.
+
+    Called during AIAgent init to add plugin memory providers to
+    the MemoryManager alongside built-in providers.
+    """
+    manager = get_plugin_manager()
+    return list(manager._memory_providers)

hermes_cli/plugins_cmd.py

@@ -374,6 +374,73 @@ def cmd_remove(name: str) -> None:
     _display_removed(name, plugins_dir)
 
 
+def _get_disabled_set() -> set:
+    """Read the disabled plugins set from config.yaml."""
+    try:
+        from hermes_cli.config import load_config
+        config = load_config()
+        disabled = config.get("plugins", {}).get("disabled", [])
+        return set(disabled) if isinstance(disabled, list) else set()
+    except Exception:
+        return set()
+
+
+def _save_disabled_set(disabled: set) -> None:
+    """Write the disabled plugins list to config.yaml."""
+    from hermes_cli.config import load_config, save_config
+    config = load_config()
+    if "plugins" not in config:
+        config["plugins"] = {}
+    config["plugins"]["disabled"] = sorted(disabled)
+    save_config(config)
+
+
+def cmd_enable(name: str) -> None:
+    """Enable a previously disabled plugin."""
+    from rich.console import Console
+
+    console = Console()
+    plugins_dir = _plugins_dir()
+
+    # Verify the plugin exists
+    target = plugins_dir / name
+    if not target.is_dir():
+        console.print(f"[red]Plugin '{name}' is not installed.[/red]")
+        sys.exit(1)
+
+    disabled = _get_disabled_set()
+    if name not in disabled:
+        console.print(f"[dim]Plugin '{name}' is already enabled.[/dim]")
+        return
+
+    disabled.discard(name)
+    _save_disabled_set(disabled)
+    console.print(f"[green]✓[/green] Plugin [bold]{name}[/bold] enabled. Takes effect on next session.")
+
+
+def cmd_disable(name: str) -> None:
+    """Disable a plugin without removing it."""
+    from rich.console import Console
+
+    console = Console()
+    plugins_dir = _plugins_dir()
+
+    # Verify the plugin exists
+    target = plugins_dir / name
+    if not target.is_dir():
+        console.print(f"[red]Plugin '{name}' is not installed.[/red]")
+        sys.exit(1)
+
+    disabled = _get_disabled_set()
+    if name in disabled:
+        console.print(f"[dim]Plugin '{name}' is already disabled.[/dim]")
+        return
+
+    disabled.add(name)
+    _save_disabled_set(disabled)
+    console.print(f"[yellow]⊘[/yellow] Plugin [bold]{name}[/bold] disabled. Takes effect on next session.")
+
+
 def cmd_list() -> None:
     """List installed plugins."""
     from rich.console import Console
@@ -393,8 +460,11 @@ def cmd_list() -> None:
         console.print("[dim]Install with:[/dim] hermes plugins install owner/repo")
         return
 
+    disabled = _get_disabled_set()
+
     table = Table(title="Installed Plugins", show_lines=False)
     table.add_column("Name", style="bold")
+    table.add_column("Status")
     table.add_column("Version", style="dim")
     table.add_column("Description")
     table.add_column("Source", style="dim")
@@ -420,11 +490,86 @@ def cmd_list() -> None:
         if (d / ".git").exists():
             source = "git"
 
-        table.add_row(name, str(version), description, source)
+        is_disabled = name in disabled or d.name in disabled
+        status = "[red]disabled[/red]" if is_disabled else "[green]enabled[/green]"
+        table.add_row(name, status, str(version), description, source)
 
     console.print()
     console.print(table)
     console.print()
+    console.print("[dim]Interactive toggle:[/dim] hermes plugins")
+    console.print("[dim]Enable/disable:[/dim] hermes plugins enable/disable <name>")
+
+
+def cmd_toggle() -> None:
+    """Interactive curses checklist to enable/disable installed plugins."""
+    from rich.console import Console
+
+    try:
+        import yaml
+    except ImportError:
+        yaml = None
+
+    console = Console()
+    plugins_dir = _plugins_dir()
+
+    dirs = sorted(d for d in plugins_dir.iterdir() if d.is_dir())
+    if not dirs:
+        console.print("[dim]No plugins installed.[/dim]")
+        console.print("[dim]Install with:[/dim] hermes plugins install owner/repo")
+        return
+
+    disabled = _get_disabled_set()
+
+    # Build items list: "name — description" for display
+    names = []
+    labels = []
+    selected = set()
+
+    for i, d in enumerate(dirs):
+        manifest_file = d / "plugin.yaml"
+        name = d.name
+        description = ""
+
+        if manifest_file.exists() and yaml:
+            try:
+                with open(manifest_file) as f:
+                    manifest = yaml.safe_load(f) or {}
+                name = manifest.get("name", d.name)
+                description = manifest.get("description", "")
+            except Exception:
+                pass
+
+        names.append(name)
+        label = f"{name} — {description}" if description else name
+        labels.append(label)
+
+        if name not in disabled and d.name not in disabled:
+            selected.add(i)
+
+    from hermes_cli.curses_ui import curses_checklist
+
+    result = curses_checklist(
+        title="Plugins — toggle enabled/disabled",
+        items=labels,
+        selected=selected,
+    )
+
+    # Compute new disabled set from deselected items
+    new_disabled = set()
+    for i, name in enumerate(names):
+        if i not in result:
+            new_disabled.add(name)
+
+    if new_disabled != disabled:
+        _save_disabled_set(new_disabled)
+        enabled_count = len(names) - len(new_disabled)
+        console.print(
+            f"\n[green]✓[/green] {enabled_count} enabled, {len(new_disabled)} disabled. "
+            f"Takes effect on next session."
+        )
+    else:
+        console.print("\n[dim]No changes.[/dim]")
 
 
 def plugins_command(args) -> None:
@@ -437,8 +582,14 @@ def plugins_command(args) -> None:
         cmd_update(args.name)
     elif action in ("remove", "rm", "uninstall"):
         cmd_remove(args.name)
-    elif action in ("list", "ls") or action is None:
+    elif action == "enable":
+        cmd_enable(args.name)
+    elif action == "disable":
+        cmd_disable(args.name)
+    elif action in ("list", "ls"):
         cmd_list()
+    elif action is None:
+        cmd_toggle()
     else:
         from rich.console import Console
 

hermes_cli/profiles.py

@@ -0,0 +1,906 @@
+"""
+Profile management for multiple isolated Hermes instances.
+
+Each profile is a fully independent HERMES_HOME directory with its own
+config.yaml, .env, memory, sessions, skills, gateway, cron, and logs.
+Profiles live under ``~/.hermes/profiles/<name>/`` by default.
+
+The "default" profile is ``~/.hermes`` itself — backward compatible,
+zero migration needed.
+
+Usage::
+
+    hermes profile create coder          # fresh profile + bundled skills
+    hermes profile create coder --clone  # also copy config, .env, SOUL.md
+    hermes profile create coder --clone-all  # full copy of source profile
+    coder chat                           # use via wrapper alias
+    hermes -p coder chat                 # or via flag
+    hermes profile use coder             # set as sticky default
+    hermes profile delete coder          # remove profile + alias + service
+"""
+
+import json
+import os
+import re
+import shutil
+import stat
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+_PROFILE_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+
+# Directories bootstrapped inside every new profile
+_PROFILE_DIRS = [
+    "memories",
+    "sessions",
+    "skills",
+    "skins",
+    "logs",
+    "plans",
+    "workspace",
+    "cron",
+]
+
+# Files copied during --clone (if they exist in the source)
+_CLONE_CONFIG_FILES = [
+    "config.yaml",
+    ".env",
+    "SOUL.md",
+]
+
+# Runtime files stripped after --clone-all (shouldn't carry over)
+_CLONE_ALL_STRIP = [
+    "gateway.pid",
+    "gateway_state.json",
+    "processes.json",
+]
+
+# Names that cannot be used as profile aliases
+_RESERVED_NAMES = frozenset({
+    "hermes", "default", "test", "tmp", "root", "sudo",
+})
+
+# Hermes subcommands that cannot be used as profile names/aliases
+_HERMES_SUBCOMMANDS = frozenset({
+    "chat", "model", "gateway", "setup", "whatsapp", "login", "logout",
+    "status", "cron", "doctor", "config", "pairing", "skills", "tools",
+    "mcp", "sessions", "insights", "version", "update", "uninstall",
+    "profile", "plugins", "honcho", "acp",
+})
+
+
+# ---------------------------------------------------------------------------
+# Path helpers
+# ---------------------------------------------------------------------------
+
+def _get_profiles_root() -> Path:
+    """Return the directory where named profiles are stored.
+
+    Always ``~/.hermes/profiles/`` — anchored to the user's home,
+    NOT to the current HERMES_HOME (which may itself be a profile).
+    This ensures ``coder profile list`` can see all profiles.
+    """
+    return Path.home() / ".hermes" / "profiles"
+
+
+def _get_default_hermes_home() -> Path:
+    """Return the default (pre-profile) HERMES_HOME path."""
+    return Path.home() / ".hermes"
+
+
+def _get_active_profile_path() -> Path:
+    """Return the path to the sticky active_profile file."""
+    return _get_default_hermes_home() / "active_profile"
+
+
+def _get_wrapper_dir() -> Path:
+    """Return the directory for wrapper scripts."""
+    return Path.home() / ".local" / "bin"
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+def validate_profile_name(name: str) -> None:
+    """Raise ``ValueError`` if *name* is not a valid profile identifier."""
+    if name == "default":
+        return  # special alias for ~/.hermes
+    if not _PROFILE_ID_RE.match(name):
+        raise ValueError(
+            f"Invalid profile name {name!r}. Must match "
+            f"[a-z0-9][a-z0-9_-]{{0,63}}"
+        )
+
+
+def get_profile_dir(name: str) -> Path:
+    """Resolve a profile name to its HERMES_HOME directory."""
+    if name == "default":
+        return _get_default_hermes_home()
+    return _get_profiles_root() / name
+
+
+def profile_exists(name: str) -> bool:
+    """Check whether a profile directory exists."""
+    if name == "default":
+        return True
+    return get_profile_dir(name).is_dir()
+
+
+# ---------------------------------------------------------------------------
+# Alias / wrapper script management
+# ---------------------------------------------------------------------------
+
+def check_alias_collision(name: str) -> Optional[str]:
+    """Return a human-readable collision message, or None if the name is safe.
+
+    Checks: reserved names, hermes subcommands, existing binaries in PATH.
+    """
+    if name in _RESERVED_NAMES:
+        return f"'{name}' is a reserved name"
+    if name in _HERMES_SUBCOMMANDS:
+        return f"'{name}' conflicts with a hermes subcommand"
+
+    # Check existing commands in PATH
+    wrapper_dir = _get_wrapper_dir()
+    try:
+        result = subprocess.run(
+            ["which", name], capture_output=True, text=True, timeout=5,
+        )
+        if result.returncode == 0:
+            existing_path = result.stdout.strip()
+            # Allow overwriting our own wrappers
+            if existing_path == str(wrapper_dir / name):
+                try:
+                    content = (wrapper_dir / name).read_text()
+                    if "hermes -p" in content:
+                        return None  # it's our wrapper, safe to overwrite
+                except Exception:
+                    pass
+            return f"'{name}' conflicts with an existing command ({existing_path})"
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    return None  # safe
+
+
+def _is_wrapper_dir_in_path() -> bool:
+    """Check if ~/.local/bin is in PATH."""
+    wrapper_dir = str(_get_wrapper_dir())
+    return wrapper_dir in os.environ.get("PATH", "").split(os.pathsep)
+
+
+def create_wrapper_script(name: str) -> Optional[Path]:
+    """Create a shell wrapper script at ~/.local/bin/<name>.
+
+    Returns the path to the created wrapper, or None if creation failed.
+    """
+    wrapper_dir = _get_wrapper_dir()
+    try:
+        wrapper_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as e:
+        print(f"⚠ Could not create {wrapper_dir}: {e}")
+        return None
+
+    wrapper_path = wrapper_dir / name
+    try:
+        wrapper_path.write_text(f'#!/bin/sh\nexec hermes -p {name} "$@"\n')
+        wrapper_path.chmod(wrapper_path.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+        return wrapper_path
+    except OSError as e:
+        print(f"⚠ Could not create wrapper at {wrapper_path}: {e}")
+        return None
+
+
+def remove_wrapper_script(name: str) -> bool:
+    """Remove the wrapper script for a profile. Returns True if removed."""
+    wrapper_path = _get_wrapper_dir() / name
+    if wrapper_path.exists():
+        try:
+            # Verify it's our wrapper before removing
+            content = wrapper_path.read_text()
+            if "hermes -p" in content:
+                wrapper_path.unlink()
+                return True
+        except Exception:
+            pass
+    return False
+
+
+# ---------------------------------------------------------------------------
+# ProfileInfo
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ProfileInfo:
+    """Summary information about a profile."""
+    name: str
+    path: Path
+    is_default: bool
+    gateway_running: bool
+    model: Optional[str] = None
+    provider: Optional[str] = None
+    has_env: bool = False
+    skill_count: int = 0
+    alias_path: Optional[Path] = None
+
+
+def _read_config_model(profile_dir: Path) -> tuple:
+    """Read model/provider from a profile's config.yaml. Returns (model, provider)."""
+    config_path = profile_dir / "config.yaml"
+    if not config_path.exists():
+        return None, None
+    try:
+        import yaml
+        with open(config_path, "r") as f:
+            cfg = yaml.safe_load(f) or {}
+        model_cfg = cfg.get("model", {})
+        if isinstance(model_cfg, str):
+            return model_cfg, None
+        if isinstance(model_cfg, dict):
+            return model_cfg.get("model"), model_cfg.get("provider")
+        return None, None
+    except Exception:
+        return None, None
+
+
+def _check_gateway_running(profile_dir: Path) -> bool:
+    """Check if a gateway is running for a given profile directory."""
+    pid_file = profile_dir / "gateway.pid"
+    if not pid_file.exists():
+        return False
+    try:
+        raw = pid_file.read_text().strip()
+        if not raw:
+            return False
+        data = json.loads(raw) if raw.startswith("{") else {"pid": int(raw)}
+        pid = int(data["pid"])
+        os.kill(pid, 0)  # existence check
+        return True
+    except (json.JSONDecodeError, KeyError, ValueError, TypeError,
+            ProcessLookupError, PermissionError, OSError):
+        return False
+
+
+def _count_skills(profile_dir: Path) -> int:
+    """Count installed skills in a profile."""
+    skills_dir = profile_dir / "skills"
+    if not skills_dir.is_dir():
+        return 0
+    count = 0
+    for md in skills_dir.rglob("SKILL.md"):
+        if "/.hub/" not in str(md) and "/.git/" not in str(md):
+            count += 1
+    return count
+
+
+# ---------------------------------------------------------------------------
+# CRUD operations
+# ---------------------------------------------------------------------------
+
+def list_profiles() -> List[ProfileInfo]:
+    """Return info for all profiles, including the default."""
+    profiles = []
+    wrapper_dir = _get_wrapper_dir()
+
+    # Default profile
+    default_home = _get_default_hermes_home()
+    if default_home.is_dir():
+        model, provider = _read_config_model(default_home)
+        profiles.append(ProfileInfo(
+            name="default",
+            path=default_home,
+            is_default=True,
+            gateway_running=_check_gateway_running(default_home),
+            model=model,
+            provider=provider,
+            has_env=(default_home / ".env").exists(),
+            skill_count=_count_skills(default_home),
+        ))
+
+    # Named profiles
+    profiles_root = _get_profiles_root()
+    if profiles_root.is_dir():
+        for entry in sorted(profiles_root.iterdir()):
+            if not entry.is_dir():
+                continue
+            name = entry.name
+            if not _PROFILE_ID_RE.match(name):
+                continue
+            model, provider = _read_config_model(entry)
+            alias_path = wrapper_dir / name
+            profiles.append(ProfileInfo(
+                name=name,
+                path=entry,
+                is_default=False,
+                gateway_running=_check_gateway_running(entry),
+                model=model,
+                provider=provider,
+                has_env=(entry / ".env").exists(),
+                skill_count=_count_skills(entry),
+                alias_path=alias_path if alias_path.exists() else None,
+            ))
+
+    return profiles
+
+
+def create_profile(
+    name: str,
+    clone_from: Optional[str] = None,
+    clone_all: bool = False,
+    clone_config: bool = False,
+    no_alias: bool = False,
+) -> Path:
+    """Create a new profile directory.
+
+    Parameters
+    ----------
+    name:
+        Profile identifier (lowercase, alphanumeric, hyphens, underscores).
+    clone_from:
+        Source profile to clone from. If ``None`` and clone_config/clone_all
+        is True, defaults to the currently active profile.
+    clone_all:
+        If True, do a full copytree of the source (all state).
+    clone_config:
+        If True, copy only config files (config.yaml, .env, SOUL.md).
+    no_alias:
+        If True, skip wrapper script creation.
+
+    Returns
+    -------
+    Path
+        The newly created profile directory.
+    """
+    validate_profile_name(name)
+
+    if name == "default":
+        raise ValueError(
+            "Cannot create a profile named 'default' — it is the built-in profile (~/.hermes)."
+        )
+
+    profile_dir = get_profile_dir(name)
+    if profile_dir.exists():
+        raise FileExistsError(f"Profile '{name}' already exists at {profile_dir}")
+
+    # Resolve clone source
+    source_dir = None
+    if clone_from is not None or clone_all or clone_config:
+        if clone_from is None:
+            # Default: clone from active profile
+            from hermes_constants import get_hermes_home
+            source_dir = get_hermes_home()
+        else:
+            validate_profile_name(clone_from)
+            source_dir = get_profile_dir(clone_from)
+        if not source_dir.is_dir():
+            raise FileNotFoundError(
+                f"Source profile '{clone_from or 'active'}' does not exist at {source_dir}"
+            )
+
+    if clone_all and source_dir:
+        # Full copy of source profile
+        shutil.copytree(source_dir, profile_dir)
+        # Strip runtime files
+        for stale in _CLONE_ALL_STRIP:
+            (profile_dir / stale).unlink(missing_ok=True)
+    else:
+        # Bootstrap directory structure
+        profile_dir.mkdir(parents=True, exist_ok=True)
+        for subdir in _PROFILE_DIRS:
+            (profile_dir / subdir).mkdir(parents=True, exist_ok=True)
+
+        # Clone config files from source
+        if source_dir is not None:
+            for filename in _CLONE_CONFIG_FILES:
+                src = source_dir / filename
+                if src.exists():
+                    shutil.copy2(src, profile_dir / filename)
+
+    return profile_dir
+
+
+def seed_profile_skills(profile_dir: Path, quiet: bool = False) -> Optional[dict]:
+    """Seed bundled skills into a profile via subprocess.
+
+    Uses subprocess because sync_skills() caches HERMES_HOME at module level.
+    Returns the sync result dict, or None on failure.
+    """
+    project_root = Path(__file__).parent.parent.resolve()
+    try:
+        result = subprocess.run(
+            [sys.executable, "-c",
+             "import json; from tools.skills_sync import sync_skills; "
+             "r = sync_skills(quiet=True); print(json.dumps(r))"],
+            env={**os.environ, "HERMES_HOME": str(profile_dir)},
+            cwd=str(project_root),
+            capture_output=True, text=True, timeout=60,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return json.loads(result.stdout.strip())
+        if not quiet:
+            print(f"⚠ Skill seeding returned exit code {result.returncode}")
+            if result.stderr.strip():
+                print(f"  {result.stderr.strip()[:200]}")
+        return None
+    except subprocess.TimeoutExpired:
+        if not quiet:
+            print("⚠ Skill seeding timed out (60s)")
+        return None
+    except Exception as e:
+        if not quiet:
+            print(f"⚠ Skill seeding failed: {e}")
+        return None
+
+
+def delete_profile(name: str, yes: bool = False) -> Path:
+    """Delete a profile, its wrapper script, and its gateway service.
+
+    Stops the gateway if running. Disables systemd/launchd service first
+    to prevent auto-restart.
+
+    Returns the path that was removed.
+    """
+    validate_profile_name(name)
+
+    if name == "default":
+        raise ValueError(
+            "Cannot delete the default profile (~/.hermes).\n"
+            "To remove everything, use: hermes uninstall"
+        )
+
+    profile_dir = get_profile_dir(name)
+    if not profile_dir.is_dir():
+        raise FileNotFoundError(f"Profile '{name}' does not exist.")
+
+    # Show what will be deleted
+    model, provider = _read_config_model(profile_dir)
+    gw_running = _check_gateway_running(profile_dir)
+    skill_count = _count_skills(profile_dir)
+
+    print(f"\nProfile: {name}")
+    print(f"Path:    {profile_dir}")
+    if model:
+        print(f"Model:   {model}" + (f" ({provider})" if provider else ""))
+    if skill_count:
+        print(f"Skills:  {skill_count}")
+
+    items = [
+        "All config, API keys, memories, sessions, skills, cron jobs",
+    ]
+
+    # Check for service
+    from hermes_cli.gateway import _profile_suffix, get_service_name
+    wrapper_path = _get_wrapper_dir() / name
+    has_wrapper = wrapper_path.exists()
+    if has_wrapper:
+        items.append(f"Command alias ({wrapper_path})")
+
+    print(f"\nThis will permanently delete:")
+    for item in items:
+        print(f"  • {item}")
+    if gw_running:
+        print(f"  ⚠ Gateway is running — it will be stopped.")
+
+    # Confirmation
+    if not yes:
+        print()
+        try:
+            confirm = input(f"Type '{name}' to confirm: ").strip()
+        except (KeyboardInterrupt, EOFError):
+            print("\nCancelled.")
+            return profile_dir
+        if confirm != name:
+            print("Cancelled.")
+            return profile_dir
+
+    # 1. Disable service (prevents auto-restart)
+    _cleanup_gateway_service(name, profile_dir)
+
+    # 2. Stop running gateway
+    if gw_running:
+        _stop_gateway_process(profile_dir)
+
+    # 3. Remove wrapper script
+    if has_wrapper:
+        if remove_wrapper_script(name):
+            print(f"✓ Removed {wrapper_path}")
+
+    # 4. Remove profile directory
+    try:
+        shutil.rmtree(profile_dir)
+        print(f"✓ Removed {profile_dir}")
+    except Exception as e:
+        print(f"⚠ Could not remove {profile_dir}: {e}")
+
+    # 5. Clear active_profile if it pointed to this profile
+    try:
+        active = get_active_profile()
+        if active == name:
+            set_active_profile("default")
+            print("✓ Active profile reset to default")
+    except Exception:
+        pass
+
+    print(f"\nProfile '{name}' deleted.")
+    return profile_dir
+
+
+def _cleanup_gateway_service(name: str, profile_dir: Path) -> None:
+    """Disable and remove systemd/launchd service for a profile."""
+    import platform as _platform
+
+    # Derive service name for this profile
+    # Temporarily set HERMES_HOME so _profile_suffix resolves correctly
+    old_home = os.environ.get("HERMES_HOME")
+    try:
+        os.environ["HERMES_HOME"] = str(profile_dir)
+        from hermes_cli.gateway import get_service_name, get_launchd_plist_path
+
+        if _platform.system() == "Linux":
+            svc_name = get_service_name()
+            svc_file = Path.home() / ".config" / "systemd" / "user" / f"{svc_name}.service"
+            if svc_file.exists():
+                subprocess.run(
+                    ["systemctl", "--user", "disable", svc_name],
+                    capture_output=True, check=False, timeout=10,
+                )
+                subprocess.run(
+                    ["systemctl", "--user", "stop", svc_name],
+                    capture_output=True, check=False, timeout=10,
+                )
+                svc_file.unlink(missing_ok=True)
+                subprocess.run(
+                    ["systemctl", "--user", "daemon-reload"],
+                    capture_output=True, check=False, timeout=10,
+                )
+                print(f"✓ Service {svc_name} removed")
+
+        elif _platform.system() == "Darwin":
+            plist_path = get_launchd_plist_path()
+            if plist_path.exists():
+                subprocess.run(
+                    ["launchctl", "unload", str(plist_path)],
+                    capture_output=True, check=False, timeout=10,
+                )
+                plist_path.unlink(missing_ok=True)
+                print(f"✓ Launchd service removed")
+    except Exception as e:
+        print(f"⚠ Service cleanup: {e}")
+    finally:
+        if old_home is not None:
+            os.environ["HERMES_HOME"] = old_home
+        elif "HERMES_HOME" in os.environ:
+            del os.environ["HERMES_HOME"]
+
+
+def _stop_gateway_process(profile_dir: Path) -> None:
+    """Stop a running gateway process via its PID file."""
+    import signal as _signal
+    import time as _time
+
+    pid_file = profile_dir / "gateway.pid"
+    if not pid_file.exists():
+        return
+
+    try:
+        raw = pid_file.read_text().strip()
+        data = json.loads(raw) if raw.startswith("{") else {"pid": int(raw)}
+        pid = int(data["pid"])
+        os.kill(pid, _signal.SIGTERM)
+        # Wait up to 10s for graceful shutdown
+        for _ in range(20):
+            _time.sleep(0.5)
+            try:
+                os.kill(pid, 0)
+            except ProcessLookupError:
+                print(f"✓ Gateway stopped (PID {pid})")
+                return
+        # Force kill
+        try:
+            os.kill(pid, _signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        print(f"✓ Gateway force-stopped (PID {pid})")
+    except (ProcessLookupError, PermissionError):
+        print("✓ Gateway already stopped")
+    except Exception as e:
+        print(f"⚠ Could not stop gateway: {e}")
+
+
+# ---------------------------------------------------------------------------
+# Active profile (sticky default)
+# ---------------------------------------------------------------------------
+
+def get_active_profile() -> str:
+    """Read the sticky active profile name.
+
+    Returns ``"default"`` if no active_profile file exists or it's empty.
+    """
+    path = _get_active_profile_path()
+    try:
+        name = path.read_text().strip()
+        if not name:
+            return "default"
+        return name
+    except (FileNotFoundError, UnicodeDecodeError, OSError):
+        return "default"
+
+
+def set_active_profile(name: str) -> None:
+    """Set the sticky active profile.
+
+    Writes to ``~/.hermes/active_profile``. Use ``"default"`` to clear.
+    """
+    validate_profile_name(name)
+    if name != "default" and not profile_exists(name):
+        raise FileNotFoundError(
+            f"Profile '{name}' does not exist. "
+            f"Create it with: hermes profile create {name}"
+        )
+
+    path = _get_active_profile_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if name == "default":
+        # Remove the file to indicate default
+        path.unlink(missing_ok=True)
+    else:
+        # Atomic write
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(name + "\n")
+        tmp.replace(path)
+
+
+def get_active_profile_name() -> str:
+    """Infer the current profile name from HERMES_HOME.
+
+    Returns ``"default"`` if HERMES_HOME is not set or points to ``~/.hermes``.
+    Returns the profile name if HERMES_HOME points into ``~/.hermes/profiles/<name>``.
+    Returns ``"custom"`` if HERMES_HOME is set to an unrecognized path.
+    """
+    from hermes_constants import get_hermes_home
+    hermes_home = get_hermes_home()
+    resolved = hermes_home.resolve()
+
+    default_resolved = _get_default_hermes_home().resolve()
+    if resolved == default_resolved:
+        return "default"
+
+    profiles_root = _get_profiles_root().resolve()
+    try:
+        rel = resolved.relative_to(profiles_root)
+        parts = rel.parts
+        if len(parts) == 1 and _PROFILE_ID_RE.match(parts[0]):
+            return parts[0]
+    except ValueError:
+        pass
+
+    return "custom"
+
+
+# ---------------------------------------------------------------------------
+# Export / Import
+# ---------------------------------------------------------------------------
+
+def export_profile(name: str, output_path: str) -> Path:
+    """Export a profile to a tar.gz archive.
+
+    Returns the output file path.
+    """
+    validate_profile_name(name)
+    profile_dir = get_profile_dir(name)
+    if not profile_dir.is_dir():
+        raise FileNotFoundError(f"Profile '{name}' does not exist.")
+
+    output = Path(output_path)
+    # shutil.make_archive wants the base name without extension
+    base = str(output).removesuffix(".tar.gz").removesuffix(".tgz")
+    result = shutil.make_archive(base, "gztar", str(profile_dir.parent), name)
+    return Path(result)
+
+
+def import_profile(archive_path: str, name: Optional[str] = None) -> Path:
+    """Import a profile from a tar.gz archive.
+
+    If *name* is not given, infers it from the archive's top-level directory.
+    Returns the imported profile directory.
+    """
+    import tarfile
+
+    archive = Path(archive_path)
+    if not archive.exists():
+        raise FileNotFoundError(f"Archive not found: {archive}")
+
+    # Peek at the archive to find the top-level directory name
+    with tarfile.open(archive, "r:gz") as tf:
+        top_dirs = {m.name.split("/")[0] for m in tf.getmembers() if "/" in m.name}
+        if not top_dirs:
+            top_dirs = {m.name for m in tf.getmembers() if m.isdir()}
+
+    inferred_name = name or (top_dirs.pop() if len(top_dirs) == 1 else None)
+    if not inferred_name:
+        raise ValueError(
+            "Cannot determine profile name from archive. "
+            "Specify it explicitly: hermes profile import <archive> --name <name>"
+        )
+
+    validate_profile_name(inferred_name)
+    profile_dir = get_profile_dir(inferred_name)
+    if profile_dir.exists():
+        raise FileExistsError(f"Profile '{inferred_name}' already exists at {profile_dir}")
+
+    profiles_root = _get_profiles_root()
+    profiles_root.mkdir(parents=True, exist_ok=True)
+
+    shutil.unpack_archive(str(archive), str(profiles_root))
+
+    # If the archive extracted under a different name, rename
+    extracted = profiles_root / (top_dirs.pop() if top_dirs else inferred_name)
+    if extracted != profile_dir and extracted.exists():
+        extracted.rename(profile_dir)
+
+    return profile_dir
+
+
+# ---------------------------------------------------------------------------
+# Rename
+# ---------------------------------------------------------------------------
+
+def rename_profile(old_name: str, new_name: str) -> Path:
+    """Rename a profile: directory, wrapper script, service, active_profile.
+
+    Returns the new profile directory.
+    """
+    validate_profile_name(old_name)
+    validate_profile_name(new_name)
+
+    if old_name == "default":
+        raise ValueError("Cannot rename the default profile.")
+    if new_name == "default":
+        raise ValueError("Cannot rename to 'default' — it is reserved.")
+
+    old_dir = get_profile_dir(old_name)
+    new_dir = get_profile_dir(new_name)
+
+    if not old_dir.is_dir():
+        raise FileNotFoundError(f"Profile '{old_name}' does not exist.")
+    if new_dir.exists():
+        raise FileExistsError(f"Profile '{new_name}' already exists.")
+
+    # 1. Stop gateway if running
+    if _check_gateway_running(old_dir):
+        _cleanup_gateway_service(old_name, old_dir)
+        _stop_gateway_process(old_dir)
+
+    # 2. Rename directory
+    old_dir.rename(new_dir)
+    print(f"✓ Renamed {old_dir.name} → {new_dir.name}")
+
+    # 3. Update wrapper script
+    remove_wrapper_script(old_name)
+    collision = check_alias_collision(new_name)
+    if not collision:
+        create_wrapper_script(new_name)
+        print(f"✓ Alias updated: {new_name}")
+    else:
+        print(f"⚠ Cannot create alias '{new_name}' — {collision}")
+
+    # 4. Update active_profile if it pointed to old name
+    try:
+        if get_active_profile() == old_name:
+            set_active_profile(new_name)
+            print(f"✓ Active profile updated: {new_name}")
+    except Exception:
+        pass
+
+    return new_dir
+
+
+# ---------------------------------------------------------------------------
+# Tab completion
+# ---------------------------------------------------------------------------
+
+def generate_bash_completion() -> str:
+    """Generate a bash completion script for hermes profile names."""
+    return '''# Hermes Agent profile completion
+# Add to ~/.bashrc: eval "$(hermes completion bash)"
+
+_hermes_profiles() {
+    local profiles_dir="$HOME/.hermes/profiles"
+    local profiles="default"
+    if [ -d "$profiles_dir" ]; then
+        profiles="$profiles $(ls "$profiles_dir" 2>/dev/null)"
+    fi
+    echo "$profiles"
+}
+
+_hermes_completion() {
+    local cur prev
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+    # Complete profile names after -p / --profile
+    if [[ "$prev" == "-p" || "$prev" == "--profile" ]]; then
+        COMPREPLY=($(compgen -W "$(_hermes_profiles)" -- "$cur"))
+        return
+    fi
+
+    # Complete profile subcommands
+    if [[ "${COMP_WORDS[1]}" == "profile" ]]; then
+        case "$prev" in
+            profile)
+                COMPREPLY=($(compgen -W "list use create delete show alias rename export import" -- "$cur"))
+                return
+                ;;
+            use|delete|show|alias|rename|export)
+                COMPREPLY=($(compgen -W "$(_hermes_profiles)" -- "$cur"))
+                return
+                ;;
+        esac
+    fi
+
+    # Top-level subcommands
+    if [[ "$COMP_CWORD" == 1 ]]; then
+        local commands="chat model gateway setup status cron doctor config skills tools mcp sessions profile update version"
+        COMPREPLY=($(compgen -W "$commands" -- "$cur"))
+    fi
+}
+
+complete -F _hermes_completion hermes
+'''
+
+
+def generate_zsh_completion() -> str:
+    """Generate a zsh completion script for hermes profile names."""
+    return '''#compdef hermes
+# Hermes Agent profile completion
+# Add to ~/.zshrc: eval "$(hermes completion zsh)"
+
+_hermes() {
+    local -a profiles
+    profiles=(default)
+    if [[ -d "$HOME/.hermes/profiles" ]]; then
+        profiles+=("${(@f)$(ls $HOME/.hermes/profiles 2>/dev/null)}")
+    fi
+
+    _arguments \\
+        '-p[Profile name]:profile:($profiles)' \\
+        '--profile[Profile name]:profile:($profiles)' \\
+        '1:command:(chat model gateway setup status cron doctor config skills tools mcp sessions profile update version)' \\
+        '*::arg:->args'
+
+    case $words[1] in
+        profile)
+            _arguments '1:action:(list use create delete show alias rename export import)' \\
+                        '2:profile:($profiles)'
+            ;;
+    esac
+}
+
+_hermes "$@"
+'''
+
+
+# ---------------------------------------------------------------------------
+# Profile env resolution (called from _apply_profile_override)
+# ---------------------------------------------------------------------------
+
+def resolve_profile_env(profile_name: str) -> str:
+    """Resolve a profile name to a HERMES_HOME path string.
+
+    Called early in the CLI entry point, before any hermes modules
+    are imported, to set the HERMES_HOME environment variable.
+    """
+    validate_profile_name(profile_name)
+    profile_dir = get_profile_dir(profile_name)
+
+    if profile_name != "default" and not profile_dir.is_dir():
+        raise FileNotFoundError(
+            f"Profile '{profile_name}' does not exist. "
+            f"Create it with: hermes profile create {profile_name}"
+        )
+
+    return str(profile_dir)

hermes_cli/setup.py

@@ -289,6 +289,7 @@ from hermes_cli.config import (
     get_env_value,
     ensure_hermes_home,
 )
+# display_hermes_home imported lazily at call sites (stale-module safety during hermes update)
 
 from hermes_cli.colors import Colors, color
 
@@ -683,7 +684,8 @@ def _print_setup_summary(config: dict, hermes_home):
         print_warning(
             "Some tools are disabled. Run 'hermes setup tools' to configure them,"
         )
-        print_warning("or edit ~/.hermes/.env directly to add the missing API keys.")
+        from hermes_constants import display_hermes_home as _dhh
+        print_warning(f"or edit {_dhh()}/.env directly to add the missing API keys.")
         print()
 
     # Done banner
@@ -706,7 +708,8 @@ def _print_setup_summary(config: dict, hermes_home):
     print()
 
     # Show file locations prominently
-    print(color("📁 All your files are in ~/.hermes/:", Colors.CYAN, Colors.BOLD))
+    from hermes_constants import display_hermes_home as _dhh
+    print(color(f"📁 All your files are in {_dhh()}/:", Colors.CYAN, Colors.BOLD))
     print()
     print(f"   {color('Settings:', Colors.YELLOW)}  {get_config_path()}")
     print(f"   {color('API Keys:', Colors.YELLOW)}  {get_env_path()}")
@@ -2837,7 +2840,8 @@ def setup_gateway(config: dict):
         save_env_value("WEBHOOK_ENABLED", "true")
         print()
         print_success("Webhooks enabled! Next steps:")
-        print_info("   1. Define webhook routes in ~/.hermes/config.yaml")
+        from hermes_constants import display_hermes_home as _dhh
+        print_info(f"   1. Define webhook routes in {_dhh()}/config.yaml")
         print_info("   2. Point your service (GitHub, GitLab, etc.) at:")
         print_info("      http://your-server:8644/webhooks/<route-name>")
         print()

hermes_cli/skills_hub.py

@@ -21,6 +21,7 @@ from rich.table import Table
 
 # Lazy imports to avoid circular dependencies and slow startup.
 # tools.skills_hub and tools.skills_guard are imported inside functions.
+from hermes_constants import display_hermes_home
 
 _console = Console()
 
@@ -388,7 +389,7 @@ def do_install(identifier: str, category: str = "", force: bool = False,
                 "[bold bright_cyan]This is an official optional skill maintained by Nous Research.[/]\n\n"
                 "It ships with hermes-agent but is not activated by default.\n"
                 "Installing will copy it to your skills directory where the agent can use it.\n\n"
-                f"Files will be at: [cyan]~/.hermes/skills/{category + '/' if category else ''}{bundle.name}/[/]",
+                f"Files will be at: [cyan]{display_hermes_home()}/skills/{category + '/' if category else ''}{bundle.name}/[/]",
                 title="Official Skill",
                 border_style="bright_cyan",
             ))
@@ -398,7 +399,7 @@ def do_install(identifier: str, category: str = "", force: bool = False,
                 "External skills can contain instructions that influence agent behavior,\n"
                 "shell commands, and scripts. Even after automated scanning, you should\n"
                 "review the installed files before use.\n\n"
-                f"Files will be at: [cyan]~/.hermes/skills/{category + '/' if category else ''}{bundle.name}/[/]",
+                f"Files will be at: [cyan]{display_hermes_home()}/skills/{category + '/' if category else ''}{bundle.name}/[/]",
                 title="Disclaimer",
                 border_style="yellow",
             ))
@@ -744,7 +745,7 @@ def do_publish(skill_path: str, target: str = "github", repo: str = "",
         auth = GitHubAuth()
         if not auth.is_authenticated():
             c.print("[bold red]Error:[/] GitHub authentication required.\n"
-                    "Set GITHUB_TOKEN in ~/.hermes/.env or run 'gh auth login'.\n")
+                    f"Set GITHUB_TOKEN in {display_hermes_home()}/.env or run 'gh auth login'.\n")
             return
 
         c.print(f"[bold]Publishing '{name}' to {repo}...[/]")

hermes_cli/tools_config.py

@@ -326,7 +326,8 @@ def _run_post_setup(post_setup_key: str):
             if result.returncode == 0:
                 _print_success("    Node.js dependencies installed")
             else:
-                _print_warning("    npm install failed - run manually: cd ~/.hermes/hermes-agent && npm install")
+                from hermes_constants import display_hermes_home
+                _print_warning(f"    npm install failed - run manually: cd {display_hermes_home()}/hermes-agent && npm install")
         elif not node_modules.exists():
             _print_warning("    Node.js not found - browser tools require: npm install (in hermes-agent directory)")
 
@@ -1264,7 +1265,8 @@ def tools_command(args=None, first_install: bool = False, config: dict = None):
         platform_choices[idx] = f"Configure {pinfo['label']}  ({new_count}/{total} enabled)"
 
     print()
-    print(color("  Tool configuration saved to ~/.hermes/config.yaml", Colors.DIM))
+    from hermes_constants import display_hermes_home
+    print(color(f"  Tool configuration saved to {display_hermes_home()}/config.yaml", Colors.DIM))
     print(color("  Changes take effect on next 'hermes' or gateway restart.", Colors.DIM))
     print()
 

hermes_cli/webhook.py

@@ -18,6 +18,8 @@ import time
 from pathlib import Path
 from typing import Dict, Optional
 
+from hermes_constants import display_hermes_home
+
 
 _SUBSCRIPTIONS_FILENAME = "webhook_subscriptions.json"
 
@@ -76,13 +78,15 @@ def _get_webhook_base_url() -> str:
     return f"http://{display_host}:{port}"
 
 
-_SETUP_HINT = """
+def _setup_hint() -> str:
+    _dhh = display_hermes_home()
+    return f"""
   Webhook platform is not enabled. To set it up:
 
   1. Run the gateway setup wizard:
      hermes gateway setup
 
-  2. Or manually add to ~/.hermes/config.yaml:
+  2. Or manually add to {_dhh}/config.yaml:
      platforms:
        webhook:
          enabled: true
@@ -91,7 +95,7 @@ _SETUP_HINT = """
            port: 8644
            secret: "your-global-hmac-secret"
 
-  3. Or set environment variables in ~/.hermes/.env:
+  3. Or set environment variables in {_dhh}/.env:
      WEBHOOK_ENABLED=true
      WEBHOOK_PORT=8644
      WEBHOOK_SECRET=your-global-secret
@@ -104,7 +108,7 @@ def _require_webhook_enabled() -> bool:
     """Check webhook is enabled. Print setup guide and return False if not."""
     if _is_webhook_enabled():
         return True
-    print(_SETUP_HINT)
+    print(_setup_hint())
     return False
 
 

hermes_constants.py

@@ -38,6 +38,26 @@ def get_hermes_dir(new_subpath: str, old_name: str) -> Path:
     return home / new_subpath
 
 
+def display_hermes_home() -> str:
+    """Return a user-friendly display string for the current HERMES_HOME.
+
+    Uses ``~/`` shorthand for readability::
+
+        default:  ``~/.hermes``
+        profile:  ``~/.hermes/profiles/coder``
+        custom:   ``/opt/hermes-custom``
+
+    Use this in **user-facing** print/log messages instead of hardcoding
+    ``~/.hermes``.  For code that needs a real ``Path``, use
+    :func:`get_hermes_home` instead.
+    """
+    home = get_hermes_home()
+    try:
+        return "~/" + str(home.relative_to(Path.home()))
+    except ValueError:
+        return str(home)
+
+
 VALID_REASONING_EFFORTS = ("xhigh", "high", "medium", "low", "minimal")
 
 

optional-skills/communication/DESCRIPTION.md

@@ -0,0 +1 @@
+Communication and decision-making frameworks — structured response formats for proposals, trade-off analysis, and stakeholder-ready recommendations.

optional-skills/communication/one-three-one-rule/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: one-three-one-rule
+description: >
+  Structured decision-making framework for technical proposals and trade-off analysis.
+  When the user faces a choice between multiple approaches (architecture decisions,
+  tool selection, refactoring strategies, migration paths), this skill produces a
+  1-3-1 format: one clear problem statement, three distinct options with pros/cons,
+  and one concrete recommendation with definition of done and implementation plan.
+  Use when the user asks for a "1-3-1", says "give me options", or needs help
+  choosing between competing approaches.
+version: 1.0.0
+author: Willard Moore
+license: MIT
+category: communication
+metadata:
+  hermes:
+    tags: [communication, decision-making, proposals, trade-offs]
+---
+
+# 1-3-1 Communication Rule
+
+Structured decision-making format for when a task has multiple viable approaches and the user needs a clear recommendation. Produces a concise problem framing, three options with trade-offs, and an actionable plan for the recommended path.
+
+## When to Use
+
+- The user explicitly asks for a "1-3-1" response.
+- The user says "give me options" or "what are my choices" for a technical decision.
+- A task has multiple viable approaches with meaningful trade-offs (architecture, tooling, migration strategy).
+- The user needs a proposal they can forward to a team or stakeholder.
+
+Do NOT use for simple questions with one obvious answer, debugging sessions, or tasks where the user has already decided on an approach.
+
+## Procedure
+
+1. **Problem** (one sentence)
+   - State the core decision or desired outcome in a single concise sentence.
+   - Focus on the *what*, not the *how* — no implementation details, tool names, or specific technologies.
+   - Keep it tight. If you need "and", you're describing two problems.
+
+2. **Options** (exactly three)
+   - Present three distinct, viable approaches labeled A, B, C.
+   - Each option gets a brief description, pros, and cons.
+   - Options should represent genuinely different strategies, not minor variations of the same approach.
+
+3. **Recommendation** (one option)
+   - State which option you recommend and why, based on the user's context and priorities.
+   - Be direct — this is your professional judgment, not a hedge.
+
+4. **Definition of Done**
+   - List the specific success criteria for the recommended option.
+   - These are concrete, verifiable outcomes — not vague aspirations.
+   - If the user picks a different option, revise this section to match.
+
+5. **Implementation Plan**
+   - Concrete steps to execute the recommended option.
+   - Include specific commands, tools, or actions where applicable.
+   - If the user picks a different option, revise this section to match.
+
+## Verification
+
+- Response has exactly one Problem sentence.
+- Response has exactly three Options (A, B, C) with pros and cons for each.
+- Response has a single Recommendation that picks one option with reasoning.
+- Definition of Done and Implementation Plan align with the recommended option.
+- If the user selects a different option, Recommendation, DoD, and Implementation Plan update accordingly.
+
+## Example
+
+User: "Give me a 1-3-1 for adding retry logic to our API client."
+
+Agent:
+
+**Problem:** API calls to external services fail intermittently under load and need graceful retry handling.
+
+**Options:**
+
+- **Option A: Exponential backoff with jitter in a shared utility.**
+  Pros: Simple, well-understood pattern; single implementation shared across all callers.
+  Cons: No circuit-breaking; callers still block during retries.
+
+- **Option B: Retry library (tenacity) as a decorator on each endpoint call.**
+  Pros: Configurable per-endpoint; built-in support for circuit breakers and rate limits.
+  Cons: Adds a dependency; decorator pattern can obscure control flow.
+
+- **Option C: Queue-based async retry with dead letter handling.**
+  Pros: Non-blocking; failed calls are tracked and replayable; scales well.
+  Cons: Significant complexity increase; requires a queue backend; overkill for low-volume services.
+
+**Recommendation:** Option A. The call volume doesn't justify queue infrastructure, and a shared utility with exponential backoff + jitter covers the failure mode cleanly without new dependencies.
+
+**Definition of Done:**
+- `api_retry()` utility handles transient HTTP errors (429, 502, 503, 504).
+- Retries up to 3 times with exponential backoff and jitter.
+- All external API calls route through the retry utility.
+- Logs each retry attempt with endpoint and attempt number.
+- Tests cover retry exhaustion, immediate success, and transient-then-success scenarios.
+
+**Implementation Plan:**
+1. Create `utils/api_retry.py` with configurable max retries, base delay, and retryable status codes.
+2. Add jitter using `random.uniform(0, base_delay)` to prevent thundering herd.
+3. Wrap existing API calls in `api_client.py` with the retry utility.
+4. Add unit tests mocking HTTP responses for each retry scenario.
+5. Verify under load with a simple stress test against a flaky endpoint mock.

optional-skills/productivity/siyuan/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: siyuan
+description: SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl.
+version: 1.0.0
+author: FEUAZUR
+license: MIT
+metadata:
+  hermes:
+    tags: [SiYuan, Notes, Knowledge Base, PKM, API]
+    related_skills: [obsidian, notion]
+    homepage: https://github.com/siyuan-note/siyuan
+prerequisites:
+  env_vars: [SIYUAN_TOKEN]
+  commands: [curl, jq]
+required_environment_variables:
+  - name: SIYUAN_TOKEN
+    prompt: SiYuan API token
+    help: "Settings > About in SiYuan desktop app"
+  - name: SIYUAN_URL
+    prompt: SiYuan instance URL (default http://127.0.0.1:6806)
+    required_for: remote instances
+---
+
+# SiYuan Note API
+
+Use the [SiYuan](https://github.com/siyuan-note/siyuan) kernel API via curl to search, read, create, update, and delete blocks and documents in a self-hosted knowledge base. No extra tools needed -- just curl and an API token.
+
+## Prerequisites
+
+1. Install and run SiYuan (desktop or Docker)
+2. Get your API token: **Settings > About > API token**
+3. Store it in `~/.hermes/.env`:
+   ```
+   SIYUAN_TOKEN=your_token_here
+   SIYUAN_URL=http://127.0.0.1:6806
+   ```
+   `SIYUAN_URL` defaults to `http://127.0.0.1:6806` if not set.
+
+## API Basics
+
+All SiYuan API calls are **POST with JSON body**. Every request follows this pattern:
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/..." \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"param": "value"}'
+```
+
+Responses are JSON with this structure:
+```json
+{"code": 0, "msg": "", "data": { ... }}
+```
+`code: 0` means success. Any other value is an error -- check `msg` for details.
+
+**ID format:** SiYuan IDs look like `20210808180117-6v0mkxr` (14-digit timestamp + 7 alphanumeric chars).
+
+## Quick Reference
+
+| Operation | Endpoint |
+|-----------|----------|
+| Full-text search | `/api/search/fullTextSearchBlock` |
+| SQL query | `/api/query/sql` |
+| Read block | `/api/block/getBlockKramdown` |
+| Read children | `/api/block/getChildBlocks` |
+| Get path | `/api/filetree/getHPathByID` |
+| Get attributes | `/api/attr/getBlockAttrs` |
+| List notebooks | `/api/notebook/lsNotebooks` |
+| List documents | `/api/filetree/listDocsByPath` |
+| Create notebook | `/api/notebook/createNotebook` |
+| Create document | `/api/filetree/createDocWithMd` |
+| Append block | `/api/block/appendBlock` |
+| Update block | `/api/block/updateBlock` |
+| Rename document | `/api/filetree/renameDocByID` |
+| Set attributes | `/api/attr/setBlockAttrs` |
+| Delete block | `/api/block/deleteBlock` |
+| Delete document | `/api/filetree/removeDocByID` |
+| Export as Markdown | `/api/export/exportMdContent` |
+
+## Common Operations
+
+### Search (Full-Text)
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/search/fullTextSearchBlock" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "meeting notes", "page": 0}' | jq '.data.blocks[:5]'
+```
+
+### Search (SQL)
+
+Query the blocks database directly. Only SELECT statements are safe.
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/query/sql" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"stmt": "SELECT id, content, type, box FROM blocks WHERE content LIKE '\''%keyword%'\'' AND type='\''p'\'' LIMIT 20"}' | jq '.data'
+```
+
+Useful columns: `id`, `parent_id`, `root_id`, `box` (notebook ID), `path`, `content`, `type`, `subtype`, `created`, `updated`.
+
+### Read Block Content
+
+Returns block content in Kramdown (Markdown-like) format.
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getBlockKramdown" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data.kramdown'
+```
+
+### Read Child Blocks
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getChildBlocks" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
+```
+
+### Get Human-Readable Path
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/getHPathByID" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
+```
+
+### Get Block Attributes
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/getBlockAttrs" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
+```
+
+### List Notebooks
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/lsNotebooks" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{}' | jq '.data.notebooks[] | {id, name, closed}'
+```
+
+### List Documents in a Notebook
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/listDocsByPath" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"notebook": "NOTEBOOK_ID", "path": "/"}' | jq '.data.files[] | {id, name}'
+```
+
+### Create a Document
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/createDocWithMd" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "notebook": "NOTEBOOK_ID",
+    "path": "/Meeting Notes/2026-03-22",
+    "markdown": "# Meeting Notes\n\n- Discussed project timeline\n- Assigned tasks"
+  }' | jq '.data'
+```
+
+### Create a Notebook
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/createNotebook" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "My New Notebook"}' | jq '.data.notebook.id'
+```
+
+### Append Block to Document
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/appendBlock" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "parentID": "DOCUMENT_OR_BLOCK_ID",
+    "data": "New paragraph added at the end.",
+    "dataType": "markdown"
+  }' | jq '.data'
+```
+
+Also available: `/api/block/prependBlock` (same params, inserts at the beginning) and `/api/block/insertBlock` (uses `previousID` instead of `parentID` to insert after a specific block).
+
+### Update Block Content
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/updateBlock" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "BLOCK_ID",
+    "data": "Updated content here.",
+    "dataType": "markdown"
+  }' | jq '.data'
+```
+
+### Rename a Document
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/renameDocByID" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "DOCUMENT_ID", "title": "New Title"}'
+```
+
+### Set Block Attributes
+
+Custom attributes must be prefixed with `custom-`:
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/setBlockAttrs" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "BLOCK_ID",
+    "attrs": {
+      "custom-status": "reviewed",
+      "custom-priority": "high"
+    }
+  }'
+```
+
+### Delete a Block
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/deleteBlock" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "BLOCK_ID"}'
+```
+
+To delete a whole document: use `/api/filetree/removeDocByID` with `{"id": "DOC_ID"}`.
+To delete a notebook: use `/api/notebook/removeNotebook` with `{"notebook": "NOTEBOOK_ID"}`.
+
+### Export Document as Markdown
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/export/exportMdContent" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "DOCUMENT_ID"}' | jq -r '.data.content'
+```
+
+## Block Types
+
+Common `type` values in SQL queries:
+
+| Type | Description |
+|------|-------------|
+| `d` | Document (root block) |
+| `p` | Paragraph |
+| `h` | Heading |
+| `l` | List |
+| `i` | List item |
+| `c` | Code block |
+| `m` | Math block |
+| `t` | Table |
+| `b` | Blockquote |
+| `s` | Super block |
+| `html` | HTML block |
+
+## Pitfalls
+
+- **All endpoints are POST** -- even read-only operations. Do not use GET.
+- **SQL safety**: only use SELECT queries. INSERT/UPDATE/DELETE/DROP are dangerous and should never be sent.
+- **ID validation**: IDs match the pattern `YYYYMMDDHHmmss-xxxxxxx`. Reject anything else.
+- **Error responses**: always check `code != 0` in responses before processing `data`.
+- **Large documents**: block content and export results can be very large. Use `LIMIT` in SQL and pipe through `jq` to extract only what you need.
+- **Notebook IDs**: when working with a specific notebook, get its ID first via `lsNotebooks`.
+
+## Alternative: MCP Server
+
+If you prefer a native integration instead of curl, install the SiYuan MCP server:
+
+```yaml
+# In ~/.hermes/config.yaml under mcp_servers:
+mcp_servers:
+  siyuan:
+    command: npx
+    args: ["-y", "@porkll/siyuan-mcp"]
+    env:
+      SIYUAN_TOKEN: "your_token"
+      SIYUAN_URL: "http://127.0.0.1:6806"
+```

optional-skills/research/scrapling/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: scrapling
+description: Web scraping with Scrapling - HTTP fetching, stealth browser automation, Cloudflare bypass, and spider crawling via CLI and Python.
+version: 1.0.0
+author: FEUAZUR
+license: MIT
+metadata:
+  hermes:
+    tags: [Web Scraping, Browser, Cloudflare, Stealth, Crawling, Spider]
+    related_skills: [duckduckgo-search, domain-intel]
+    homepage: https://github.com/D4Vinci/Scrapling
+prerequisites:
+  commands: [scrapling, python]
+---
+
+# Scrapling
+
+[Scrapling](https://github.com/D4Vinci/Scrapling) is a web scraping framework with anti-bot bypass, stealth browser automation, and a spider framework. It provides three fetching strategies (HTTP, dynamic JS, stealth/Cloudflare) and a full CLI.
+
+**This skill is for educational and research purposes only.** Users must comply with local/international data scraping laws and respect website Terms of Service.
+
+## When to Use
+
+- Scraping static HTML pages (faster than browser tools)
+- Scraping JS-rendered pages that need a real browser
+- Bypassing Cloudflare Turnstile or bot detection
+- Crawling multiple pages with a spider
+- When the built-in `web_extract` tool does not return the data you need
+
+## Installation
+
+```bash
+pip install "scrapling[all]"
+scrapling install
+```
+
+Minimal install (HTTP only, no browser):
+```bash
+pip install scrapling
+```
+
+With browser automation only:
+```bash
+pip install "scrapling[fetchers]"
+scrapling install
+```
+
+## Quick Reference
+
+| Approach | Class | Use When |
+|----------|-------|----------|
+| HTTP | `Fetcher` / `FetcherSession` | Static pages, APIs, fast bulk requests |
+| Dynamic | `DynamicFetcher` / `DynamicSession` | JS-rendered content, SPAs |
+| Stealth | `StealthyFetcher` / `StealthySession` | Cloudflare, anti-bot protected sites |
+| Spider | `Spider` | Multi-page crawling with link following |
+
+## CLI Usage
+
+### Extract Static Page
+
+```bash
+scrapling extract get 'https://example.com' output.md
+```
+
+With CSS selector and browser impersonation:
+
+```bash
+scrapling extract get 'https://example.com' output.md \
+  --css-selector '.content' \
+  --impersonate 'chrome'
+```
+
+### Extract JS-Rendered Page
+
+```bash
+scrapling extract fetch 'https://example.com' output.md \
+  --css-selector '.dynamic-content' \
+  --disable-resources \
+  --network-idle
+```
+
+### Extract Cloudflare-Protected Page
+
+```bash
+scrapling extract stealthy-fetch 'https://protected-site.com' output.html \
+  --solve-cloudflare \
+  --block-webrtc \
+  --hide-canvas
+```
+
+### POST Request
+
+```bash
+scrapling extract post 'https://example.com/api' output.json \
+  --json '{"query": "search term"}'
+```
+
+### Output Formats
+
+The output format is determined by the file extension:
+- `.html` -- raw HTML
+- `.md` -- converted to Markdown
+- `.txt` -- plain text
+- `.json` / `.jsonl` -- JSON
+
+## Python: HTTP Scraping
+
+### Single Request
+
+```python
+from scrapling.fetchers import Fetcher
+
+page = Fetcher.get('https://quotes.toscrape.com/')
+quotes = page.css('.quote .text::text').getall()
+for q in quotes:
+    print(q)
+```
+
+### Session (Persistent Cookies)
+
+```python
+from scrapling.fetchers import FetcherSession
+
+with FetcherSession(impersonate='chrome') as session:
+    page = session.get('https://example.com/', stealthy_headers=True)
+    links = page.css('a::attr(href)').getall()
+    for link in links[:5]:
+        sub = session.get(link)
+        print(sub.css('h1::text').get())
+```
+
+### POST / PUT / DELETE
+
+```python
+page = Fetcher.post('https://api.example.com/data', json={"key": "value"})
+page = Fetcher.put('https://api.example.com/item/1', data={"name": "updated"})
+page = Fetcher.delete('https://api.example.com/item/1')
+```
+
+### With Proxy
+
+```python
+page = Fetcher.get('https://example.com', proxy='http://user:pass@proxy:8080')
+```
+
+## Python: Dynamic Pages (JS-Rendered)
+
+For pages that require JavaScript execution (SPAs, lazy-loaded content):
+
+```python
+from scrapling.fetchers import DynamicFetcher
+
+page = DynamicFetcher.fetch('https://example.com', headless=True)
+data = page.css('.js-loaded-content::text').getall()
+```
+
+### Wait for Specific Element
+
+```python
+page = DynamicFetcher.fetch(
+    'https://example.com',
+    wait_selector=('.results', 'visible'),
+    network_idle=True,
+)
+```
+
+### Disable Resources for Speed
+
+Blocks fonts, images, media, stylesheets (~25% faster):
+
+```python
+from scrapling.fetchers import DynamicSession
+
+with DynamicSession(headless=True, disable_resources=True, network_idle=True) as session:
+    page = session.fetch('https://example.com')
+    items = page.css('.item::text').getall()
+```
+
+### Custom Page Automation
+
+```python
+from playwright.sync_api import Page
+from scrapling.fetchers import DynamicFetcher
+
+def scroll_and_click(page: Page):
+    page.mouse.wheel(0, 3000)
+    page.wait_for_timeout(1000)
+    page.click('button.load-more')
+    page.wait_for_selector('.extra-results')
+
+page = DynamicFetcher.fetch('https://example.com', page_action=scroll_and_click)
+results = page.css('.extra-results .item::text').getall()
+```
+
+## Python: Stealth Mode (Anti-Bot Bypass)
+
+For Cloudflare-protected or heavily fingerprinted sites:
+
+```python
+from scrapling.fetchers import StealthyFetcher
+
+page = StealthyFetcher.fetch(
+    'https://protected-site.com',
+    headless=True,
+    solve_cloudflare=True,
+    block_webrtc=True,
+    hide_canvas=True,
+)
+content = page.css('.protected-content::text').getall()
+```
+
+### Stealth Session
+
+```python
+from scrapling.fetchers import StealthySession
+
+with StealthySession(headless=True, solve_cloudflare=True) as session:
+    page1 = session.fetch('https://protected-site.com/page1')
+    page2 = session.fetch('https://protected-site.com/page2')
+```
+
+## Element Selection
+
+All fetchers return a `Selector` object with these methods:
+
+### CSS Selectors
+
+```python
+page.css('h1::text').get()              # First h1 text
+page.css('a::attr(href)').getall()      # All link hrefs
+page.css('.quote .text::text').getall() # Nested selection
+```
+
+### XPath
+
+```python
+page.xpath('//div[@class="content"]/text()').getall()
+page.xpath('//a/@href').getall()
+```
+
+### Find Methods
+
+```python
+page.find_all('div', class_='quote')       # By tag + attribute
+page.find_by_text('Read more', tag='a')    # By text content
+page.find_by_regex(r'\$\d+\.\d{2}')       # By regex pattern
+```
+
+### Similar Elements
+
+Find elements with similar structure (useful for product listings, etc.):
+
+```python
+first_product = page.css('.product')[0]
+all_similar = first_product.find_similar()
+```
+
+### Navigation
+
+```python
+el = page.css('.target')[0]
+el.parent                # Parent element
+el.children              # Child elements
+el.next_sibling          # Next sibling
+el.prev_sibling          # Previous sibling
+```
+
+## Python: Spider Framework
+
+For multi-page crawling with link following:
+
+```python
+from scrapling.spiders import Spider, Request, Response
+
+class QuotesSpider(Spider):
+    name = "quotes"
+    start_urls = ["https://quotes.toscrape.com/"]
+    concurrent_requests = 10
+    download_delay = 1
+
+    async def parse(self, response: Response):
+        for quote in response.css('.quote'):
+            yield {
+                "text": quote.css('.text::text').get(),
+                "author": quote.css('.author::text').get(),
+                "tags": quote.css('.tag::text').getall(),
+            }
+
+        next_page = response.css('.next a::attr(href)').get()
+        if next_page:
+            yield response.follow(next_page)
+
+result = QuotesSpider().start()
+print(f"Scraped {len(result.items)} quotes")
+result.items.to_json("quotes.json")
+```
+
+### Multi-Session Spider
+
+Route requests to different fetcher types:
+
+```python
+from scrapling.fetchers import FetcherSession, AsyncStealthySession
+
+class SmartSpider(Spider):
+    name = "smart"
+    start_urls = ["https://example.com/"]
+
+    def configure_sessions(self, manager):
+        manager.add("fast", FetcherSession(impersonate="chrome"))
+        manager.add("stealth", AsyncStealthySession(headless=True), lazy=True)
+
+    async def parse(self, response: Response):
+        for link in response.css('a::attr(href)').getall():
+            if "protected" in link:
+                yield Request(link, sid="stealth")
+            else:
+                yield Request(link, sid="fast", callback=self.parse)
+```
+
+### Pause/Resume Crawling
+
+```python
+spider = QuotesSpider(crawldir="./crawl_checkpoint")
+spider.start()  # Ctrl+C to pause, re-run to resume from checkpoint
+```
+
+## Pitfalls
+
+- **Browser install required**: run `scrapling install` after pip install -- without it, `DynamicFetcher` and `StealthyFetcher` will fail
+- **Timeouts**: DynamicFetcher/StealthyFetcher timeout is in **milliseconds** (default 30000), Fetcher timeout is in **seconds**
+- **Cloudflare bypass**: `solve_cloudflare=True` adds 5-15 seconds to fetch time -- only enable when needed
+- **Resource usage**: StealthyFetcher runs a real browser -- limit concurrent usage
+- **Legal**: always check robots.txt and website ToS before scraping. This library is for educational and research purposes
+- **Python version**: requires Python 3.10+

plugins/cognitive-memory/__init__.py

@@ -0,0 +1,384 @@
+"""Cognitive memory plugin — MemoryProvider interface.
+
+Semantic memory with vector embeddings (via litellm), auto-classification,
+contradiction detection, importance decay, and time-based forgetting.
+Local SQLite storage with binary-packed float32 embeddings.
+
+Original PR #727 by 0xbyt4, adapted to MemoryProvider ABC.
+
+Requires: litellm (for embeddings via any provider — OpenAI, Cohere, etc.)
+Config via environment: uses litellm's standard env vars (OPENAI_API_KEY, etc.)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import os
+import re
+import sqlite3
+import struct
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from agent.memory_provider import MemoryProvider
+
+logger = logging.getLogger(__name__)
+
+_DB_DIR = Path(os.environ.get("HERMES_HOME", os.path.expanduser("~/.hermes"))) / "cognitive_memory"
+_EMBEDDING_DIM = 1536  # text-embedding-3-small default
+_SIMILARITY_DEDUP_THRESHOLD = 0.95
+
+
+# ---------------------------------------------------------------------------
+# Embedding helper
+# ---------------------------------------------------------------------------
+
+def _get_embedding(text: str) -> Optional[List[float]]:
+    """Get embedding via litellm."""
+    try:
+        import litellm
+        resp = litellm.embedding(model="text-embedding-3-small", input=[text])
+        return resp.data[0]["embedding"]
+    except Exception as e:
+        logger.debug("Embedding failed: %s", e)
+        return None
+
+
+def _cosine_similarity(a: List[float], b: List[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    mag_a = math.sqrt(sum(x * x for x in a))
+    mag_b = math.sqrt(sum(x * x for x in b))
+    if mag_a == 0 or mag_b == 0:
+        return 0.0
+    return dot / (mag_a * mag_b)
+
+
+def _pack_embedding(emb: List[float]) -> bytes:
+    return struct.pack(f"{len(emb)}f", *emb)
+
+
+def _unpack_embedding(data: bytes) -> List[float]:
+    n = len(data) // 4
+    return list(struct.unpack(f"{n}f", data))
+
+
+# ---------------------------------------------------------------------------
+# Classification
+# ---------------------------------------------------------------------------
+
+_CATEGORY_PATTERNS = {
+    "preference": [r"\b(?:prefer|like|love|hate|dislike|favorite)\b"],
+    "correction": [r"\b(?:actually|no,|wrong|incorrect|not right)\b"],
+    "fact": [r"\b(?:is|are|was|were|has|have)\b"],
+    "procedure": [r"\b(?:first|then|step|always|never|usually)\b"],
+    "environment": [r"\b(?:running|using|installed|version|os|platform)\b"],
+}
+
+
+def _classify(content: str) -> str:
+    content_lower = content.lower()
+    for category, patterns in _CATEGORY_PATTERNS.items():
+        for pattern in patterns:
+            if re.search(pattern, content_lower):
+                return category
+    return "general"
+
+
+def _estimate_importance(content: str, category: str) -> float:
+    base = {"correction": 0.9, "preference": 0.7, "procedure": 0.6}.get(category, 0.5)
+    # Longer content slightly more important
+    length_bonus = min(len(content) / 500, 0.2)
+    return min(base + length_bonus, 1.0)
+
+
+# ---------------------------------------------------------------------------
+# Tool schema
+# ---------------------------------------------------------------------------
+
+COGNITIVE_RECALL_SCHEMA = {
+    "name": "cognitive_recall",
+    "description": (
+        "Semantic memory with automatic classification and importance scoring. "
+        "Actions: recall (search by meaning), store (add a fact), "
+        "forget (remove by ID), status (memory stats)."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": ["recall", "store", "forget", "status"],
+                "description": "Action to perform.",
+            },
+            "query": {"type": "string", "description": "Search query (for 'recall')."},
+            "content": {"type": "string", "description": "Fact to store (for 'store')."},
+            "category": {
+                "type": "string",
+                "enum": ["preference", "fact", "procedure", "environment", "correction", "general"],
+                "description": "Category (auto-detected if omitted).",
+            },
+            "memory_id": {"type": "integer", "description": "Memory ID (for 'forget')."},
+        },
+        "required": ["action"],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# MemoryProvider implementation
+# ---------------------------------------------------------------------------
+
+class CognitiveMemoryProvider(MemoryProvider):
+    """Semantic memory with embeddings, classification, and forgetting."""
+
+    def __init__(self):
+        self._conn = None
+        self._decay_half_life = 30  # days
+        self._last_decay = 0
+
+    @property
+    def name(self) -> str:
+        return "cognitive"
+
+    def get_config_schema(self):
+        return [
+            {"key": "embedding_model", "description": "Embedding model (litellm format)", "default": "text-embedding-3-small"},
+            {"key": "decay_half_life", "description": "Importance decay half-life in days (0=disabled)", "default": "30"},
+        ]
+
+    def is_available(self) -> bool:
+        try:
+            import litellm  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def initialize(self, session_id: str, **kwargs) -> None:
+        _DB_DIR.mkdir(parents=True, exist_ok=True)
+        db_path = _DB_DIR / "cognitive.db"
+        self._conn = sqlite3.connect(str(db_path))
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.executescript("""
+            CREATE TABLE IF NOT EXISTS memories (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                content TEXT NOT NULL,
+                category TEXT DEFAULT 'general',
+                importance REAL DEFAULT 0.5,
+                embedding BLOB,
+                retrieval_count INTEGER DEFAULT 0,
+                helpful_count INTEGER DEFAULT 0,
+                created_at REAL,
+                updated_at REAL,
+                deleted INTEGER DEFAULT 0
+            );
+            CREATE INDEX IF NOT EXISTS idx_mem_importance ON memories(importance DESC);
+            CREATE INDEX IF NOT EXISTS idx_mem_category ON memories(category);
+        """)
+        self._conn.commit()
+
+    def system_prompt_block(self) -> str:
+        if not self._conn:
+            return ""
+        try:
+            count = self._conn.execute(
+                "SELECT COUNT(*) FROM memories WHERE deleted = 0"
+            ).fetchone()[0]
+        except Exception:
+            count = 0
+        if count == 0:
+            return ""
+        return (
+            f"# Cognitive Memory\n"
+            f"Active. {count} memories with semantic recall and importance scoring.\n"
+            f"Use cognitive_recall to search, store facts, or check status.\n"
+            f"Memories decay over time — frequently used facts persist, unused ones fade."
+        )
+
+    def prefetch(self, query: str) -> str:
+        if not self._conn or not query:
+            return ""
+        emb = _get_embedding(query)
+        if not emb:
+            return ""
+        try:
+            rows = self._conn.execute(
+                "SELECT id, content, importance, embedding FROM memories "
+                "WHERE deleted = 0 AND embedding IS NOT NULL "
+                "ORDER BY importance DESC LIMIT 50"
+            ).fetchall()
+            scored = []
+            now = time.time()
+            for row in rows:
+                mem_emb = _unpack_embedding(row[3])
+                sim = _cosine_similarity(emb, mem_emb)
+                importance = row[2]
+                score = 0.5 * sim + 0.3 * importance + 0.2 * max(0, 1 - (now - (row[0] * 86400)) / (30 * 86400))
+                if sim > 0.3:
+                    scored.append((score, row[1]))
+            scored.sort(reverse=True)
+            if not scored:
+                return ""
+            lines = [f"- {content}" for _, content in scored[:5]]
+            return "## Cognitive Memory\n" + "\n".join(lines)
+        except Exception as e:
+            logger.debug("Cognitive prefetch failed: %s", e)
+            return ""
+
+    def sync_turn(self, user_content: str, assistant_content: str) -> None:
+        # Run decay cycle periodically
+        self._maybe_decay()
+
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        return [COGNITIVE_RECALL_SCHEMA]
+
+    def handle_tool_call(self, tool_name: str, args: dict, **kwargs) -> str:
+        if tool_name != "cognitive_recall":
+            return json.dumps({"error": f"Unknown tool: {tool_name}"})
+
+        action = args.get("action", "")
+
+        if action == "store":
+            return self._store(args)
+        elif action == "recall":
+            return self._recall(args)
+        elif action == "forget":
+            return self._forget(args)
+        elif action == "status":
+            return self._status()
+        return json.dumps({"error": f"Unknown action: {action}"})
+
+    def on_memory_write(self, action: str, target: str, content: str) -> None:
+        if action == "add" and self._conn and content:
+            category = "preference" if target == "user" else _classify(content)
+            importance = _estimate_importance(content, category)
+            emb = _get_embedding(content)
+            now = time.time()
+            self._conn.execute(
+                "INSERT INTO memories (content, category, importance, embedding, created_at, updated_at) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (content, category, importance, _pack_embedding(emb) if emb else None, now, now),
+            )
+            self._conn.commit()
+
+    def shutdown(self) -> None:
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    # -- Internal methods ----------------------------------------------------
+
+    def _store(self, args: dict) -> str:
+        content = args.get("content", "")
+        if not content:
+            return json.dumps({"error": "content is required"})
+
+        category = args.get("category") or _classify(content)
+        importance = _estimate_importance(content, category)
+        emb = _get_embedding(content)
+
+        # Dedup check
+        if emb:
+            rows = self._conn.execute(
+                "SELECT id, embedding FROM memories WHERE deleted = 0 AND embedding IS NOT NULL"
+            ).fetchall()
+            for row in rows:
+                existing_emb = _unpack_embedding(row[1])
+                if _cosine_similarity(emb, existing_emb) > _SIMILARITY_DEDUP_THRESHOLD:
+                    return json.dumps({"error": "Very similar memory already exists", "existing_id": row[0]})
+
+        now = time.time()
+        cur = self._conn.execute(
+            "INSERT INTO memories (content, category, importance, embedding, created_at, updated_at) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            (content, category, importance, _pack_embedding(emb) if emb else None, now, now),
+        )
+        self._conn.commit()
+        return json.dumps({"id": cur.lastrowid, "category": category, "importance": round(importance, 2)})
+
+    def _recall(self, args: dict) -> str:
+        query = args.get("query", "")
+        if not query:
+            return json.dumps({"error": "query is required"})
+
+        emb = _get_embedding(query)
+        if not emb:
+            return json.dumps({"error": "Embedding generation failed"})
+
+        rows = self._conn.execute(
+            "SELECT id, content, category, importance, embedding, created_at FROM memories "
+            "WHERE deleted = 0 AND embedding IS NOT NULL "
+            "ORDER BY importance DESC LIMIT 50"
+        ).fetchall()
+
+        now = time.time()
+        results = []
+        for row in rows:
+            mem_emb = _unpack_embedding(row[4])
+            sim = _cosine_similarity(emb, mem_emb)
+            days_old = (now - (row[5] or now)) / 86400
+            recency = max(0, 1 - days_old / 90)
+            score = 0.5 * sim + 0.3 * row[3] + 0.2 * recency
+            if sim > 0.2:
+                results.append({
+                    "id": row[0], "content": row[1], "category": row[2],
+                    "score": round(score, 3), "similarity": round(sim, 3),
+                })
+
+        results.sort(key=lambda x: x["score"], reverse=True)
+        # Bump retrieval counts
+        for r in results[:10]:
+            self._conn.execute(
+                "UPDATE memories SET retrieval_count = retrieval_count + 1 WHERE id = ?",
+                (r["id"],),
+            )
+        self._conn.commit()
+        return json.dumps({"results": results[:10], "count": len(results[:10])})
+
+    def _forget(self, args: dict) -> str:
+        memory_id = args.get("memory_id")
+        if memory_id is None:
+            return json.dumps({"error": "memory_id is required"})
+        self._conn.execute("UPDATE memories SET deleted = 1 WHERE id = ?", (int(memory_id),))
+        self._conn.commit()
+        return json.dumps({"forgotten": True, "id": memory_id})
+
+    def _status(self) -> str:
+        total = self._conn.execute("SELECT COUNT(*) FROM memories WHERE deleted = 0").fetchone()[0]
+        by_cat = self._conn.execute(
+            "SELECT category, COUNT(*) FROM memories WHERE deleted = 0 GROUP BY category"
+        ).fetchall()
+        return json.dumps({
+            "total": total,
+            "by_category": {row[0]: row[1] for row in by_cat},
+            "decay_half_life_days": self._decay_half_life,
+        })
+
+    def _maybe_decay(self) -> None:
+        """Run importance decay every ~1 hour."""
+        now = time.time()
+        if now - self._last_decay < 3600:
+            return
+        self._last_decay = now
+        if not self._conn or self._decay_half_life <= 0:
+            return
+        try:
+            factor = 0.5 ** (1.0 / self._decay_half_life)
+            self._conn.execute(
+                "UPDATE memories SET importance = importance * ? WHERE deleted = 0",
+                (factor,),
+            )
+            # Prune very low importance
+            self._conn.execute(
+                "UPDATE memories SET deleted = 1 WHERE deleted = 0 AND importance < 0.05"
+            )
+            self._conn.commit()
+        except Exception as e:
+            logger.debug("Cognitive decay failed: %s", e)
+
+
+def register(ctx) -> None:
+    """Register cognitive memory as a memory provider plugin."""
+    ctx.register_memory_provider(CognitiveMemoryProvider())

plugins/cognitive-memory/plugin.yaml

@@ -0,0 +1,6 @@
+name: cognitive-memory
+version: 1.0.0
+description: >
+  Semantic memory with vector embeddings, auto-classification, contradiction
+  detection, importance decay, and time-based forgetting. Local SQLite storage,
+  requires litellm for embeddings.

plugins/hermes-memory-store/__init__.py

@@ -0,0 +1,373 @@
+"""hermes-memory-store — holographic memory plugin using MemoryProvider interface.
+
+Registers as a MemoryProvider plugin, giving the agent structured fact storage
+with entity resolution, trust scoring, and HRR-based compositional retrieval.
+
+Original plugin by dusterbloom (PR #2351), adapted to the MemoryProvider ABC.
+
+Config in ~/.hermes/config.yaml:
+  plugins:
+    hermes-memory-store:
+      db_path: ~/.hermes/memory_store.db
+      auto_extract: false
+      default_trust: 0.5
+      min_trust_threshold: 0.3
+      temporal_decay_half_life: 0
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any, Dict, List
+
+from agent.memory_provider import MemoryProvider
+from .store import MemoryStore
+from .retrieval import FactRetriever
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Tool schemas (unchanged from original PR)
+# ---------------------------------------------------------------------------
+
+FACT_STORE_SCHEMA = {
+    "name": "fact_store",
+    "description": (
+        "Deep structured memory with algebraic reasoning. "
+        "Use alongside the memory tool — memory for always-on context, "
+        "fact_store for deep recall and compositional queries.\n\n"
+        "ACTIONS (simple → powerful):\n"
+        "• add — Store a fact the user would expect you to remember.\n"
+        "• search — Keyword lookup ('editor config', 'deploy process').\n"
+        "• probe — Entity recall: ALL facts about a person/thing.\n"
+        "• related — What connects to an entity? Structural adjacency.\n"
+        "• reason — Compositional: facts connected to MULTIPLE entities simultaneously.\n"
+        "• contradict — Memory hygiene: find facts making conflicting claims.\n"
+        "• update/remove/list — CRUD operations.\n\n"
+        "IMPORTANT: Before answering questions about the user, ALWAYS probe or reason first."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": ["add", "search", "probe", "related", "reason", "contradict", "update", "remove", "list"],
+            },
+            "content": {"type": "string", "description": "Fact content (required for 'add')."},
+            "query": {"type": "string", "description": "Search query (required for 'search')."},
+            "entity": {"type": "string", "description": "Entity name for 'probe'/'related'."},
+            "entities": {"type": "array", "items": {"type": "string"}, "description": "Entity names for 'reason'."},
+            "fact_id": {"type": "integer", "description": "Fact ID for 'update'/'remove'."},
+            "category": {"type": "string", "enum": ["user_pref", "project", "tool", "general"]},
+            "tags": {"type": "string", "description": "Comma-separated tags."},
+            "trust_delta": {"type": "number", "description": "Trust adjustment for 'update'."},
+            "min_trust": {"type": "number", "description": "Minimum trust filter (default: 0.3)."},
+            "limit": {"type": "integer", "description": "Max results (default: 10)."},
+        },
+        "required": ["action"],
+    },
+}
+
+FACT_FEEDBACK_SCHEMA = {
+    "name": "fact_feedback",
+    "description": (
+        "Rate a fact after using it. Mark 'helpful' if accurate, 'unhelpful' if outdated. "
+        "This trains the memory — good facts rise, bad facts sink."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "action": {"type": "string", "enum": ["helpful", "unhelpful"]},
+            "fact_id": {"type": "integer", "description": "The fact ID to rate."},
+        },
+        "required": ["action", "fact_id"],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+def _load_plugin_config() -> dict:
+    config_path = Path("~/.hermes/config.yaml").expanduser()
+    if not config_path.exists():
+        return {}
+    try:
+        import yaml
+        with open(config_path) as f:
+            all_config = yaml.safe_load(f) or {}
+        return all_config.get("plugins", {}).get("hermes-memory-store", {}) or {}
+    except Exception:
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# MemoryProvider implementation
+# ---------------------------------------------------------------------------
+
+class HolographicMemoryProvider(MemoryProvider):
+    """Holographic memory with structured facts, entity resolution, and HRR retrieval."""
+
+    def __init__(self, config: dict | None = None):
+        self._config = config or _load_plugin_config()
+        self._store = None
+        self._retriever = None
+        self._min_trust = float(self._config.get("min_trust_threshold", 0.3))
+
+    @property
+    def name(self) -> str:
+        return "holographic"
+
+    def is_available(self) -> bool:
+        return True  # SQLite is always available, numpy is optional
+
+    def get_config_schema(self):
+        return [
+            {"key": "db_path", "description": "SQLite database path", "default": "~/.hermes/memory_store.db"},
+            {"key": "auto_extract", "description": "Auto-extract facts at session end", "default": "false", "choices": ["true", "false"]},
+            {"key": "default_trust", "description": "Default trust score for new facts", "default": "0.5"},
+            {"key": "hrr_dim", "description": "HRR vector dimensions", "default": "1024"},
+        ]
+
+    def initialize(self, session_id: str, **kwargs) -> None:
+        db_path = self._config.get("db_path", "~/.hermes/memory_store.db")
+        default_trust = float(self._config.get("default_trust", 0.5))
+        hrr_dim = int(self._config.get("hrr_dim", 1024))
+        hrr_weight = float(self._config.get("hrr_weight", 0.3))
+        temporal_decay = int(self._config.get("temporal_decay_half_life", 0))
+
+        self._store = MemoryStore(db_path=db_path, default_trust=default_trust, hrr_dim=hrr_dim)
+        self._retriever = FactRetriever(
+            store=self._store,
+            temporal_decay_half_life=temporal_decay,
+            hrr_weight=hrr_weight,
+            hrr_dim=hrr_dim,
+        )
+        self._session_id = session_id
+
+    def system_prompt_block(self) -> str:
+        if not self._store:
+            return ""
+        try:
+            total = self._store._conn.execute(
+                "SELECT COUNT(*) FROM facts"
+            ).fetchone()[0]
+        except Exception:
+            total = 0
+        if total == 0:
+            return ""
+        return (
+            f"# Holographic Memory\n"
+            f"Active. {total} facts stored with entity resolution and trust scoring.\n"
+            f"Use fact_store to search, probe entities, reason across entities, or add facts.\n"
+            f"Use fact_feedback to rate facts after using them (trains trust scores)."
+        )
+
+    def prefetch(self, query: str) -> str:
+        if not self._retriever or not query:
+            return ""
+        try:
+            results = self._retriever.search(query, min_trust=self._min_trust, limit=5)
+            if not results:
+                return ""
+            lines = []
+            for r in results:
+                trust = r.get("trust", 0)
+                lines.append(f"- [{trust:.1f}] {r.get('content', '')}")
+            return "## Holographic Memory\n" + "\n".join(lines)
+        except Exception as e:
+            logger.debug("Holographic prefetch failed: %s", e)
+            return ""
+
+    def sync_turn(self, user_content: str, assistant_content: str) -> None:
+        # Holographic memory stores explicit facts via tools, not auto-sync.
+        # The on_session_end hook handles auto-extraction if configured.
+        pass
+
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        return [FACT_STORE_SCHEMA, FACT_FEEDBACK_SCHEMA]
+
+    def handle_tool_call(self, tool_name: str, args: Dict[str, Any], **kwargs) -> str:
+        if tool_name == "fact_store":
+            return self._handle_fact_store(args)
+        elif tool_name == "fact_feedback":
+            return self._handle_fact_feedback(args)
+        return json.dumps({"error": f"Unknown tool: {tool_name}"})
+
+    def on_session_end(self, messages: List[Dict[str, Any]]) -> None:
+        if not self._config.get("auto_extract", False):
+            return
+        if not self._store or not messages:
+            return
+        self._auto_extract_facts(messages)
+
+    def on_memory_write(self, action: str, target: str, content: str) -> None:
+        """Mirror built-in memory writes as facts."""
+        if action == "add" and self._store and content:
+            try:
+                category = "user_pref" if target == "user" else "general"
+                self._store.add_fact(content, category=category)
+            except Exception as e:
+                logger.debug("Holographic memory_write mirror failed: %s", e)
+
+    def shutdown(self) -> None:
+        self._store = None
+        self._retriever = None
+
+    # -- Tool handlers -------------------------------------------------------
+
+    def _handle_fact_store(self, args: dict) -> str:
+        try:
+            action = args["action"]
+            store = self._store
+            retriever = self._retriever
+
+            if action == "add":
+                fact_id = store.add_fact(
+                    args["content"],
+                    category=args.get("category", "general"),
+                    tags=args.get("tags", ""),
+                )
+                return json.dumps({"fact_id": fact_id, "status": "added"})
+
+            elif action == "search":
+                results = retriever.search(
+                    args["query"],
+                    category=args.get("category"),
+                    min_trust=float(args.get("min_trust", self._min_trust)),
+                    limit=int(args.get("limit", 10)),
+                )
+                return json.dumps({"results": results, "count": len(results)})
+
+            elif action == "probe":
+                results = retriever.probe(
+                    args["entity"],
+                    category=args.get("category"),
+                    limit=int(args.get("limit", 10)),
+                )
+                return json.dumps({"results": results, "count": len(results)})
+
+            elif action == "related":
+                results = retriever.related(
+                    args["entity"],
+                    category=args.get("category"),
+                    limit=int(args.get("limit", 10)),
+                )
+                return json.dumps({"results": results, "count": len(results)})
+
+            elif action == "reason":
+                entities = args.get("entities", [])
+                if not entities:
+                    return json.dumps({"error": "reason requires 'entities' list"})
+                results = retriever.reason(
+                    entities,
+                    category=args.get("category"),
+                    limit=int(args.get("limit", 10)),
+                )
+                return json.dumps({"results": results, "count": len(results)})
+
+            elif action == "contradict":
+                results = retriever.contradict(
+                    category=args.get("category"),
+                    limit=int(args.get("limit", 10)),
+                )
+                return json.dumps({"results": results, "count": len(results)})
+
+            elif action == "update":
+                updated = store.update_fact(
+                    int(args["fact_id"]),
+                    content=args.get("content"),
+                    trust_delta=float(args["trust_delta"]) if "trust_delta" in args else None,
+                    tags=args.get("tags"),
+                    category=args.get("category"),
+                )
+                return json.dumps({"updated": updated})
+
+            elif action == "remove":
+                removed = store.remove_fact(int(args["fact_id"]))
+                return json.dumps({"removed": removed})
+
+            elif action == "list":
+                facts = store.list_facts(
+                    category=args.get("category"),
+                    min_trust=float(args.get("min_trust", 0.0)),
+                    limit=int(args.get("limit", 10)),
+                )
+                return json.dumps({"facts": facts, "count": len(facts)})
+
+            else:
+                return json.dumps({"error": f"Unknown action: {action}"})
+
+        except KeyError as exc:
+            return json.dumps({"error": f"Missing required argument: {exc}"})
+        except Exception as exc:
+            return json.dumps({"error": str(exc)})
+
+    def _handle_fact_feedback(self, args: dict) -> str:
+        try:
+            fact_id = int(args["fact_id"])
+            helpful = args["action"] == "helpful"
+            result = self._store.record_feedback(fact_id, helpful=helpful)
+            return json.dumps(result)
+        except KeyError as exc:
+            return json.dumps({"error": f"Missing required argument: {exc}"})
+        except Exception as exc:
+            return json.dumps({"error": str(exc)})
+
+    # -- Auto-extraction (on_session_end) ------------------------------------
+
+    def _auto_extract_facts(self, messages: list) -> None:
+        _PREF_PATTERNS = [
+            re.compile(r'\bI\s+(?:prefer|like|love|use|want|need)\s+(.+)', re.IGNORECASE),
+            re.compile(r'\bmy\s+(?:favorite|preferred|default)\s+\w+\s+is\s+(.+)', re.IGNORECASE),
+            re.compile(r'\bI\s+(?:always|never|usually)\s+(.+)', re.IGNORECASE),
+        ]
+        _DECISION_PATTERNS = [
+            re.compile(r'\bwe\s+(?:decided|agreed|chose)\s+(?:to\s+)?(.+)', re.IGNORECASE),
+            re.compile(r'\bthe\s+project\s+(?:uses|needs|requires)\s+(.+)', re.IGNORECASE),
+        ]
+
+        extracted = 0
+        for msg in messages:
+            if msg.get("role") != "user":
+                continue
+            content = msg.get("content", "")
+            if not isinstance(content, str) or len(content) < 10:
+                continue
+
+            for pattern in _PREF_PATTERNS:
+                if pattern.search(content):
+                    try:
+                        self._store.add_fact(content[:400], category="user_pref")
+                        extracted += 1
+                    except Exception:
+                        pass
+                    break
+
+            for pattern in _DECISION_PATTERNS:
+                if pattern.search(content):
+                    try:
+                        self._store.add_fact(content[:400], category="project")
+                        extracted += 1
+                    except Exception:
+                        pass
+                    break
+
+        if extracted:
+            logger.info("Auto-extracted %d facts from conversation", extracted)
+
+
+# ---------------------------------------------------------------------------
+# Plugin entry point
+# ---------------------------------------------------------------------------
+
+def register(ctx) -> None:
+    """Register the holographic memory provider with the plugin system."""
+    config = _load_plugin_config()
+    provider = HolographicMemoryProvider(config=config)
+    ctx.register_memory_provider(provider)

plugins/hermes-memory-store/holographic.py

@@ -0,0 +1,203 @@
+"""Holographic Reduced Representations (HRR) with phase encoding.
+
+HRRs are a vector symbolic architecture for encoding compositional structure
+into fixed-width distributed representations. This module uses *phase vectors*:
+each concept is a vector of angles in [0, 2π). The algebraic operations are:
+
+  bind   — circular convolution (phase addition)  — associates two concepts
+  unbind — circular correlation (phase subtraction) — retrieves a bound value
+  bundle — superposition (circular mean)           — merges multiple concepts
+
+Phase encoding is numerically stable, avoids the magnitude collapse of
+traditional complex-number HRRs, and maps cleanly to cosine similarity.
+
+Atoms are generated deterministically from SHA-256 so representations are
+identical across processes, machines, and language versions.
+
+References:
+  Plate (1995) — Holographic Reduced Representations
+  Gayler (2004) — Vector Symbolic Architectures answer Jackendoff's challenges
+"""
+
+import hashlib
+import logging
+import struct
+import math
+
+try:
+    import numpy as np
+    _HAS_NUMPY = True
+except ImportError:
+    _HAS_NUMPY = False
+
+logger = logging.getLogger(__name__)
+
+_TWO_PI = 2.0 * math.pi
+
+
+def _require_numpy() -> None:
+    if not _HAS_NUMPY:
+        raise RuntimeError("numpy is required for holographic operations")
+
+
+def encode_atom(word: str, dim: int = 1024) -> "np.ndarray":
+    """Deterministic phase vector via SHA-256 counter blocks.
+
+    Uses hashlib (not numpy RNG) for cross-platform reproducibility.
+
+    Algorithm:
+    - Generate enough SHA-256 blocks by hashing f"{word}:{i}" for i=0,1,2,...
+    - Concatenate digests, interpret as uint16 values via struct.unpack
+    - Scale to [0, 2π): phases = values * (2π / 65536)
+    - Truncate to dim elements
+    - Returns np.float64 array of shape (dim,)
+    """
+    _require_numpy()
+
+    # Each SHA-256 digest is 32 bytes = 16 uint16 values.
+    values_per_block = 16
+    blocks_needed = math.ceil(dim / values_per_block)
+
+    uint16_values: list[int] = []
+    for i in range(blocks_needed):
+        digest = hashlib.sha256(f"{word}:{i}".encode()).digest()
+        uint16_values.extend(struct.unpack("<16H", digest))
+
+    phases = np.array(uint16_values[:dim], dtype=np.float64) * (_TWO_PI / 65536.0)
+    return phases
+
+
+def bind(a: "np.ndarray", b: "np.ndarray") -> "np.ndarray":
+    """Circular convolution = element-wise phase addition.
+
+    Binding associates two concepts into a single composite vector.
+    The result is dissimilar to both inputs (quasi-orthogonal).
+    """
+    _require_numpy()
+    return (a + b) % _TWO_PI
+
+
+def unbind(memory: "np.ndarray", key: "np.ndarray") -> "np.ndarray":
+    """Circular correlation = element-wise phase subtraction.
+
+    Unbinding retrieves the value associated with a key from a memory vector.
+    unbind(bind(a, b), a) ≈ b  (up to superposition noise)
+    """
+    _require_numpy()
+    return (memory - key) % _TWO_PI
+
+
+def bundle(*vectors: "np.ndarray") -> "np.ndarray":
+    """Superposition via circular mean of complex exponentials.
+
+    Bundling merges multiple vectors into one that is similar to each input.
+    The result can hold O(sqrt(dim)) items before similarity degrades.
+    """
+    _require_numpy()
+    complex_sum = np.sum([np.exp(1j * v) for v in vectors], axis=0)
+    return np.angle(complex_sum) % _TWO_PI
+
+
+def similarity(a: "np.ndarray", b: "np.ndarray") -> float:
+    """Phase cosine similarity. Range [-1, 1].
+
+    Returns 1.0 for identical vectors, near 0.0 for random (unrelated) vectors,
+    and -1.0 for perfectly anti-correlated vectors.
+    """
+    _require_numpy()
+    return float(np.mean(np.cos(a - b)))
+
+
+def encode_text(text: str, dim: int = 1024) -> "np.ndarray":
+    """Bag-of-words: bundle of atom vectors for each token.
+
+    Tokenizes by lowercasing, splitting on whitespace, and stripping
+    leading/trailing punctuation from each token.
+
+    Returns bundle of all token atom vectors.
+    If text is empty or produces no tokens, returns encode_atom("__hrr_empty__", dim).
+    """
+    _require_numpy()
+
+    tokens = [
+        token.strip(".,!?;:\"'()[]{}")
+        for token in text.lower().split()
+    ]
+    tokens = [t for t in tokens if t]
+
+    if not tokens:
+        return encode_atom("__hrr_empty__", dim)
+
+    atom_vectors = [encode_atom(token, dim) for token in tokens]
+    return bundle(*atom_vectors)
+
+
+def encode_fact(content: str, entities: list[str], dim: int = 1024) -> "np.ndarray":
+    """Structured encoding: content bound to ROLE_CONTENT, each entity bound to ROLE_ENTITY, all bundled.
+
+    Role vectors are reserved atoms: "__hrr_role_content__", "__hrr_role_entity__"
+
+    Components:
+    1. bind(encode_text(content, dim), encode_atom("__hrr_role_content__", dim))
+    2. For each entity: bind(encode_atom(entity.lower(), dim), encode_atom("__hrr_role_entity__", dim))
+    3. bundle all components together
+
+    This enables algebraic extraction:
+        unbind(fact, bind(entity, ROLE_ENTITY)) ≈ content_vector
+    """
+    _require_numpy()
+
+    role_content = encode_atom("__hrr_role_content__", dim)
+    role_entity = encode_atom("__hrr_role_entity__", dim)
+
+    components: list[np.ndarray] = [
+        bind(encode_text(content, dim), role_content)
+    ]
+
+    for entity in entities:
+        components.append(bind(encode_atom(entity.lower(), dim), role_entity))
+
+    return bundle(*components)
+
+
+def phases_to_bytes(phases: "np.ndarray") -> bytes:
+    """Serialize phase vector to bytes. float64 tobytes — 8 KB at dim=1024."""
+    _require_numpy()
+    return phases.tobytes()
+
+
+def bytes_to_phases(data: bytes) -> "np.ndarray":
+    """Deserialize bytes back to phase vector. Inverse of phases_to_bytes.
+
+    The .copy() call is required because frombuffer returns a read-only view
+    backed by the bytes object; callers expect a mutable array.
+    """
+    _require_numpy()
+    return np.frombuffer(data, dtype=np.float64).copy()
+
+
+def snr_estimate(dim: int, n_items: int) -> float:
+    """Signal-to-noise ratio estimate for holographic storage.
+
+    SNR = sqrt(dim / n_items) when n_items > 0, else inf.
+
+    The SNR falls below 2.0 when n_items > dim / 4, meaning retrieval
+    errors become likely. Logs a warning when this threshold is crossed.
+    """
+    _require_numpy()
+
+    if n_items <= 0:
+        return float("inf")
+
+    snr = math.sqrt(dim / n_items)
+
+    if snr < 2.0:
+        logger.warning(
+            "HRR storage near capacity: SNR=%.2f (dim=%d, n_items=%d). "
+            "Retrieval accuracy may degrade. Consider increasing dim or reducing stored items.",
+            snr,
+            dim,
+            n_items,
+        )
+
+    return snr

plugins/hermes-memory-store/plugin.yaml

@@ -0,0 +1,6 @@
+name: hermes-memory-store
+version: 0.1.0
+description: Structured memory backend with SQLite storage, trust scoring, entity resolution, and hybrid keyword/BM25 retrieval.
+author: peppi
+hooks:
+  - on_session_end

plugins/hermes-memory-store/retrieval.py

@@ -0,0 +1,597 @@
+"""Hybrid keyword/BM25 retrieval for the memory store.
+
+Ported from KIK memory_agent.py — combines FTS5 full-text search with
+Jaccard similarity reranking and trust-weighted scoring.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .store import MemoryStore
+
+try:
+    from . import holographic as hrr
+except ImportError:
+    import holographic as hrr  # type: ignore[no-redef]
+
+
+class FactRetriever:
+    """Multi-strategy fact retrieval with trust-weighted scoring."""
+
+    def __init__(
+        self,
+        store: MemoryStore,
+        temporal_decay_half_life: int = 0,  # days, 0 = disabled
+        fts_weight: float = 0.4,
+        jaccard_weight: float = 0.3,
+        hrr_weight: float = 0.3,
+        hrr_dim: int = 1024,
+    ):
+        self.store = store
+        self.half_life = temporal_decay_half_life
+        self.hrr_dim = hrr_dim
+
+        # Auto-redistribute weights if numpy unavailable
+        if hrr_weight > 0 and not hrr._HAS_NUMPY:
+            fts_weight = 0.6
+            jaccard_weight = 0.4
+            hrr_weight = 0.0
+
+        self.fts_weight = fts_weight
+        self.jaccard_weight = jaccard_weight
+        self.hrr_weight = hrr_weight
+
+    def search(
+        self,
+        query: str,
+        category: str | None = None,
+        min_trust: float = 0.3,
+        limit: int = 10,
+    ) -> list[dict]:
+        """Hybrid search: FTS5 candidates → Jaccard rerank → trust weighting.
+
+        Pipeline:
+        1. FTS5 search: Get limit*3 candidates from SQLite full-text search
+        2. Jaccard boost: Token overlap between query and fact content
+        3. Trust weighting: final_score = relevance * trust_score
+        4. Temporal decay (optional): decay = 0.5^(age_days / half_life)
+
+        Returns list of dicts with fact data + 'score' field, sorted by score desc.
+        """
+        # Stage 1: Get FTS5 candidates (more than limit for reranking headroom)
+        candidates = self._fts_candidates(query, category, min_trust, limit * 3)
+
+        if not candidates:
+            return []
+
+        # Stage 2: Rerank with Jaccard + trust + optional decay
+        query_tokens = self._tokenize(query)
+        scored = []
+
+        for fact in candidates:
+            content_tokens = self._tokenize(fact["content"])
+            tag_tokens = self._tokenize(fact.get("tags", ""))
+            all_tokens = content_tokens | tag_tokens
+
+            jaccard = self._jaccard_similarity(query_tokens, all_tokens)
+            fts_score = fact.get("fts_rank", 0.0)
+
+            # HRR similarity
+            if self.hrr_weight > 0 and fact.get("hrr_vector"):
+                fact_vec = hrr.bytes_to_phases(fact["hrr_vector"])
+                query_vec = hrr.encode_text(query, self.hrr_dim)
+                hrr_sim = (hrr.similarity(query_vec, fact_vec) + 1.0) / 2.0  # shift to [0,1]
+            else:
+                hrr_sim = 0.5  # neutral
+
+            # Combine FTS5 + Jaccard + HRR
+            relevance = (self.fts_weight * fts_score
+                        + self.jaccard_weight * jaccard
+                        + self.hrr_weight * hrr_sim)
+
+            # Trust weighting
+            score = relevance * fact["trust_score"]
+
+            # Optional temporal decay
+            if self.half_life > 0:
+                score *= self._temporal_decay(fact.get("updated_at") or fact.get("created_at"))
+
+            fact["score"] = score
+            scored.append(fact)
+
+        # Sort by score descending, return top limit
+        scored.sort(key=lambda x: x["score"], reverse=True)
+        results = scored[:limit]
+        # Strip raw HRR bytes — callers expect JSON-serializable dicts
+        for fact in results:
+            fact.pop("hrr_vector", None)
+        return results
+
+    def probe(
+        self,
+        entity: str,
+        category: str | None = None,
+        limit: int = 10,
+    ) -> list[dict]:
+        """Compositional entity query using HRR algebra.
+
+        Unbinds entity from memory bank to extract associated content.
+        This is NOT keyword search — it uses algebraic structure to find facts
+        where the entity plays a structural role.
+
+        Falls back to FTS5 search if numpy unavailable.
+        """
+        if not hrr._HAS_NUMPY:
+            # Fallback to keyword search on entity name
+            return self.search(entity, category=category, limit=limit)
+
+        conn = self.store._conn
+
+        # Encode entity as role-bound vector
+        role_entity = hrr.encode_atom("__hrr_role_entity__", self.hrr_dim)
+        entity_vec = hrr.encode_atom(entity.lower(), self.hrr_dim)
+        probe_key = hrr.bind(entity_vec, role_entity)
+
+        # Try category-specific bank first, then all facts
+        if category:
+            bank_name = f"cat:{category}"
+            bank_row = conn.execute(
+                "SELECT vector FROM memory_banks WHERE bank_name = ?",
+                (bank_name,),
+            ).fetchone()
+            if bank_row:
+                bank_vec = hrr.bytes_to_phases(bank_row["vector"])
+                extracted = hrr.unbind(bank_vec, probe_key)
+                # Use extracted signal to score individual facts
+                return self._score_facts_by_vector(
+                    extracted, category=category, limit=limit
+                )
+
+        # Score against individual fact vectors directly
+        where = "WHERE hrr_vector IS NOT NULL"
+        params: list = []
+        if category:
+            where += " AND category = ?"
+            params.append(category)
+
+        rows = conn.execute(
+            f"""
+            SELECT fact_id, content, category, tags, trust_score,
+                   retrieval_count, helpful_count, created_at, updated_at,
+                   hrr_vector
+            FROM facts
+            {where}
+            """,
+            params,
+        ).fetchall()
+
+        if not rows:
+            # Final fallback: keyword search
+            return self.search(entity, category=category, limit=limit)
+
+        scored = []
+        for row in rows:
+            fact = dict(row)
+            fact_vec = hrr.bytes_to_phases(fact.pop("hrr_vector"))
+            # Unbind probe key from fact to see if entity is structurally present
+            residual = hrr.unbind(fact_vec, probe_key)
+            # Compare residual against content signal
+            role_content = hrr.encode_atom("__hrr_role_content__", self.hrr_dim)
+            content_vec = hrr.bind(hrr.encode_text(fact["content"], self.hrr_dim), role_content)
+            sim = hrr.similarity(residual, content_vec)
+            fact["score"] = (sim + 1.0) / 2.0 * fact["trust_score"]
+            scored.append(fact)
+
+        scored.sort(key=lambda x: x["score"], reverse=True)
+        return scored[:limit]
+
+    def related(
+        self,
+        entity: str,
+        category: str | None = None,
+        limit: int = 10,
+    ) -> list[dict]:
+        """Discover facts that share structural connections with an entity.
+
+        Unlike probe (which finds facts *about* an entity), related finds
+        facts that are connected through shared context — e.g., other entities
+        mentioned alongside this one, or content that overlaps structurally.
+
+        Falls back to FTS5 search if numpy unavailable.
+        """
+        if not hrr._HAS_NUMPY:
+            return self.search(entity, category=category, limit=limit)
+
+        conn = self.store._conn
+
+        # Encode entity as a bare atom (not role-bound — we want ANY structural match)
+        entity_vec = hrr.encode_atom(entity.lower(), self.hrr_dim)
+
+        # Get all facts with vectors
+        where = "WHERE hrr_vector IS NOT NULL"
+        params: list = []
+        if category:
+            where += " AND category = ?"
+            params.append(category)
+
+        rows = conn.execute(
+            f"""
+            SELECT fact_id, content, category, tags, trust_score,
+                   retrieval_count, helpful_count, created_at, updated_at,
+                   hrr_vector
+            FROM facts
+            {where}
+            """,
+            params,
+        ).fetchall()
+
+        if not rows:
+            return self.search(entity, category=category, limit=limit)
+
+        # Score each fact by how much the entity's atom appears in its vector
+        # This catches both role-bound entity matches AND content word matches
+        scored = []
+        for row in rows:
+            fact = dict(row)
+            fact_vec = hrr.bytes_to_phases(fact.pop("hrr_vector"))
+
+            # Check structural similarity: unbind entity from fact
+            residual = hrr.unbind(fact_vec, entity_vec)
+            # A high-similarity residual to ANY known role vector means this entity
+            # plays a structural role in the fact
+            role_entity = hrr.encode_atom("__hrr_role_entity__", self.hrr_dim)
+            role_content = hrr.encode_atom("__hrr_role_content__", self.hrr_dim)
+
+            entity_role_sim = hrr.similarity(residual, role_entity)
+            content_role_sim = hrr.similarity(residual, role_content)
+            # Take the max — entity could appear in either role
+            best_sim = max(entity_role_sim, content_role_sim)
+
+            fact["score"] = (best_sim + 1.0) / 2.0 * fact["trust_score"]
+            scored.append(fact)
+
+        scored.sort(key=lambda x: x["score"], reverse=True)
+        return scored[:limit]
+
+    def reason(
+        self,
+        entities: list[str],
+        category: str | None = None,
+        limit: int = 10,
+    ) -> list[dict]:
+        """Multi-entity compositional query — vector-space JOIN.
+
+        Given multiple entities, algebraically intersects their structural
+        connections to find facts related to ALL of them simultaneously.
+        This is compositional reasoning that no embedding DB can do.
+
+        Example: reason(["peppi", "backend"]) finds facts where peppi AND
+        backend both play structural roles — without keyword matching.
+
+        Falls back to FTS5 search if numpy unavailable.
+        """
+        if not hrr._HAS_NUMPY or not entities:
+            # Fallback: search with all entities as keywords
+            query = " ".join(entities)
+            return self.search(query, category=category, limit=limit)
+
+        conn = self.store._conn
+        role_entity = hrr.encode_atom("__hrr_role_entity__", self.hrr_dim)
+
+        # For each entity, compute what the bank "remembers" about it
+        # by unbinding entity+role from each fact vector
+        entity_residuals = []
+        for entity in entities:
+            entity_vec = hrr.encode_atom(entity.lower(), self.hrr_dim)
+            probe_key = hrr.bind(entity_vec, role_entity)
+            entity_residuals.append(probe_key)
+
+        # The intersection key: bundle all probe keys, then use it to find
+        # facts that are structurally connected to ALL entities
+        intersection_key = hrr.bundle(*entity_residuals) if len(entity_residuals) > 1 else entity_residuals[0]
+
+        # Get all facts with vectors
+        where = "WHERE hrr_vector IS NOT NULL"
+        params: list = []
+        if category:
+            where += " AND category = ?"
+            params.append(category)
+
+        rows = conn.execute(
+            f"""
+            SELECT fact_id, content, category, tags, trust_score,
+                   retrieval_count, helpful_count, created_at, updated_at,
+                   hrr_vector
+            FROM facts
+            {where}
+            """,
+            params,
+        ).fetchall()
+
+        if not rows:
+            query = " ".join(entities)
+            return self.search(query, category=category, limit=limit)
+
+        # Score each fact: unbind the intersection key and check if the
+        # residual is coherent (high self-similarity = structured match)
+        scored = []
+        for row in rows:
+            fact = dict(row)
+            fact_vec = hrr.bytes_to_phases(fact.pop("hrr_vector"))
+
+            # Unbind intersection key from fact
+            residual = hrr.unbind(fact_vec, intersection_key)
+
+            # Score by how much EACH entity is present in this fact
+            # A fact scores high only if ALL entities have structural presence
+            entity_scores = []
+            for entity in entities:
+                entity_vec = hrr.encode_atom(entity.lower(), self.hrr_dim)
+                probe_key = hrr.bind(entity_vec, role_entity)
+                single_residual = hrr.unbind(fact_vec, probe_key)
+                # Check residual against content role (does this entity participate?)
+                role_content = hrr.encode_atom("__hrr_role_content__", self.hrr_dim)
+                sim = hrr.similarity(single_residual, role_content)
+                entity_scores.append(sim)
+
+            # Use minimum score — fact must match ALL entities, not just some
+            # This is the AND semantics (vs OR which would use mean/max)
+            min_sim = min(entity_scores)
+            fact["score"] = (min_sim + 1.0) / 2.0 * fact["trust_score"]
+            scored.append(fact)
+
+        scored.sort(key=lambda x: x["score"], reverse=True)
+        return scored[:limit]
+
+    def contradict(
+        self,
+        category: str | None = None,
+        threshold: float = 0.3,
+        limit: int = 10,
+    ) -> list[dict]:
+        """Find potentially contradictory facts via entity overlap + content divergence.
+
+        Two facts contradict when they share entities (same subject) but have
+        low content-vector similarity (different claims). This is automated
+        memory hygiene — no other memory system does this.
+
+        Returns pairs of facts with a contradiction score.
+        Falls back to empty list if numpy unavailable.
+        """
+        if not hrr._HAS_NUMPY:
+            return []
+
+        conn = self.store._conn
+
+        # Get all facts with vectors and their linked entities
+        where = "WHERE f.hrr_vector IS NOT NULL"
+        params: list = []
+        if category:
+            where += " AND f.category = ?"
+            params.append(category)
+
+        rows = conn.execute(
+            f"""
+            SELECT f.fact_id, f.content, f.category, f.tags, f.trust_score,
+                   f.created_at, f.updated_at, f.hrr_vector
+            FROM facts f
+            {where}
+            """,
+            params,
+        ).fetchall()
+
+        if len(rows) < 2:
+            return []
+
+        # Build entity sets per fact
+        fact_entities: dict[int, set[str]] = {}
+        for row in rows:
+            fid = row["fact_id"]
+            entity_rows = conn.execute(
+                """
+                SELECT e.name FROM entities e
+                JOIN fact_entities fe ON fe.entity_id = e.entity_id
+                WHERE fe.fact_id = ?
+                """,
+                (fid,),
+            ).fetchall()
+            fact_entities[fid] = {r["name"].lower() for r in entity_rows}
+
+        # Compare all pairs: high entity overlap + low content similarity = contradiction
+        facts = [dict(r) for r in rows]
+        contradictions = []
+
+        for i in range(len(facts)):
+            for j in range(i + 1, len(facts)):
+                f1, f2 = facts[i], facts[j]
+                ents1 = fact_entities.get(f1["fact_id"], set())
+                ents2 = fact_entities.get(f2["fact_id"], set())
+
+                if not ents1 or not ents2:
+                    continue
+
+                # Entity overlap (Jaccard)
+                entity_overlap = len(ents1 & ents2) / len(ents1 | ents2) if (ents1 | ents2) else 0.0
+
+                if entity_overlap < 0.3:
+                    continue  # Not enough entity overlap to be contradictory
+
+                # Content similarity via HRR vectors
+                v1 = hrr.bytes_to_phases(f1["hrr_vector"])
+                v2 = hrr.bytes_to_phases(f2["hrr_vector"])
+                content_sim = hrr.similarity(v1, v2)
+
+                # High entity overlap + low content similarity = potential contradiction
+                # contradiction_score: higher = more contradictory
+                contradiction_score = entity_overlap * (1.0 - (content_sim + 1.0) / 2.0)
+
+                if contradiction_score >= threshold:
+                    # Strip hrr_vector from output (not JSON serializable)
+                    f1_clean = {k: v for k, v in f1.items() if k != "hrr_vector"}
+                    f2_clean = {k: v for k, v in f2.items() if k != "hrr_vector"}
+                    contradictions.append({
+                        "fact_a": f1_clean,
+                        "fact_b": f2_clean,
+                        "entity_overlap": round(entity_overlap, 3),
+                        "content_similarity": round(content_sim, 3),
+                        "contradiction_score": round(contradiction_score, 3),
+                        "shared_entities": sorted(ents1 & ents2),
+                    })
+
+        contradictions.sort(key=lambda x: x["contradiction_score"], reverse=True)
+        return contradictions[:limit]
+
+    def _score_facts_by_vector(
+        self,
+        target_vec: "np.ndarray",
+        category: str | None = None,
+        limit: int = 10,
+    ) -> list[dict]:
+        """Score facts by similarity to a target vector."""
+        conn = self.store._conn
+
+        where = "WHERE hrr_vector IS NOT NULL"
+        params: list = []
+        if category:
+            where += " AND category = ?"
+            params.append(category)
+
+        rows = conn.execute(
+            f"""
+            SELECT fact_id, content, category, tags, trust_score,
+                   retrieval_count, helpful_count, created_at, updated_at,
+                   hrr_vector
+            FROM facts
+            {where}
+            """,
+            params,
+        ).fetchall()
+
+        scored = []
+        for row in rows:
+            fact = dict(row)
+            fact_vec = hrr.bytes_to_phases(fact.pop("hrr_vector"))
+            sim = hrr.similarity(target_vec, fact_vec)
+            fact["score"] = (sim + 1.0) / 2.0 * fact["trust_score"]
+            scored.append(fact)
+
+        scored.sort(key=lambda x: x["score"], reverse=True)
+        return scored[:limit]
+
+    def _fts_candidates(
+        self,
+        query: str,
+        category: str | None,
+        min_trust: float,
+        limit: int,
+    ) -> list[dict]:
+        """Get raw FTS5 candidates from the store.
+
+        Uses the store's database connection directly for FTS5 MATCH
+        with rank scoring. Normalizes FTS5 rank to [0, 1] range.
+        """
+        conn = self.store._conn
+
+        # Build query - FTS5 rank is negative (lower = better match)
+        # We need to join facts_fts with facts to get all columns
+        params: list = []
+        where_clauses = ["facts_fts MATCH ?"]
+        params.append(query)
+
+        if category:
+            where_clauses.append("f.category = ?")
+            params.append(category)
+
+        where_clauses.append("f.trust_score >= ?")
+        params.append(min_trust)
+
+        where_sql = " AND ".join(where_clauses)
+
+        sql = f"""
+            SELECT f.*, facts_fts.rank as fts_rank_raw
+            FROM facts_fts
+            JOIN facts f ON f.fact_id = facts_fts.rowid
+            WHERE {where_sql}
+            ORDER BY facts_fts.rank
+            LIMIT ?
+        """
+        params.append(limit)
+
+        try:
+            rows = conn.execute(sql, params).fetchall()
+        except Exception:
+            # FTS5 MATCH can fail on malformed queries — fall back to empty
+            return []
+
+        if not rows:
+            return []
+
+        # Normalize FTS5 rank: rank is negative, lower = better
+        # Convert to positive score in [0, 1] range
+        raw_ranks = [abs(row["fts_rank_raw"]) for row in rows]
+        max_rank = max(raw_ranks) if raw_ranks else 1.0
+        max_rank = max(max_rank, 1e-6)  # avoid div by zero
+
+        results = []
+        for row, raw_rank in zip(rows, raw_ranks):
+            fact = dict(row)
+            fact.pop("fts_rank_raw", None)
+            fact["fts_rank"] = raw_rank / max_rank  # normalize to [0, 1]
+            results.append(fact)
+
+        return results
+
+    @staticmethod
+    def _tokenize(text: str) -> set[str]:
+        """Simple whitespace tokenization with lowercasing.
+
+        Strips common punctuation. No stemming/lemmatization (Phase 1).
+        """
+        if not text:
+            return set()
+        # Split on whitespace, lowercase, strip punctuation
+        tokens = set()
+        for word in text.lower().split():
+            cleaned = word.strip(".,;:!?\"'()[]{}#@<>")
+            if cleaned:
+                tokens.add(cleaned)
+        return tokens
+
+    @staticmethod
+    def _jaccard_similarity(set_a: set, set_b: set) -> float:
+        """Jaccard similarity coefficient: |A ∩ B| / |A ∪ B|."""
+        if not set_a or not set_b:
+            return 0.0
+        intersection = len(set_a & set_b)
+        union = len(set_a | set_b)
+        return intersection / union if union > 0 else 0.0
+
+    def _temporal_decay(self, timestamp_str: str | None) -> float:
+        """Exponential decay: 0.5^(age_days / half_life_days).
+
+        Returns 1.0 if decay is disabled or timestamp is missing.
+        """
+        if not self.half_life or not timestamp_str:
+            return 1.0
+
+        try:
+            if isinstance(timestamp_str, str):
+                # Parse ISO format timestamp from SQLite
+                ts = datetime.fromisoformat(timestamp_str.replace("Z", "+00:00"))
+            else:
+                ts = timestamp_str
+
+            if ts.tzinfo is None:
+                ts = ts.replace(tzinfo=timezone.utc)
+
+            age_days = (datetime.now(timezone.utc) - ts).total_seconds() / 86400
+            if age_days < 0:
+                return 1.0
+
+            return math.pow(0.5, age_days / self.half_life)
+        except (ValueError, TypeError):
+            return 1.0

plugins/hermes-memory-store/store.py

@@ -0,0 +1,572 @@
+"""
+SQLite-backed fact store with entity resolution and trust scoring.
+Single-user Hermes memory store plugin.
+"""
+
+import re
+import sqlite3
+import threading
+from datetime import datetime
+from pathlib import Path
+
+try:
+    from . import holographic as hrr
+except ImportError:
+    import holographic as hrr  # type: ignore[no-redef]
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS facts (
+    fact_id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    content         TEXT NOT NULL UNIQUE,
+    category        TEXT DEFAULT 'general',
+    tags            TEXT DEFAULT '',
+    trust_score     REAL DEFAULT 0.5,
+    retrieval_count INTEGER DEFAULT 0,
+    helpful_count   INTEGER DEFAULT 0,
+    created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    hrr_vector      BLOB
+);
+
+CREATE TABLE IF NOT EXISTS entities (
+    entity_id   INTEGER PRIMARY KEY AUTOINCREMENT,
+    name        TEXT NOT NULL,
+    entity_type TEXT DEFAULT 'unknown',
+    aliases     TEXT DEFAULT '',
+    created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS fact_entities (
+    fact_id   INTEGER REFERENCES facts(fact_id),
+    entity_id INTEGER REFERENCES entities(entity_id),
+    PRIMARY KEY (fact_id, entity_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_facts_trust    ON facts(trust_score DESC);
+CREATE INDEX IF NOT EXISTS idx_facts_category ON facts(category);
+CREATE INDEX IF NOT EXISTS idx_entities_name  ON entities(name);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS facts_fts
+    USING fts5(content, tags, content=facts, content_rowid=fact_id);
+
+CREATE TRIGGER IF NOT EXISTS facts_ai AFTER INSERT ON facts BEGIN
+    INSERT INTO facts_fts(rowid, content, tags)
+        VALUES (new.fact_id, new.content, new.tags);
+END;
+
+CREATE TRIGGER IF NOT EXISTS facts_ad AFTER DELETE ON facts BEGIN
+    INSERT INTO facts_fts(facts_fts, rowid, content, tags)
+        VALUES ('delete', old.fact_id, old.content, old.tags);
+END;
+
+CREATE TRIGGER IF NOT EXISTS facts_au AFTER UPDATE ON facts BEGIN
+    INSERT INTO facts_fts(facts_fts, rowid, content, tags)
+        VALUES ('delete', old.fact_id, old.content, old.tags);
+    INSERT INTO facts_fts(rowid, content, tags)
+        VALUES (new.fact_id, new.content, new.tags);
+END;
+
+CREATE TABLE IF NOT EXISTS memory_banks (
+    bank_id    INTEGER PRIMARY KEY AUTOINCREMENT,
+    bank_name  TEXT NOT NULL UNIQUE,
+    vector     BLOB NOT NULL,
+    dim        INTEGER NOT NULL,
+    fact_count INTEGER DEFAULT 0,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+"""
+
+# Trust adjustment constants
+_HELPFUL_DELTA   =  0.05
+_UNHELPFUL_DELTA = -0.10
+_TRUST_MIN       =  0.0
+_TRUST_MAX       =  1.0
+
+# Entity extraction patterns
+_RE_CAPITALIZED  = re.compile(r'\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)\b')
+_RE_DOUBLE_QUOTE = re.compile(r'"([^"]+)"')
+_RE_SINGLE_QUOTE = re.compile(r"'([^']+)'")
+_RE_AKA          = re.compile(
+    r'(\w+(?:\s+\w+)*)\s+(?:aka|also known as)\s+(\w+(?:\s+\w+)*)',
+    re.IGNORECASE,
+)
+
+
+def _clamp_trust(value: float) -> float:
+    return max(_TRUST_MIN, min(_TRUST_MAX, value))
+
+
+class MemoryStore:
+    """SQLite-backed fact store with entity resolution and trust scoring."""
+
+    def __init__(
+        self,
+        db_path: "str | Path" = "~/.hermes/memory_store.db",
+        default_trust: float = 0.5,
+        hrr_dim: int = 1024,
+    ) -> None:
+        self.db_path = Path(db_path).expanduser()
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.default_trust = _clamp_trust(default_trust)
+        self.hrr_dim = hrr_dim
+        self._hrr_available = hrr._HAS_NUMPY
+        self._conn: sqlite3.Connection = sqlite3.connect(
+            str(self.db_path),
+            check_same_thread=False,
+            timeout=10.0,
+        )
+        self._lock = threading.RLock()
+        self._conn.row_factory = sqlite3.Row
+        self._init_db()
+
+    # ------------------------------------------------------------------
+    # Initialisation
+    # ------------------------------------------------------------------
+
+    def _init_db(self) -> None:
+        """Create tables, indexes, and triggers if they do not exist. Enable WAL mode."""
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.executescript(_SCHEMA)
+        # Migrate: add hrr_vector column if missing (safe for existing databases)
+        columns = {row[1] for row in self._conn.execute("PRAGMA table_info(facts)").fetchall()}
+        if "hrr_vector" not in columns:
+            self._conn.execute("ALTER TABLE facts ADD COLUMN hrr_vector BLOB")
+        self._conn.commit()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def add_fact(
+        self,
+        content: str,
+        category: str = "general",
+        tags: str = "",
+    ) -> int:
+        """Insert a fact and return its fact_id.
+
+        Deduplicates by content (UNIQUE constraint). On duplicate, returns
+        the existing fact_id without modifying the row. Extracts entities from
+        the content and links them to the fact.
+        """
+        with self._lock:
+            content = content.strip()
+            if not content:
+                raise ValueError("content must not be empty")
+
+            try:
+                cur = self._conn.execute(
+                    """
+                    INSERT INTO facts (content, category, tags, trust_score)
+                    VALUES (?, ?, ?, ?)
+                    """,
+                    (content, category, tags, self.default_trust),
+                )
+                self._conn.commit()
+                fact_id: int = cur.lastrowid  # type: ignore[assignment]
+            except sqlite3.IntegrityError:
+                # Duplicate content — return existing id
+                row = self._conn.execute(
+                    "SELECT fact_id FROM facts WHERE content = ?", (content,)
+                ).fetchone()
+                return int(row["fact_id"])
+
+            # Entity extraction and linking
+            for name in self._extract_entities(content):
+                entity_id = self._resolve_entity(name)
+                self._link_fact_entity(fact_id, entity_id)
+
+            # Compute HRR vector after entity linking
+            self._compute_hrr_vector(fact_id, content)
+            self._rebuild_bank(category)
+
+            return fact_id
+
+    def search_facts(
+        self,
+        query: str,
+        category: str | None = None,
+        min_trust: float = 0.3,
+        limit: int = 10,
+    ) -> list[dict]:
+        """Full-text search over facts using FTS5.
+
+        Returns a list of fact dicts ordered by FTS5 rank, then trust_score
+        descending. Also increments retrieval_count for matched facts.
+        """
+        with self._lock:
+            query = query.strip()
+            if not query:
+                return []
+
+            params: list = [query, min_trust]
+            category_clause = ""
+            if category is not None:
+                category_clause = "AND f.category = ?"
+                params.append(category)
+            params.append(limit)
+
+            sql = f"""
+                SELECT f.fact_id, f.content, f.category, f.tags,
+                       f.trust_score, f.retrieval_count, f.helpful_count,
+                       f.created_at, f.updated_at
+                FROM facts f
+                JOIN facts_fts fts ON fts.rowid = f.fact_id
+                WHERE facts_fts MATCH ?
+                  AND f.trust_score >= ?
+                  {category_clause}
+                ORDER BY fts.rank, f.trust_score DESC
+                LIMIT ?
+            """
+
+            rows = self._conn.execute(sql, params).fetchall()
+            results = [self._row_to_dict(r) for r in rows]
+
+            if results:
+                ids = [r["fact_id"] for r in results]
+                placeholders = ",".join("?" * len(ids))
+                self._conn.execute(
+                    f"UPDATE facts SET retrieval_count = retrieval_count + 1 WHERE fact_id IN ({placeholders})",
+                    ids,
+                )
+                self._conn.commit()
+
+            return results
+
+    def update_fact(
+        self,
+        fact_id: int,
+        content: str | None = None,
+        trust_delta: float | None = None,
+        tags: str | None = None,
+        category: str | None = None,
+    ) -> bool:
+        """Partially update a fact. Trust is clamped to [0, 1].
+
+        Returns True if the row existed, False otherwise.
+        """
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT fact_id, trust_score FROM facts WHERE fact_id = ?", (fact_id,)
+            ).fetchone()
+            if row is None:
+                return False
+
+            assignments: list[str] = ["updated_at = CURRENT_TIMESTAMP"]
+            params: list = []
+
+            if content is not None:
+                assignments.append("content = ?")
+                params.append(content.strip())
+            if tags is not None:
+                assignments.append("tags = ?")
+                params.append(tags)
+            if category is not None:
+                assignments.append("category = ?")
+                params.append(category)
+            if trust_delta is not None:
+                new_trust = _clamp_trust(row["trust_score"] + trust_delta)
+                assignments.append("trust_score = ?")
+                params.append(new_trust)
+
+            params.append(fact_id)
+            self._conn.execute(
+                f"UPDATE facts SET {', '.join(assignments)} WHERE fact_id = ?",
+                params,
+            )
+            self._conn.commit()
+
+            # If content changed, re-extract entities
+            if content is not None:
+                self._conn.execute(
+                    "DELETE FROM fact_entities WHERE fact_id = ?", (fact_id,)
+                )
+                for name in self._extract_entities(content):
+                    entity_id = self._resolve_entity(name)
+                    self._link_fact_entity(fact_id, entity_id)
+                self._conn.commit()
+
+            # Recompute HRR vector if content changed
+            if content is not None:
+                self._compute_hrr_vector(fact_id, content)
+            # Rebuild bank for relevant category
+            cat = category or self._conn.execute(
+                "SELECT category FROM facts WHERE fact_id = ?", (fact_id,)
+            ).fetchone()["category"]
+            self._rebuild_bank(cat)
+
+            return True
+
+    def remove_fact(self, fact_id: int) -> bool:
+        """Delete a fact and its entity links. Returns True if the row existed."""
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT fact_id, category FROM facts WHERE fact_id = ?", (fact_id,)
+            ).fetchone()
+            if row is None:
+                return False
+
+            self._conn.execute(
+                "DELETE FROM fact_entities WHERE fact_id = ?", (fact_id,)
+            )
+            self._conn.execute("DELETE FROM facts WHERE fact_id = ?", (fact_id,))
+            self._conn.commit()
+            self._rebuild_bank(row["category"])
+            return True
+
+    def list_facts(
+        self,
+        category: str | None = None,
+        min_trust: float = 0.0,
+        limit: int = 50,
+    ) -> list[dict]:
+        """Browse facts ordered by trust_score descending.
+
+        Optionally filter by category and minimum trust score.
+        """
+        with self._lock:
+            params: list = [min_trust]
+            category_clause = ""
+            if category is not None:
+                category_clause = "AND category = ?"
+                params.append(category)
+            params.append(limit)
+
+            sql = f"""
+                SELECT fact_id, content, category, tags, trust_score,
+                       retrieval_count, helpful_count, created_at, updated_at
+                FROM facts
+                WHERE trust_score >= ?
+                  {category_clause}
+                ORDER BY trust_score DESC
+                LIMIT ?
+            """
+            rows = self._conn.execute(sql, params).fetchall()
+            return [self._row_to_dict(r) for r in rows]
+
+    def record_feedback(self, fact_id: int, helpful: bool) -> dict:
+        """Record user feedback and adjust trust asymmetrically.
+
+        helpful=True  -> trust += 0.05, helpful_count += 1
+        helpful=False -> trust -= 0.10
+
+        Returns a dict with fact_id, old_trust, new_trust, helpful_count.
+        Raises KeyError if fact_id does not exist.
+        """
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT fact_id, trust_score, helpful_count FROM facts WHERE fact_id = ?",
+                (fact_id,),
+            ).fetchone()
+            if row is None:
+                raise KeyError(f"fact_id {fact_id} not found")
+
+            old_trust: float = row["trust_score"]
+            delta = _HELPFUL_DELTA if helpful else _UNHELPFUL_DELTA
+            new_trust = _clamp_trust(old_trust + delta)
+
+            helpful_increment = 1 if helpful else 0
+            self._conn.execute(
+                """
+                UPDATE facts
+                SET trust_score    = ?,
+                    helpful_count  = helpful_count + ?,
+                    updated_at     = CURRENT_TIMESTAMP
+                WHERE fact_id = ?
+                """,
+                (new_trust, helpful_increment, fact_id),
+            )
+            self._conn.commit()
+
+            return {
+                "fact_id":      fact_id,
+                "old_trust":    old_trust,
+                "new_trust":    new_trust,
+                "helpful_count": row["helpful_count"] + helpful_increment,
+            }
+
+    # ------------------------------------------------------------------
+    # Entity helpers
+    # ------------------------------------------------------------------
+
+    def _extract_entities(self, text: str) -> list[str]:
+        """Extract entity candidates from text using simple regex rules.
+
+        Rules applied (in order):
+        1. Capitalized multi-word phrases  e.g. "John Doe"
+        2. Double-quoted terms             e.g. "Python"
+        3. Single-quoted terms             e.g. 'pytest'
+        4. AKA patterns                    e.g. "Guido aka BDFL" -> two entities
+
+        Returns a deduplicated list preserving first-seen order.
+        """
+        seen: set[str] = set()
+        candidates: list[str] = []
+
+        def _add(name: str) -> None:
+            stripped = name.strip()
+            if stripped and stripped.lower() not in seen:
+                seen.add(stripped.lower())
+                candidates.append(stripped)
+
+        for m in _RE_CAPITALIZED.finditer(text):
+            _add(m.group(1))
+
+        for m in _RE_DOUBLE_QUOTE.finditer(text):
+            _add(m.group(1))
+
+        for m in _RE_SINGLE_QUOTE.finditer(text):
+            _add(m.group(1))
+
+        for m in _RE_AKA.finditer(text):
+            _add(m.group(1))
+            _add(m.group(2))
+
+        return candidates
+
+    def _resolve_entity(self, name: str) -> int:
+        """Find an existing entity by name or alias (case-insensitive) or create one.
+
+        Returns the entity_id.
+        """
+        # Exact name match
+        row = self._conn.execute(
+            "SELECT entity_id FROM entities WHERE name LIKE ?", (name,)
+        ).fetchone()
+        if row is not None:
+            return int(row["entity_id"])
+
+        # Search aliases — aliases stored as comma-separated; use LIKE with % boundaries
+        alias_row = self._conn.execute(
+            """
+            SELECT entity_id FROM entities
+            WHERE ',' || aliases || ',' LIKE '%,' || ? || ',%'
+            """,
+            (name,),
+        ).fetchone()
+        if alias_row is not None:
+            return int(alias_row["entity_id"])
+
+        # Create new entity
+        cur = self._conn.execute(
+            "INSERT INTO entities (name) VALUES (?)", (name,)
+        )
+        self._conn.commit()
+        return int(cur.lastrowid)  # type: ignore[return-value]
+
+    def _link_fact_entity(self, fact_id: int, entity_id: int) -> None:
+        """Insert into fact_entities, silently ignore if the link already exists."""
+        self._conn.execute(
+            """
+            INSERT OR IGNORE INTO fact_entities (fact_id, entity_id)
+            VALUES (?, ?)
+            """,
+            (fact_id, entity_id),
+        )
+        self._conn.commit()
+
+    def _compute_hrr_vector(self, fact_id: int, content: str) -> None:
+        """Compute and store HRR vector for a fact. No-op if numpy unavailable."""
+        with self._lock:
+            if not self._hrr_available:
+                return
+
+            # Get entities linked to this fact
+            rows = self._conn.execute(
+                """
+                SELECT e.name FROM entities e
+                JOIN fact_entities fe ON fe.entity_id = e.entity_id
+                WHERE fe.fact_id = ?
+                """,
+                (fact_id,),
+            ).fetchall()
+            entities = [row["name"] for row in rows]
+
+            vector = hrr.encode_fact(content, entities, self.hrr_dim)
+            self._conn.execute(
+                "UPDATE facts SET hrr_vector = ? WHERE fact_id = ?",
+                (hrr.phases_to_bytes(vector), fact_id),
+            )
+            self._conn.commit()
+
+    def _rebuild_bank(self, category: str) -> None:
+        """Full rebuild of a category's memory bank from all its fact vectors."""
+        with self._lock:
+            if not self._hrr_available:
+                return
+
+            bank_name = f"cat:{category}"
+            rows = self._conn.execute(
+                "SELECT hrr_vector FROM facts WHERE category = ? AND hrr_vector IS NOT NULL",
+                (category,),
+            ).fetchall()
+
+            if not rows:
+                self._conn.execute("DELETE FROM memory_banks WHERE bank_name = ?", (bank_name,))
+                self._conn.commit()
+                return
+
+            vectors = [hrr.bytes_to_phases(row["hrr_vector"]) for row in rows]
+            bank_vector = hrr.bundle(*vectors)
+            fact_count = len(vectors)
+
+            # Check SNR
+            hrr.snr_estimate(self.hrr_dim, fact_count)
+
+            self._conn.execute(
+                """
+                INSERT INTO memory_banks (bank_name, vector, dim, fact_count, updated_at)
+                VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
+                ON CONFLICT(bank_name) DO UPDATE SET
+                    vector = excluded.vector,
+                    dim = excluded.dim,
+                    fact_count = excluded.fact_count,
+                    updated_at = excluded.updated_at
+                """,
+                (bank_name, hrr.phases_to_bytes(bank_vector), self.hrr_dim, fact_count),
+            )
+            self._conn.commit()
+
+    def rebuild_all_vectors(self, dim: int | None = None) -> int:
+        """Recompute all HRR vectors + banks from text. For recovery/migration.
+
+        Returns the number of facts processed.
+        """
+        with self._lock:
+            if not self._hrr_available:
+                return 0
+
+            if dim is not None:
+                self.hrr_dim = dim
+
+            rows = self._conn.execute(
+                "SELECT fact_id, content, category FROM facts"
+            ).fetchall()
+
+            categories: set[str] = set()
+            for row in rows:
+                self._compute_hrr_vector(row["fact_id"], row["content"])
+                categories.add(row["category"])
+
+            for category in categories:
+                self._rebuild_bank(category)
+
+            return len(rows)
+
+    # ------------------------------------------------------------------
+    # Utilities
+    # ------------------------------------------------------------------
+
+    def _row_to_dict(self, row: sqlite3.Row) -> dict:
+        """Convert a sqlite3.Row to a plain dict."""
+        return dict(row)
+
+    def close(self) -> None:
+        """Close the database connection."""
+        self._conn.close()
+
+    def __enter__(self) -> "MemoryStore":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()

plugins/hindsight-memory/__init__.py

@@ -0,0 +1,315 @@
+"""Hindsight memory plugin — MemoryProvider interface.
+
+Long-term memory with knowledge graph, entity resolution, and multi-strategy
+retrieval. Supports cloud (API key) and local (embedded PostgreSQL) modes.
+
+Original PR #1811 by benfrank241, adapted to MemoryProvider ABC.
+
+Config via environment variables:
+  HINDSIGHT_API_KEY   — API key for Hindsight Cloud
+  HINDSIGHT_BANK_ID   — memory bank identifier (default: hermes)
+  HINDSIGHT_BUDGET    — recall budget: low/mid/high (default: mid)
+  HINDSIGHT_API_URL   — API endpoint
+  HINDSIGHT_MODE      — cloud or local (default: cloud)
+
+Or via ~/.hindsight/config.json (written by the original setup wizard).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import queue
+import threading
+from typing import Any, Dict, List
+
+from agent.memory_provider import MemoryProvider
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_API_URL = "https://api.hindsight.vectorize.io"
+_VALID_BUDGETS = {"low", "mid", "high"}
+
+
+# ---------------------------------------------------------------------------
+# Thread helper (from original PR — avoids aiohttp event loop conflicts)
+# ---------------------------------------------------------------------------
+
+def _run_in_thread(fn, timeout: float = 30.0):
+    result_q: queue.Queue = queue.Queue(maxsize=1)
+
+    def _run():
+        import asyncio
+        asyncio.set_event_loop(None)
+        try:
+            result_q.put(("ok", fn()))
+        except Exception as exc:
+            result_q.put(("err", exc))
+
+    t = threading.Thread(target=_run, daemon=True, name="hindsight-call")
+    t.start()
+    kind, value = result_q.get(timeout=timeout)
+    if kind == "err":
+        raise value
+    return value
+
+
+# ---------------------------------------------------------------------------
+# Tool schemas
+# ---------------------------------------------------------------------------
+
+RETAIN_SCHEMA = {
+    "name": "hindsight_retain",
+    "description": (
+        "Store information to long-term memory. Hindsight automatically "
+        "extracts structured facts, resolves entities, and indexes for retrieval."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "content": {"type": "string", "description": "The information to store."},
+            "context": {"type": "string", "description": "Short label (e.g. 'user preference', 'project decision')."},
+        },
+        "required": ["content"],
+    },
+}
+
+RECALL_SCHEMA = {
+    "name": "hindsight_recall",
+    "description": (
+        "Search long-term memory. Returns memories ranked by relevance using "
+        "semantic search, keyword matching, entity graph traversal, and reranking."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "What to search for."},
+        },
+        "required": ["query"],
+    },
+}
+
+REFLECT_SCHEMA = {
+    "name": "hindsight_reflect",
+    "description": (
+        "Synthesize a reasoned answer from long-term memories. Unlike recall, "
+        "this reasons across all stored memories to produce a coherent response."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "The question to reflect on."},
+        },
+        "required": ["query"],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+def _load_config() -> dict:
+    """Load config from ~/.hindsight/config.json, falling back to env vars."""
+    from pathlib import Path
+    config_path = Path.home() / ".hindsight" / "config.json"
+
+    if config_path.exists():
+        try:
+            return json.loads(config_path.read_text(encoding="utf-8"))
+        except Exception:
+            pass
+
+    return {
+        "mode": os.environ.get("HINDSIGHT_MODE", "cloud"),
+        "apiKey": os.environ.get("HINDSIGHT_API_KEY", ""),
+        "banks": {
+            "hermes": {
+                "bankId": os.environ.get("HINDSIGHT_BANK_ID", "hermes"),
+                "budget": os.environ.get("HINDSIGHT_BUDGET", "mid"),
+                "enabled": True,
+            }
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# MemoryProvider implementation
+# ---------------------------------------------------------------------------
+
+class HindsightMemoryProvider(MemoryProvider):
+    """Hindsight long-term memory with knowledge graph and multi-strategy retrieval."""
+
+    def __init__(self):
+        self._config = None
+        self._api_key = None
+        self._bank_id = "hermes"
+        self._budget = "mid"
+        self._mode = "cloud"
+        self._prefetch_result = ""
+        self._prefetch_lock = threading.Lock()
+        self._prefetch_thread = None
+
+    @property
+    def name(self) -> str:
+        return "hindsight"
+
+    def is_available(self) -> bool:
+        try:
+            cfg = _load_config()
+            mode = cfg.get("mode", "cloud")
+            if mode == "local":
+                embed = cfg.get("embed", {})
+                return bool(embed.get("llmApiKey") or os.environ.get("HINDSIGHT_LLM_API_KEY"))
+            api_key = cfg.get("apiKey") or os.environ.get("HINDSIGHT_API_KEY", "")
+            return bool(api_key)
+        except Exception:
+            return False
+
+    def get_config_schema(self):
+        return [
+            {"key": "mode", "description": "Cloud API or local embedded mode", "default": "cloud", "choices": ["cloud", "local"]},
+            {"key": "api_key", "description": "Hindsight Cloud API key", "secret": True, "env_var": "HINDSIGHT_API_KEY", "url": "https://app.hindsight.vectorize.io"},
+            {"key": "bank_id", "description": "Memory bank identifier", "default": "hermes"},
+            {"key": "budget", "description": "Recall thoroughness", "default": "mid", "choices": ["low", "mid", "high"]},
+            {"key": "llm_provider", "description": "LLM provider for local mode", "default": "anthropic", "choices": ["anthropic", "openai", "groq", "ollama"]},
+            {"key": "llm_api_key", "description": "LLM API key for local mode", "secret": True, "env_var": "HINDSIGHT_LLM_API_KEY"},
+            {"key": "llm_model", "description": "LLM model for local mode", "default": "claude-haiku-4-5-20251001"},
+        ]
+
+    def _make_client(self):
+        """Create a fresh Hindsight client (thread-safe)."""
+        if self._mode == "local":
+            from hindsight import HindsightEmbedded
+            embed = self._config.get("embed", {})
+            return HindsightEmbedded(
+                profile=embed.get("profile", "hermes"),
+                llm_provider=embed.get("llmProvider", ""),
+                llm_api_key=embed.get("llmApiKey", ""),
+                llm_model=embed.get("llmModel", ""),
+            )
+        from hindsight_client import Hindsight
+        return Hindsight(api_key=self._api_key, timeout=30.0)
+
+    def initialize(self, session_id: str, **kwargs) -> None:
+        self._config = _load_config()
+        self._mode = self._config.get("mode", "cloud")
+        self._api_key = self._config.get("apiKey") or os.environ.get("HINDSIGHT_API_KEY", "")
+
+        banks = self._config.get("banks", {}).get("hermes", {})
+        self._bank_id = banks.get("bankId", "hermes")
+        budget = banks.get("budget", "mid")
+        self._budget = budget if budget in _VALID_BUDGETS else "mid"
+
+        # Ensure bank exists
+        try:
+            client = _run_in_thread(self._make_client)
+            _run_in_thread(lambda: client.create_bank(bank_id=self._bank_id, name=self._bank_id))
+        except Exception:
+            pass  # Already exists
+
+    def system_prompt_block(self) -> str:
+        return (
+            f"# Hindsight Memory\n"
+            f"Active. Bank: {self._bank_id}, budget: {self._budget}.\n"
+            f"Use hindsight_recall to search, hindsight_reflect for synthesis, "
+            f"hindsight_retain to store facts."
+        )
+
+    def prefetch(self, query: str) -> str:
+        if self._prefetch_thread and self._prefetch_thread.is_alive():
+            self._prefetch_thread.join(timeout=3.0)
+        with self._prefetch_lock:
+            result = self._prefetch_result
+            self._prefetch_result = ""
+        if not result:
+            return ""
+        return f"## Hindsight Memory\n{result}"
+
+    def queue_prefetch(self, query: str) -> None:
+        def _run():
+            try:
+                client = self._make_client()
+                resp = client.recall(bank_id=self._bank_id, query=query, budget=self._budget)
+                if resp.results:
+                    text = "\n".join(r.text for r in resp.results if r.text)
+                    with self._prefetch_lock:
+                        self._prefetch_result = text
+            except Exception as e:
+                logger.debug("Hindsight prefetch failed: %s", e)
+
+        self._prefetch_thread = threading.Thread(target=_run, daemon=True, name="hindsight-prefetch")
+        self._prefetch_thread.start()
+
+    def sync_turn(self, user_content: str, assistant_content: str) -> None:
+        combined = f"User: {user_content}\nAssistant: {assistant_content}"
+        try:
+            _run_in_thread(
+                lambda: self._make_client().retain(
+                    bank_id=self._bank_id, content=combined, context="conversation"
+                )
+            )
+        except Exception as e:
+            logger.warning("Hindsight sync failed: %s", e)
+
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        return [RETAIN_SCHEMA, RECALL_SCHEMA, REFLECT_SCHEMA]
+
+    def handle_tool_call(self, tool_name: str, args: dict, **kwargs) -> str:
+        if tool_name == "hindsight_retain":
+            content = args.get("content", "")
+            if not content:
+                return json.dumps({"error": "Missing required parameter: content"})
+            context = args.get("context")
+            try:
+                _run_in_thread(
+                    lambda: self._make_client().retain(
+                        bank_id=self._bank_id, content=content, context=context
+                    )
+                )
+                return json.dumps({"result": "Memory stored successfully."})
+            except Exception as e:
+                return json.dumps({"error": f"Failed to store memory: {e}"})
+
+        elif tool_name == "hindsight_recall":
+            query = args.get("query", "")
+            if not query:
+                return json.dumps({"error": "Missing required parameter: query"})
+            try:
+                resp = _run_in_thread(
+                    lambda: self._make_client().recall(
+                        bank_id=self._bank_id, query=query, budget=self._budget
+                    )
+                )
+                if not resp.results:
+                    return json.dumps({"result": "No relevant memories found."})
+                lines = [f"{i}. {r.text}" for i, r in enumerate(resp.results, 1)]
+                return json.dumps({"result": "\n".join(lines)})
+            except Exception as e:
+                return json.dumps({"error": f"Failed to search memory: {e}"})
+
+        elif tool_name == "hindsight_reflect":
+            query = args.get("query", "")
+            if not query:
+                return json.dumps({"error": "Missing required parameter: query"})
+            try:
+                resp = _run_in_thread(
+                    lambda: self._make_client().reflect(
+                        bank_id=self._bank_id, query=query, budget=self._budget
+                    )
+                )
+                return json.dumps({"result": resp.text or "No relevant memories found."})
+            except Exception as e:
+                return json.dumps({"error": f"Failed to reflect: {e}"})
+
+        return json.dumps({"error": f"Unknown tool: {tool_name}"})
+
+    def shutdown(self) -> None:
+        if self._prefetch_thread and self._prefetch_thread.is_alive():
+            self._prefetch_thread.join(timeout=5.0)
+
+
+def register(ctx) -> None:
+    """Register Hindsight as a memory provider plugin."""
+    ctx.register_memory_provider(HindsightMemoryProvider())

plugins/hindsight-memory/plugin.yaml

@@ -0,0 +1,8 @@
+name: hindsight-memory
+version: 1.0.0
+description: >
+  Long-term memory via Hindsight — knowledge graph with entity resolution,
+  multi-strategy retrieval (semantic + BM25 + graph + temporal), and
+  cross-encoder reranking. Cloud or local mode.
+requires_env:
+  - HINDSIGHT_API_KEY

plugins/mem0-memory/__init__.py

@@ -0,0 +1,294 @@
+"""Mem0 memory plugin — MemoryProvider interface.
+
+Server-side LLM fact extraction, semantic search with reranking, and
+automatic deduplication via the Mem0 Platform API.
+
+Original PR #2933 by kartik-mem0, adapted to MemoryProvider ABC.
+
+Config via environment variables:
+  MEM0_API_KEY       — Mem0 Platform API key (required)
+  MEM0_USER_ID       — User identifier (default: hermes-user)
+  MEM0_AGENT_ID      — Agent identifier (default: hermes)
+
+Or via $HERMES_HOME/mem0.json.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+from pathlib import Path
+from typing import Any, Dict, List
+
+from agent.memory_provider import MemoryProvider
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+def _load_config() -> dict:
+    """Load config from $HERMES_HOME/mem0.json or env vars."""
+    hermes_home = os.environ.get("HERMES_HOME", os.path.expanduser("~/.hermes"))
+    config_path = Path(hermes_home) / "mem0.json"
+
+    if config_path.exists():
+        try:
+            return json.loads(config_path.read_text(encoding="utf-8"))
+        except Exception:
+            pass
+
+    return {
+        "api_key": os.environ.get("MEM0_API_KEY", ""),
+        "user_id": os.environ.get("MEM0_USER_ID", "hermes-user"),
+        "agent_id": os.environ.get("MEM0_AGENT_ID", "hermes"),
+        "rerank": True,
+        "keyword_search": False,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Tool schemas
+# ---------------------------------------------------------------------------
+
+PROFILE_SCHEMA = {
+    "name": "mem0_profile",
+    "description": (
+        "Retrieve all stored memories about the user — preferences, facts, "
+        "project context. Fast, no reranking. Use at conversation start."
+    ),
+    "parameters": {"type": "object", "properties": {}, "required": []},
+}
+
+SEARCH_SCHEMA = {
+    "name": "mem0_search",
+    "description": (
+        "Search memories by meaning. Returns relevant facts ranked by similarity. "
+        "Set rerank=true for higher accuracy (+150ms)."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "What to search for."},
+            "rerank": {"type": "boolean", "description": "Enable reranking for precision (default: false)."},
+            "top_k": {"type": "integer", "description": "Max results (default: 10, max: 50)."},
+        },
+        "required": ["query"],
+    },
+}
+
+CONTEXT_SCHEMA = {
+    "name": "mem0_context",
+    "description": (
+        "Deep retrieval with forced reranking. Use when you need the most "
+        "relevant memories for a specific topic."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "What to search for."},
+        },
+        "required": ["query"],
+    },
+}
+
+CONCLUDE_SCHEMA = {
+    "name": "mem0_conclude",
+    "description": (
+        "Store a durable fact about the user. Stored verbatim (no LLM extraction). "
+        "Use for explicit preferences, corrections, or decisions."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "conclusion": {"type": "string", "description": "The fact to store."},
+        },
+        "required": ["conclusion"],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# MemoryProvider implementation
+# ---------------------------------------------------------------------------
+
+class Mem0MemoryProvider(MemoryProvider):
+    """Mem0 Platform memory with server-side extraction and semantic search."""
+
+    def __init__(self):
+        self._config = None
+        self._client = None
+        self._api_key = ""
+        self._user_id = "hermes-user"
+        self._agent_id = "hermes"
+        self._rerank = True
+        self._prefetch_result = ""
+        self._prefetch_lock = threading.Lock()
+        self._prefetch_thread = None
+
+    @property
+    def name(self) -> str:
+        return "mem0"
+
+    def is_available(self) -> bool:
+        cfg = _load_config()
+        return bool(cfg.get("api_key"))
+
+    def get_config_schema(self):
+        return [
+            {"key": "api_key", "description": "Mem0 Platform API key", "secret": True, "required": True, "env_var": "MEM0_API_KEY", "url": "https://app.mem0.ai"},
+            {"key": "user_id", "description": "User identifier", "default": "hermes-user"},
+            {"key": "agent_id", "description": "Agent identifier", "default": "hermes"},
+            {"key": "rerank", "description": "Enable reranking for recall", "default": "true", "choices": ["true", "false"]},
+        ]
+
+    def _get_client(self):
+        if self._client is not None:
+            return self._client
+        try:
+            from mem0 import MemoryClient
+            self._client = MemoryClient(api_key=self._api_key)
+            return self._client
+        except ImportError:
+            raise RuntimeError("mem0 package not installed. Run: pip install mem0ai")
+
+    def initialize(self, session_id: str, **kwargs) -> None:
+        self._config = _load_config()
+        self._api_key = self._config.get("api_key", "")
+        self._user_id = self._config.get("user_id", "hermes-user")
+        self._agent_id = self._config.get("agent_id", "hermes")
+        self._rerank = self._config.get("rerank", True)
+
+    def system_prompt_block(self) -> str:
+        return (
+            "# Mem0 Memory\n"
+            f"Active. User: {self._user_id}.\n"
+            "Use mem0_search to find memories, mem0_conclude to store facts, "
+            "mem0_profile for a full overview."
+        )
+
+    def prefetch(self, query: str) -> str:
+        if self._prefetch_thread and self._prefetch_thread.is_alive():
+            self._prefetch_thread.join(timeout=3.0)
+        with self._prefetch_lock:
+            result = self._prefetch_result
+            self._prefetch_result = ""
+        if not result:
+            return ""
+        return f"## Mem0 Memory\n{result}"
+
+    def queue_prefetch(self, query: str) -> None:
+        def _run():
+            try:
+                client = self._get_client()
+                results = client.search(
+                    query=query,
+                    user_id=self._user_id,
+                    rerank=self._rerank,
+                    top_k=5,
+                )
+                if results:
+                    lines = [r.get("memory", "") for r in results if r.get("memory")]
+                    with self._prefetch_lock:
+                        self._prefetch_result = "\n".join(f"- {l}" for l in lines)
+            except Exception as e:
+                logger.debug("Mem0 prefetch failed: %s", e)
+
+        self._prefetch_thread = threading.Thread(target=_run, daemon=True, name="mem0-prefetch")
+        self._prefetch_thread.start()
+
+    def sync_turn(self, user_content: str, assistant_content: str) -> None:
+        """Send the turn to Mem0 for server-side fact extraction."""
+        try:
+            client = self._get_client()
+            messages = [
+                {"role": "user", "content": user_content},
+                {"role": "assistant", "content": assistant_content},
+            ]
+            client.add(messages, user_id=self._user_id, agent_id=self._agent_id)
+        except Exception as e:
+            logger.warning("Mem0 sync failed: %s", e)
+
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        return [PROFILE_SCHEMA, SEARCH_SCHEMA, CONTEXT_SCHEMA, CONCLUDE_SCHEMA]
+
+    def handle_tool_call(self, tool_name: str, args: dict, **kwargs) -> str:
+        try:
+            client = self._get_client()
+        except Exception as e:
+            return json.dumps({"error": str(e)})
+
+        if tool_name == "mem0_profile":
+            try:
+                memories = client.get_all(user_id=self._user_id)
+                if not memories:
+                    return json.dumps({"result": "No memories stored yet."})
+                lines = [m.get("memory", "") for m in memories if m.get("memory")]
+                return json.dumps({"result": "\n".join(lines), "count": len(lines)})
+            except Exception as e:
+                return json.dumps({"error": f"Failed to fetch profile: {e}"})
+
+        elif tool_name == "mem0_search":
+            query = args.get("query", "")
+            if not query:
+                return json.dumps({"error": "Missing required parameter: query"})
+            rerank = args.get("rerank", False)
+            top_k = min(int(args.get("top_k", 10)), 50)
+            try:
+                results = client.search(
+                    query=query, user_id=self._user_id,
+                    rerank=rerank, top_k=top_k,
+                )
+                if not results:
+                    return json.dumps({"result": "No relevant memories found."})
+                items = [{"memory": r.get("memory", ""), "score": r.get("score", 0)} for r in results]
+                return json.dumps({"results": items, "count": len(items)})
+            except Exception as e:
+                return json.dumps({"error": f"Search failed: {e}"})
+
+        elif tool_name == "mem0_context":
+            query = args.get("query", "")
+            if not query:
+                return json.dumps({"error": "Missing required parameter: query"})
+            try:
+                results = client.search(
+                    query=query, user_id=self._user_id,
+                    rerank=True, top_k=5,
+                )
+                if not results:
+                    return json.dumps({"result": "No relevant memories found."})
+                items = [{"memory": r.get("memory", ""), "score": r.get("score", 0)} for r in results]
+                return json.dumps({"results": items, "count": len(items)})
+            except Exception as e:
+                return json.dumps({"error": f"Context retrieval failed: {e}"})
+
+        elif tool_name == "mem0_conclude":
+            conclusion = args.get("conclusion", "")
+            if not conclusion:
+                return json.dumps({"error": "Missing required parameter: conclusion"})
+            try:
+                client.add(
+                    [{"role": "user", "content": conclusion}],
+                    user_id=self._user_id,
+                    agent_id=self._agent_id,
+                    infer=False,
+                )
+                return json.dumps({"result": "Fact stored."})
+            except Exception as e:
+                return json.dumps({"error": f"Failed to store: {e}"})
+
+        return json.dumps({"error": f"Unknown tool: {tool_name}"})
+
+    def shutdown(self) -> None:
+        if self._prefetch_thread and self._prefetch_thread.is_alive():
+            self._prefetch_thread.join(timeout=5.0)
+        self._client = None
+
+
+def register(ctx) -> None:
+    """Register Mem0 as a memory provider plugin."""
+    ctx.register_memory_provider(Mem0MemoryProvider())

plugins/mem0-memory/plugin.yaml

@@ -0,0 +1,7 @@
+name: mem0-memory
+version: 1.0.0
+description: >
+  Long-term memory via Mem0 Platform — server-side LLM fact extraction,
+  semantic search with reranking, and automatic deduplication.
+requires_env:
+  - MEM0_API_KEY

plugins/openviking-memory/__init__.py

@@ -0,0 +1,205 @@
+"""OpenViking memory plugin — MemoryProvider interface.
+
+Read-only semantic search over a self-hosted OpenViking knowledge server.
+Supports search (fast/deep/auto), URI-based content reading, and
+filesystem-style browsing.
+
+Original PR #3369 by Mibayy, adapted to MemoryProvider ABC.
+
+Config via environment variables:
+  OPENVIKING_ENDPOINT  — Server URL (default: http://127.0.0.1:1933)
+  OPENVIKING_API_KEY   — Optional API key
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Dict, List
+
+from agent.memory_provider import MemoryProvider
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Tool schemas
+# ---------------------------------------------------------------------------
+
+SEARCH_SCHEMA = {
+    "name": "viking_search",
+    "description": (
+        "Semantic search over OpenViking knowledge base. "
+        "Returns ranked results with URIs for deeper reading."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "Search query."},
+            "mode": {
+                "type": "string", "enum": ["auto", "fast", "deep"],
+                "description": "Search depth (default: auto).",
+            },
+            "scope": {"type": "string", "description": "URI prefix to scope search."},
+            "limit": {"type": "integer", "description": "Max results (default: 10)."},
+        },
+        "required": ["query"],
+    },
+}
+
+READ_SCHEMA = {
+    "name": "viking_read",
+    "description": (
+        "Read content at a viking:// URI. Supports three detail levels: "
+        "abstract (summary), overview (key points), read (full content)."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "uri": {"type": "string", "description": "viking:// URI to read."},
+            "level": {
+                "type": "string", "enum": ["abstract", "overview", "read"],
+                "description": "Detail level (default: overview).",
+            },
+        },
+        "required": ["uri"],
+    },
+}
+
+BROWSE_SCHEMA = {
+    "name": "viking_browse",
+    "description": (
+        "Browse the OpenViking knowledge store like a filesystem. "
+        "Supports tree (hierarchy), list (directory), and stat (metadata)."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string", "enum": ["tree", "list", "stat"],
+                "description": "Browse action.",
+            },
+            "path": {"type": "string", "description": "Path to browse (default: root)."},
+        },
+        "required": ["action"],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# MemoryProvider implementation
+# ---------------------------------------------------------------------------
+
+class OpenVikingMemoryProvider(MemoryProvider):
+    """Read-only memory via OpenViking self-hosted knowledge server."""
+
+    def __init__(self):
+        self._endpoint = ""
+        self._api_key = ""
+
+    @property
+    def name(self) -> str:
+        return "openviking"
+
+    def get_config_schema(self):
+        return [
+            {"key": "endpoint", "description": "OpenViking server URL", "required": True, "default": "http://127.0.0.1:1933"},
+            {"key": "api_key", "description": "OpenViking API key (if server requires auth)", "secret": True, "env_var": "OPENVIKING_API_KEY"},
+        ]
+
+    def is_available(self) -> bool:
+        endpoint = os.environ.get("OPENVIKING_ENDPOINT", "")
+        if not endpoint:
+            return False
+        # Quick health check
+        try:
+            import httpx
+            resp = httpx.get(f"{endpoint}/health", timeout=3.0)
+            return resp.status_code == 200
+        except Exception:
+            return False
+
+    def initialize(self, session_id: str, **kwargs) -> None:
+        self._endpoint = os.environ.get("OPENVIKING_ENDPOINT", "http://127.0.0.1:1933")
+        self._api_key = os.environ.get("OPENVIKING_API_KEY", "")
+
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json"}
+        if self._api_key:
+            h["X-API-Key"] = self._api_key
+        return h
+
+    def system_prompt_block(self) -> str:
+        return (
+            "# OpenViking Knowledge Base\n"
+            f"Active. Endpoint: {self._endpoint}\n"
+            "Use viking_search to find information, viking_read for details, "
+            "viking_browse to explore the knowledge tree."
+        )
+
+    def prefetch(self, query: str) -> str:
+        """OpenViking is tool-driven, no automatic prefetch."""
+        return ""
+
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        return [SEARCH_SCHEMA, READ_SCHEMA, BROWSE_SCHEMA]
+
+    def handle_tool_call(self, tool_name: str, args: dict, **kwargs) -> str:
+        try:
+            import httpx
+        except ImportError:
+            return json.dumps({"error": "httpx not installed"})
+
+        try:
+            if tool_name == "viking_search":
+                return self._search(httpx, args)
+            elif tool_name == "viking_read":
+                return self._read(httpx, args)
+            elif tool_name == "viking_browse":
+                return self._browse(httpx, args)
+            return json.dumps({"error": f"Unknown tool: {tool_name}"})
+        except Exception as e:
+            return json.dumps({"error": str(e)})
+
+    def _search(self, httpx, args: dict) -> str:
+        query = args.get("query", "")
+        if not query:
+            return json.dumps({"error": "query is required"})
+        payload = {"query": query, "mode": args.get("mode", "auto")}
+        if args.get("scope"):
+            payload["scope"] = args["scope"]
+        if args.get("limit"):
+            payload["limit"] = args["limit"]
+        resp = httpx.post(
+            f"{self._endpoint}/v1/search",
+            json=payload, headers=self._headers(), timeout=30.0,
+        )
+        return resp.text
+
+    def _read(self, httpx, args: dict) -> str:
+        uri = args.get("uri", "")
+        if not uri:
+            return json.dumps({"error": "uri is required"})
+        level = args.get("level", "overview")
+        resp = httpx.post(
+            f"{self._endpoint}/v1/read",
+            json={"uri": uri, "level": level},
+            headers=self._headers(), timeout=30.0,
+        )
+        return resp.text
+
+    def _browse(self, httpx, args: dict) -> str:
+        action = args.get("action", "tree")
+        path = args.get("path", "/")
+        resp = httpx.post(
+            f"{self._endpoint}/v1/browse",
+            json={"action": action, "path": path},
+            headers=self._headers(), timeout=30.0,
+        )
+        return resp.text
+
+
+def register(ctx) -> None:
+    """Register OpenViking as a memory provider plugin."""
+    ctx.register_memory_provider(OpenVikingMemoryProvider())

plugins/openviking-memory/plugin.yaml

@@ -0,0 +1,7 @@
+name: openviking-memory
+version: 1.0.0
+description: >
+  Read-only memory via OpenViking — semantic search, URI-based content
+  reading, and filesystem browsing over a self-hosted knowledge server.
+requires_env:
+  - OPENVIKING_ENDPOINT

plugins/retaindb-memory/__init__.py

@@ -0,0 +1,280 @@
+"""RetainDB memory plugin — MemoryProvider interface.
+
+Cross-session memory via RetainDB cloud API. Durable write-behind queue,
+semantic search with deduplication, and user profile retrieval.
+
+Original PR #2732 by Alinxus, adapted to MemoryProvider ABC.
+
+Config via environment variables:
+  RETAINDB_API_KEY    — API key (required)
+  RETAINDB_BASE_URL   — API endpoint (default: https://api.retaindb.com)
+  RETAINDB_PROJECT    — Project identifier (default: hermes)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+from typing import Any, Dict, List
+
+from agent.memory_provider import MemoryProvider
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_BASE_URL = "https://api.retaindb.com"
+
+
+# ---------------------------------------------------------------------------
+# Tool schemas
+# ---------------------------------------------------------------------------
+
+PROFILE_SCHEMA = {
+    "name": "retaindb_profile",
+    "description": "Get the user's stable profile — preferences, facts, and patterns.",
+    "parameters": {"type": "object", "properties": {}, "required": []},
+}
+
+SEARCH_SCHEMA = {
+    "name": "retaindb_search",
+    "description": (
+        "Semantic search across stored memories. Returns ranked results "
+        "with relevance scores."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "What to search for."},
+            "top_k": {"type": "integer", "description": "Max results (default: 8, max: 20)."},
+        },
+        "required": ["query"],
+    },
+}
+
+CONTEXT_SCHEMA = {
+    "name": "retaindb_context",
+    "description": "Synthesized 'what matters now' context block for the current task.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "Current task or question."},
+        },
+        "required": ["query"],
+    },
+}
+
+REMEMBER_SCHEMA = {
+    "name": "retaindb_remember",
+    "description": "Persist an explicit fact or preference to long-term memory.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "content": {"type": "string", "description": "The fact to remember."},
+            "memory_type": {
+                "type": "string",
+                "enum": ["preference", "fact", "decision", "context"],
+                "description": "Category (default: fact).",
+            },
+            "importance": {
+                "type": "number",
+                "description": "Importance 0-1 (default: 0.5).",
+            },
+        },
+        "required": ["content"],
+    },
+}
+
+FORGET_SCHEMA = {
+    "name": "retaindb_forget",
+    "description": "Delete a specific memory by ID.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "memory_id": {"type": "string", "description": "Memory ID to delete."},
+        },
+        "required": ["memory_id"],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# MemoryProvider implementation
+# ---------------------------------------------------------------------------
+
+class RetainDBMemoryProvider(MemoryProvider):
+    """RetainDB cloud memory with write-behind queue and semantic search."""
+
+    def __init__(self):
+        self._api_key = ""
+        self._base_url = _DEFAULT_BASE_URL
+        self._project = "hermes"
+        self._user_id = ""
+        self._prefetch_result = ""
+        self._prefetch_lock = threading.Lock()
+        self._prefetch_thread = None
+
+    @property
+    def name(self) -> str:
+        return "retaindb"
+
+    def is_available(self) -> bool:
+        return bool(os.environ.get("RETAINDB_API_KEY"))
+
+    def get_config_schema(self):
+        return [
+            {"key": "api_key", "description": "RetainDB API key", "secret": True, "required": True, "env_var": "RETAINDB_API_KEY", "url": "https://retaindb.com"},
+            {"key": "base_url", "description": "API endpoint", "default": "https://api.retaindb.com"},
+            {"key": "project", "description": "Project identifier", "default": "hermes"},
+        ]
+
+    def _headers(self) -> dict:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def _api(self, method: str, path: str, **kwargs):
+        """Make an API call to RetainDB."""
+        import requests
+        url = f"{self._base_url}{path}"
+        resp = requests.request(method, url, headers=self._headers(), timeout=30, **kwargs)
+        resp.raise_for_status()
+        return resp.json()
+
+    def initialize(self, session_id: str, **kwargs) -> None:
+        self._api_key = os.environ.get("RETAINDB_API_KEY", "")
+        self._base_url = os.environ.get("RETAINDB_BASE_URL", _DEFAULT_BASE_URL)
+        self._project = os.environ.get("RETAINDB_PROJECT", "hermes")
+        self._user_id = kwargs.get("user_id", "default")
+        self._session_id = session_id
+
+    def system_prompt_block(self) -> str:
+        return (
+            "# RetainDB Memory\n"
+            f"Active. Project: {self._project}.\n"
+            "Use retaindb_search to find memories, retaindb_remember to store facts, "
+            "retaindb_profile for a user overview, retaindb_context for task-relevant context."
+        )
+
+    def prefetch(self, query: str) -> str:
+        if self._prefetch_thread and self._prefetch_thread.is_alive():
+            self._prefetch_thread.join(timeout=3.0)
+        with self._prefetch_lock:
+            result = self._prefetch_result
+            self._prefetch_result = ""
+        if not result:
+            return ""
+        return f"## RetainDB Memory\n{result}"
+
+    def queue_prefetch(self, query: str) -> None:
+        def _run():
+            try:
+                data = self._api("POST", "/v1/recall", json={
+                    "project": self._project,
+                    "query": query,
+                    "user_id": self._user_id,
+                    "top_k": 5,
+                })
+                results = data.get("results", [])
+                if results:
+                    lines = [r.get("content", "") for r in results if r.get("content")]
+                    with self._prefetch_lock:
+                        self._prefetch_result = "\n".join(f"- {l}" for l in lines)
+            except Exception as e:
+                logger.debug("RetainDB prefetch failed: %s", e)
+
+        self._prefetch_thread = threading.Thread(target=_run, daemon=True, name="retaindb-prefetch")
+        self._prefetch_thread.start()
+
+    def sync_turn(self, user_content: str, assistant_content: str) -> None:
+        try:
+            self._api("POST", "/v1/ingest", json={
+                "project": self._project,
+                "user_id": self._user_id,
+                "session_id": self._session_id,
+                "messages": [
+                    {"role": "user", "content": user_content},
+                    {"role": "assistant", "content": assistant_content},
+                ],
+            })
+        except Exception as e:
+            logger.warning("RetainDB sync failed: %s", e)
+
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        return [PROFILE_SCHEMA, SEARCH_SCHEMA, CONTEXT_SCHEMA, REMEMBER_SCHEMA, FORGET_SCHEMA]
+
+    def handle_tool_call(self, tool_name: str, args: dict, **kwargs) -> str:
+        try:
+            if tool_name == "retaindb_profile":
+                data = self._api("GET", f"/v1/profile/{self._project}/{self._user_id}")
+                return json.dumps(data)
+
+            elif tool_name == "retaindb_search":
+                query = args.get("query", "")
+                if not query:
+                    return json.dumps({"error": "query is required"})
+                data = self._api("POST", "/v1/search", json={
+                    "project": self._project,
+                    "user_id": self._user_id,
+                    "query": query,
+                    "top_k": min(int(args.get("top_k", 8)), 20),
+                })
+                return json.dumps(data)
+
+            elif tool_name == "retaindb_context":
+                query = args.get("query", "")
+                if not query:
+                    return json.dumps({"error": "query is required"})
+                data = self._api("POST", "/v1/recall", json={
+                    "project": self._project,
+                    "user_id": self._user_id,
+                    "query": query,
+                    "top_k": 5,
+                })
+                return json.dumps(data)
+
+            elif tool_name == "retaindb_remember":
+                content = args.get("content", "")
+                if not content:
+                    return json.dumps({"error": "content is required"})
+                data = self._api("POST", "/v1/remember", json={
+                    "project": self._project,
+                    "user_id": self._user_id,
+                    "content": content,
+                    "memory_type": args.get("memory_type", "fact"),
+                    "importance": float(args.get("importance", 0.5)),
+                })
+                return json.dumps(data)
+
+            elif tool_name == "retaindb_forget":
+                memory_id = args.get("memory_id", "")
+                if not memory_id:
+                    return json.dumps({"error": "memory_id is required"})
+                data = self._api("DELETE", f"/v1/memory/{memory_id}")
+                return json.dumps(data)
+
+            return json.dumps({"error": f"Unknown tool: {tool_name}"})
+        except Exception as e:
+            return json.dumps({"error": str(e)})
+
+    def on_memory_write(self, action: str, target: str, content: str) -> None:
+        if action == "add":
+            try:
+                self._api("POST", "/v1/remember", json={
+                    "project": self._project,
+                    "user_id": self._user_id,
+                    "content": content,
+                    "memory_type": "preference" if target == "user" else "fact",
+                })
+            except Exception as e:
+                logger.debug("RetainDB memory bridge failed: %s", e)
+
+    def shutdown(self) -> None:
+        if self._prefetch_thread and self._prefetch_thread.is_alive():
+            self._prefetch_thread.join(timeout=5.0)
+
+
+def register(ctx) -> None:
+    """Register RetainDB as a memory provider plugin."""
+    ctx.register_memory_provider(RetainDBMemoryProvider())

plugins/retaindb-memory/plugin.yaml

@@ -0,0 +1,7 @@
+name: retaindb-memory
+version: 1.0.0
+description: >
+  Cross-session memory via RetainDB — durable write-behind queue, semantic
+  search with deduplication, user identity resolution, and profile retrieval.
+requires_env:
+  - RETAINDB_API_KEY

run_agent.py

@@ -1043,7 +1043,20 @@ class AIAgent:
                     self._memory_store.load_from_disk()
             except Exception:
                 pass  # Memory is optional -- don't break agent init
-        
+
+        # Memory provider manager — orchestrates built-in + plugin providers.
+        # Existing Honcho code stays as-is (will migrate in a follow-up PR).
+        # The manager provides the extension point for plugin memory backends.
+        from agent.memory_manager import MemoryManager
+        from agent.builtin_memory_provider import BuiltinMemoryProvider
+        self._memory_manager = MemoryManager()
+        self._memory_manager.add_provider(BuiltinMemoryProvider(
+            memory_store=self._memory_store,
+            memory_enabled=self._memory_enabled,
+            user_profile_enabled=self._user_profile_enabled,
+        ))
+        # Plugin memory providers are added after Honcho init (below).
+
         # Honcho AI-native memory (cross-session user modeling)
         # Reads $HERMES_HOME/honcho.json (instance) or ~/.honcho/config.json (global).
         self._honcho = None  # HonchoSessionManager | None
@@ -1114,6 +1127,53 @@ class AIAgent:
                 self._user_profile_enabled = False
                 logger.debug("peer %s memory_mode=honcho: local USER.md writes disabled", _hcfg.peer_name or "user")
 
+        # Register plugin memory providers with the manager.
+        # At most ONE external provider is active at a time (configured via
+        # memory.provider in config.yaml). Auto-detected from plugins that
+        # called ctx.register_memory_provider() during discover_and_load().
+        _configured_provider = mem_config.get("provider", "") if not skip_memory else ""
+        if _configured_provider and not skip_memory:
+            try:
+                from hermes_cli.plugins import get_plugin_memory_providers
+                _found = False
+                for plugin_provider in get_plugin_memory_providers():
+                    _pname = getattr(plugin_provider, "name", "unknown")
+                    if _pname != _configured_provider:
+                        logger.debug(
+                            "Memory provider '%s' skipped (config selects '%s')",
+                            _pname, _configured_provider,
+                        )
+                        continue
+                    try:
+                        if plugin_provider.is_available():
+                            self._memory_manager.add_provider(plugin_provider)
+                            plugin_provider.initialize(
+                                session_id=self.session_id or "",
+                                platform=self.platform,
+                                model=self.model,
+                            )
+                            _found = True
+                            if not self.quiet_mode:
+                                print(f"  Memory provider: {_pname}")
+                        else:
+                            logger.warning(
+                                "Memory provider '%s' configured but not available "
+                                "(missing credentials or dependencies)", _pname,
+                            )
+                    except Exception as e:
+                        logger.warning(
+                            "Plugin memory provider '%s' init failed: %s", _pname, e,
+                        )
+                if not _found and not self.quiet_mode:
+                    _available = [getattr(p, "name", "?") for p in get_plugin_memory_providers()]
+                    if _available:
+                        logger.warning(
+                            "memory.provider='%s' not found among registered providers: %s",
+                            _configured_provider, _available,
+                        )
+            except Exception as e:
+                logger.debug("Plugin memory provider loading skipped: %s", e)
+
         # Skills config: nudge interval for skill creation reminders
         self._skill_nudge_interval = 10
         try:
@@ -2659,6 +2719,19 @@ class AIAgent:
                 if user_block:
                     prompt_parts.append(user_block)
 
+        # Plugin memory providers contribute system prompt blocks.
+        # (Builtin provider's block is already handled above via _memory_store.)
+        if hasattr(self, "_memory_manager"):
+            for provider in self._memory_manager.providers:
+                if provider.name == "builtin":
+                    continue  # already handled above
+                try:
+                    block = provider.system_prompt_block()
+                    if block and block.strip():
+                        prompt_parts.append(block)
+                except Exception as e:
+                    logger.debug("Memory provider '%s' prompt block failed: %s", provider.name, e)
+
         has_skills_tools = any(name in self.valid_tool_names for name in ['skills_list', 'skill_view', 'skill_manage'])
         if has_skills_tools:
             avail_toolsets = {
@@ -6099,6 +6172,23 @@ class AIAgent:
             except Exception as e:
                 logger.debug("Honcho prefetch failed (non-fatal): %s", e)
 
+        # Plugin memory provider prefetch (non-builtin providers only).
+        self._plugin_memory_context = ""
+        self._plugin_memory_turn_context = ""
+        if hasattr(self, "_memory_manager"):
+            for provider in self._memory_manager.providers:
+                if provider.name == "builtin":
+                    continue
+                try:
+                    ctx = provider.prefetch(original_user_message)
+                    if ctx and ctx.strip():
+                        if not conversation_history:
+                            self._plugin_memory_context += ("\n\n" + ctx if self._plugin_memory_context else ctx)
+                        else:
+                            self._plugin_memory_turn_context += ("\n\n" + ctx if self._plugin_memory_turn_context else ctx)
+                except Exception as e:
+                    logger.debug("Memory provider '%s' prefetch failed: %s", provider.name, e)
+
         # Add user message
         user_msg = {"role": "user", "content": user_message}
         messages.append(user_msg)
@@ -6142,6 +6232,11 @@ class AIAgent:
                     self._cached_system_prompt = (
                         self._cached_system_prompt + "\n\n" + self._honcho_context
                     ).strip()
+                # Plugin memory provider context (first turn → bake into system prompt)
+                if self._plugin_memory_context:
+                    self._cached_system_prompt = (
+                        self._cached_system_prompt + "\n\n" + self._plugin_memory_context
+                    ).strip()
 
                 # Plugin hook: on_session_start
                 # Fired once when a brand-new session is created (not on
@@ -6312,6 +6407,15 @@ class AIAgent:
                         api_msg.get("content", ""), self._honcho_turn_context
                     )
 
+                # Plugin memory provider turn context injection
+                if idx == current_turn_user_idx and msg.get("role") == "user" and self._plugin_memory_turn_context:
+                    existing = api_msg.get("content", "")
+                    api_msg["content"] = (
+                        existing
+                        + "\n\n[Plugin memory context — relevant memories for this turn.]\n\n"
+                        + self._plugin_memory_turn_context
+                    )
+
                 # For ALL assistant messages, pass reasoning back to the API
                 # This ensures multi-turn reasoning context is preserved
                 if msg.get("role") == "assistant":
@@ -6924,8 +7028,10 @@ class AIAgent:
                         print(f"{self.log_prefix}   Auth method: {auth_method}")
                         print(f"{self.log_prefix}   Token prefix: {key[:12]}..." if key and len(key) > 12 else f"{self.log_prefix}   Token: (empty or short)")
                         print(f"{self.log_prefix}   Troubleshooting:")
-                        print(f"{self.log_prefix}     • Check ANTHROPIC_TOKEN in ~/.hermes/.env for Hermes-managed OAuth/setup tokens")
-                        print(f"{self.log_prefix}     • Check ANTHROPIC_API_KEY in ~/.hermes/.env for API keys or legacy token values")
+                        from hermes_constants import display_hermes_home as _dhh_fn
+                        _dhh = _dhh_fn()
+                        print(f"{self.log_prefix}     • Check ANTHROPIC_TOKEN in {_dhh}/.env for Hermes-managed OAuth/setup tokens")
+                        print(f"{self.log_prefix}     • Check ANTHROPIC_API_KEY in {_dhh}/.env for API keys or legacy token values")
                         print(f"{self.log_prefix}     • For API keys: verify at https://console.anthropic.com/settings/keys")
                         print(f"{self.log_prefix}     • For Claude Code: run 'claude /login' to refresh, then retry")
                         print(f"{self.log_prefix}     • Clear stale keys: hermes config set ANTHROPIC_TOKEN \"\"")
@@ -7947,6 +8053,17 @@ class AIAgent:
             self._honcho_sync(original_user_message, final_response)
             self._queue_honcho_prefetch(original_user_message)
 
+        # Sync to plugin memory providers and queue prefetch for next turn
+        if final_response and not interrupted and hasattr(self, "_memory_manager"):
+            for provider in self._memory_manager.providers:
+                if provider.name == "builtin":
+                    continue
+                try:
+                    provider.sync_turn(original_user_message, final_response)
+                    provider.queue_prefetch(original_user_message)
+                except Exception as e:
+                    logger.debug("Memory provider '%s' post-turn failed: %s", provider.name, e)
+
         # Plugin hook: post_llm_call
         # Fired once per turn after the tool-calling loop completes.
         # Plugins can use this to persist conversation data (e.g. sync

skills/productivity/google-workspace/SKILL.md

@@ -4,6 +4,11 @@ description: Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration via
 version: 1.0.0
 author: Nous Research
 license: MIT
+required_credential_files:
+  - path: google_token.json
+    description: Google OAuth2 token (created by setup script)
+  - path: google_client_secret.json
+    description: Google OAuth2 client credentials (downloaded from Google Cloud Console)
 metadata:
   hermes:
     tags: [Google, Gmail, Calendar, Drive, Sheets, Docs, Contacts, Email, OAuth]

skills/research/duckduckgo-search/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: duckduckgo-search
-description: Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Use the Python DDGS library or CLI to search, then web_extract for full content.
-version: 1.2.0
+description: Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Prefer the `ddgs` CLI when installed; use the Python DDGS library only after verifying that `ddgs` is available in the current runtime.
+version: 1.3.0
 author: gamedevCloudy
 license: MIT
 metadata:
@@ -9,26 +9,96 @@ metadata:
     tags: [search, duckduckgo, web-search, free, fallback]
     related_skills: [arxiv]
     fallback_for_toolsets: [web]
-prerequisites:
-  commands: [ddgs]
 ---
 
 # DuckDuckGo Search
 
 Free web search using DuckDuckGo. **No API key required.**
 
-Preferred when `web_search` tool is unavailable or unsuitable (no `FIRECRAWL_API_KEY` set). Can also be used as a standalone search tool.
+Preferred when `web_search` is unavailable or unsuitable (for example when `FIRECRAWL_API_KEY` is not set). Can also be used as a standalone search path when DuckDuckGo results are specifically desired.
 
-## Setup
+## Detection Flow
+
+Check what is actually available before choosing an approach:
 
 ```bash
-# Install the ddgs package (one-time)
-pip install ddgs
+# Check CLI availability
+command -v ddgs >/dev/null && echo "DDGS_CLI=installed" || echo "DDGS_CLI=missing"
 ```
 
-## Python API (Primary)
+Decision tree:
+1. If `ddgs` CLI is installed, prefer `terminal` + `ddgs`
+2. If `ddgs` CLI is missing, do not assume `execute_code` can import `ddgs`
+3. If the user wants DuckDuckGo specifically, install `ddgs` first in the relevant environment
+4. Otherwise fall back to built-in web/browser tools
 
-Use the `DDGS` class in `execute_code` for structured results with typed fields.
+Important runtime note:
+- Terminal and `execute_code` are separate runtimes
+- A successful shell install does not guarantee `execute_code` can import `ddgs`
+- Never assume third-party Python packages are preinstalled inside `execute_code`
+
+## Installation
+
+Install `ddgs` only when DuckDuckGo search is specifically needed and the runtime does not already provide it.
+
+```bash
+# Python package + CLI entrypoint
+pip install ddgs
+
+# Verify CLI
+ddgs --help
+```
+
+If a workflow depends on Python imports, verify that same runtime can import `ddgs` before using `from ddgs import DDGS`.
+
+## Method 1: CLI Search (Preferred)
+
+Use the `ddgs` command via `terminal` when it exists. This is the preferred path because it avoids assuming the `execute_code` sandbox has the `ddgs` Python package installed.
+
+```bash
+# Text search
+ddgs text -k "python async programming" -m 5
+
+# News search
+ddgs news -k "artificial intelligence" -m 5
+
+# Image search
+ddgs images -k "landscape photography" -m 10
+
+# Video search
+ddgs videos -k "python tutorial" -m 5
+
+# With region filter
+ddgs text -k "best restaurants" -m 5 -r us-en
+
+# Recent results only (d=day, w=week, m=month, y=year)
+ddgs text -k "latest AI news" -m 5 -t w
+
+# JSON output for parsing
+ddgs text -k "fastapi tutorial" -m 5 -o json
+```
+
+### CLI Flags
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `-k` | Keywords (query) — **required** | `-k "search terms"` |
+| `-m` | Max results | `-m 5` |
+| `-r` | Region | `-r us-en` |
+| `-t` | Time limit | `-t w` (week) |
+| `-s` | Safe search | `-s off` |
+| `-o` | Output format | `-o json` |
+
+## Method 2: Python API (Only After Verification)
+
+Use the `DDGS` class in `execute_code` or another Python runtime only after verifying that `ddgs` is installed there. Do not assume `execute_code` includes third-party packages by default.
+
+Safe wording:
+- "Use `execute_code` with `ddgs` after installing or verifying the package if needed"
+
+Avoid saying:
+- "`execute_code` includes `ddgs`"
+- "DuckDuckGo search works by default in `execute_code`"
 
 **Important:** `max_results` must always be passed as a **keyword argument** — positional usage raises an error on all methods.
 
@@ -76,7 +146,7 @@ from ddgs import DDGS
 with DDGS() as ddgs:
     for r in ddgs.images("semiconductor chip", max_results=5):
         print(r["title"])
-        print(r["image"])       # direct image URL
+        print(r["image"])
         print(r.get("thumbnail", ""))
         print(r.get("source", ""))
         print()
@@ -94,9 +164,9 @@ from ddgs import DDGS
 with DDGS() as ddgs:
     for r in ddgs.videos("FastAPI tutorial", max_results=5):
         print(r["title"])
-        print(r.get("content", ""))       # video URL
-        print(r.get("duration", ""))       # e.g. "26:03"
-        print(r.get("provider", ""))       # YouTube, etc.
+        print(r.get("content", ""))
+        print(r.get("duration", ""))
+        print(r.get("provider", ""))
         print(r.get("published", ""))
         print()
 ```
@@ -112,50 +182,17 @@ Returns: `title`, `content`, `description`, `duration`, `provider`, `published`,
 | `images()` | Visuals, diagrams | title, image, thumbnail, url |
 | `videos()` | Tutorials, demos | title, content, duration, provider |
 
-## CLI (Alternative)
-
-Use the `ddgs` command via terminal when you don't need structured field access.
-
-```bash
-# Text search
-ddgs text -k "python async programming" -m 5
-
-# News search
-ddgs news -k "artificial intelligence" -m 5
-
-# Image search
-ddgs images -k "landscape photography" -m 10
-
-# Video search
-ddgs videos -k "python tutorial" -m 5
-
-# With region filter
-ddgs text -k "best restaurants" -m 5 -r us-en
-
-# Recent results only (d=day, w=week, m=month, y=year)
-ddgs text -k "latest AI news" -m 5 -t w
-
-# JSON output for parsing
-ddgs text -k "fastapi tutorial" -m 5 -o json
-```
-
-### CLI Flags
-
-| Flag | Description | Example |
-|------|-------------|---------|
-| `-k` | Keywords (query) — **required** | `-k "search terms"` |
-| `-m` | Max results | `-m 5` |
-| `-r` | Region | `-r us-en` |
-| `-t` | Time limit | `-t w` (week) |
-| `-s` | Safe search | `-s off` |
-| `-o` | Output format | `-o json` |
-
 ## Workflow: Search then Extract
 
-DuckDuckGo returns titles, URLs, and snippets — not full page content. To get full content, follow up with `web_extract`:
+DuckDuckGo returns titles, URLs, and snippets — not full page content. To get full page content, search first and then extract the most relevant URL with `web_extract`, browser tools, or curl.
 
-1. **Search** with ddgs to find relevant URLs
-2. **Extract** content using the `web_extract` tool (if available) or curl
+CLI example:
+
+```bash
+ddgs text -k "fastapi deployment guide" -m 3 -o json
+```
+
+Python example, only after verifying `ddgs` is installed in that runtime:
 
 ```python
 from ddgs import DDGS
@@ -164,25 +201,37 @@ with DDGS() as ddgs:
     results = list(ddgs.text("fastapi deployment guide", max_results=3))
     for r in results:
         print(r["title"], "->", r["href"])
-
-# Then use web_extract tool on the best URL
 ```
 
+Then extract the best URL with `web_extract` or another content-retrieval tool.
+
 ## Limitations
 
 - **Rate limiting**: DuckDuckGo may throttle after many rapid requests. Add a short delay between searches if needed.
-- **No content extraction**: ddgs returns snippets, not full page content. Use `web_extract` or curl for that.
+- **No content extraction**: `ddgs` returns snippets, not full page content. Use `web_extract`, browser tools, or curl for the full article/page.
 - **Results quality**: Generally good but less configurable than Firecrawl's search.
 - **Availability**: DuckDuckGo may block requests from some cloud IPs. If searches return empty, try different keywords or wait a few seconds.
-- **Field variability**: Return fields may vary between results or ddgs versions. Use `.get()` for optional fields to avoid KeyError.
+- **Field variability**: Return fields may vary between results or `ddgs` versions. Use `.get()` for optional fields to avoid `KeyError`.
+- **Separate runtimes**: A successful `ddgs` install in terminal does not automatically mean `execute_code` can import it.
+
+## Troubleshooting
+
+| Problem | Likely Cause | What To Do |
+|---------|--------------|------------|
+| `ddgs: command not found` | CLI not installed in the shell environment | Install `ddgs`, or use built-in web/browser tools instead |
+| `ModuleNotFoundError: No module named 'ddgs'` | Python runtime does not have the package installed | Do not use Python DDGS there until that runtime is prepared |
+| Search returns nothing | Temporary rate limiting or poor query | Wait a few seconds, retry, or adjust the query |
+| CLI works but `execute_code` import fails | Terminal and `execute_code` are different runtimes | Keep using CLI, or separately prepare the Python runtime |
 
 ## Pitfalls
 
 - **`max_results` is keyword-only**: `ddgs.text("query", 5)` raises an error. Use `ddgs.text("query", max_results=5)`.
+- **Do not assume the CLI exists**: Check `command -v ddgs` before using it.
+- **Do not assume `execute_code` can import `ddgs`**: `from ddgs import DDGS` may fail with `ModuleNotFoundError` unless that runtime was prepared separately.
+- **Package name**: The package is `ddgs` (previously `duckduckgo-search`). Install with `pip install ddgs`.
 - **Don't confuse `-k` and `-m`** (CLI): `-k` is for keywords, `-m` is for max results count.
-- **Package name**: The package is `ddgs` (was previously `duckduckgo-search`). Install with `pip install ddgs`.
-- **Empty results**: If ddgs returns nothing, it may be rate-limited. Wait a few seconds and retry.
+- **Empty results**: If `ddgs` returns nothing, it may be rate-limited. Wait a few seconds and retry.
 
 ## Validated With
 
-Smoke-tested with `ddgs==9.11.2` on Python 3.13. All four methods (text, news, images, videos) confirmed working with keyword `max_results`.
+Validated examples against `ddgs==9.11.2` semantics. Skill guidance now treats CLI availability and Python import availability as separate concerns so the documented workflow matches actual runtime behavior.

tests/acp/test_entry.py

@@ -0,0 +1,20 @@
+"""Tests for acp_adapter.entry startup wiring."""
+
+import acp
+
+from acp_adapter import entry
+
+
+def test_main_enables_unstable_protocol(monkeypatch):
+    calls = {}
+
+    async def fake_run_agent(agent, **kwargs):
+        calls["kwargs"] = kwargs
+
+    monkeypatch.setattr(entry, "_setup_logging", lambda: None)
+    monkeypatch.setattr(entry, "_load_env", lambda: None)
+    monkeypatch.setattr(acp, "run_agent", fake_run_agent)
+
+    entry.main()
+
+    assert calls["kwargs"]["use_unstable_protocol"] is True

tests/acp/test_server.py

@@ -8,6 +8,7 @@ from unittest.mock import MagicMock, AsyncMock, patch
 import pytest
 
 import acp
+from acp.agent.router import build_agent_router
 from acp.schema import (
     AgentCapabilities,
     AuthenticateResponse,
@@ -18,6 +19,8 @@ from acp.schema import (
     NewSessionResponse,
     PromptResponse,
     ResumeSessionResponse,
+    SetSessionConfigOptionResponse,
+    SetSessionModeResponse,
     SessionInfo,
     TextContentBlock,
     Usage,
@@ -168,6 +171,74 @@ class TestListAndFork:
         assert fork_resp.session_id != new_resp.session_id
 
 
+# ---------------------------------------------------------------------------
+# session configuration / model routing
+# ---------------------------------------------------------------------------
+
+
+class TestSessionConfiguration:
+    @pytest.mark.asyncio
+    async def test_set_session_mode_returns_response(self, agent):
+        new_resp = await agent.new_session(cwd="/tmp")
+        resp = await agent.set_session_mode(mode_id="chat", session_id=new_resp.session_id)
+        state = agent.session_manager.get_session(new_resp.session_id)
+
+        assert isinstance(resp, SetSessionModeResponse)
+        assert getattr(state, "mode", None) == "chat"
+
+    @pytest.mark.asyncio
+    async def test_set_config_option_returns_response(self, agent):
+        new_resp = await agent.new_session(cwd="/tmp")
+        resp = await agent.set_config_option(
+            config_id="approval_mode",
+            session_id=new_resp.session_id,
+            value="auto",
+        )
+        state = agent.session_manager.get_session(new_resp.session_id)
+
+        assert isinstance(resp, SetSessionConfigOptionResponse)
+        assert getattr(state, "config_options", {}) == {"approval_mode": "auto"}
+        assert resp.config_options == []
+
+    @pytest.mark.asyncio
+    async def test_router_accepts_stable_session_config_methods(self, agent):
+        new_resp = await agent.new_session(cwd="/tmp")
+        router = build_agent_router(agent)
+
+        mode_result = await router(
+            "session/set_mode",
+            {"modeId": "chat", "sessionId": new_resp.session_id},
+            False,
+        )
+        config_result = await router(
+            "session/set_config_option",
+            {
+                "configId": "approval_mode",
+                "sessionId": new_resp.session_id,
+                "value": "auto",
+            },
+            False,
+        )
+
+        assert mode_result == {}
+        assert config_result == {"configOptions": []}
+
+    @pytest.mark.asyncio
+    async def test_router_accepts_unstable_model_switch_when_enabled(self, agent):
+        new_resp = await agent.new_session(cwd="/tmp")
+        router = build_agent_router(agent, use_unstable_protocol=True)
+
+        result = await router(
+            "session/set_model",
+            {"modelId": "gpt-5.4", "sessionId": new_resp.session_id},
+            False,
+        )
+        state = agent.session_manager.get_session(new_resp.session_id)
+
+        assert result == {}
+        assert state.model == "gpt-5.4"
+
+
 # ---------------------------------------------------------------------------
 # prompt
 # ---------------------------------------------------------------------------

tests/agent/test_external_skills.py

@@ -0,0 +1,157 @@
+"""Tests for external skill directories (skills.external_dirs config)."""
+
+import json
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+
+@pytest.fixture
+def external_skills_dir(tmp_path):
+    """Create a temp dir with a sample external skill."""
+    ext_dir = tmp_path / "external-skills"
+    skill_dir = ext_dir / "my-external-skill"
+    skill_dir.mkdir(parents=True)
+    (skill_dir / "SKILL.md").write_text(
+        "---\nname: my-external-skill\ndescription: A skill from an external directory\n---\n\n# My External Skill\n\nDo external things.\n"
+    )
+    return ext_dir
+
+
+@pytest.fixture
+def hermes_home(tmp_path):
+    """Create a minimal HERMES_HOME with config."""
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "skills").mkdir()
+    return home
+
+
+class TestGetExternalSkillsDirs:
+    def test_empty_config(self, hermes_home):
+        (hermes_home / "config.yaml").write_text("skills:\n  external_dirs: []\n")
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert result == []
+
+    def test_nonexistent_dir_skipped(self, hermes_home):
+        (hermes_home / "config.yaml").write_text(
+            "skills:\n  external_dirs:\n    - /nonexistent/path\n"
+        )
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert result == []
+
+    def test_valid_dir_returned(self, hermes_home, external_skills_dir):
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
+        )
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert len(result) == 1
+        assert result[0] == external_skills_dir.resolve()
+
+    def test_duplicate_dirs_deduplicated(self, hermes_home, external_skills_dir):
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n    - {external_skills_dir}\n"
+        )
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert len(result) == 1
+
+    def test_local_skills_dir_excluded(self, hermes_home):
+        local_skills = hermes_home / "skills"
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {local_skills}\n"
+        )
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert result == []
+
+    def test_no_config_file(self, hermes_home):
+        # No config.yaml at all
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert result == []
+
+    def test_string_value_converted_to_list(self, hermes_home, external_skills_dir):
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs: {external_skills_dir}\n"
+        )
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert len(result) == 1
+
+
+class TestGetAllSkillsDirs:
+    def test_local_always_first(self, hermes_home, external_skills_dir):
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
+        )
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_all_skills_dirs
+            result = get_all_skills_dirs()
+        assert result[0] == hermes_home / "skills"
+        assert result[1] == external_skills_dir.resolve()
+
+
+class TestExternalSkillsInFindAll:
+    def test_external_skills_found(self, hermes_home, external_skills_dir):
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
+        )
+        local_skills = hermes_home / "skills"
+        with (
+            patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}),
+            patch("tools.skills_tool.SKILLS_DIR", local_skills),
+        ):
+            from tools.skills_tool import _find_all_skills
+            skills = _find_all_skills()
+        names = [s["name"] for s in skills]
+        assert "my-external-skill" in names
+
+    def test_local_takes_precedence(self, hermes_home, external_skills_dir):
+        """If the same skill name exists locally and externally, local wins."""
+        local_skills = hermes_home / "skills"
+        local_skill = local_skills / "my-external-skill"
+        local_skill.mkdir(parents=True)
+        (local_skill / "SKILL.md").write_text(
+            "---\nname: my-external-skill\ndescription: Local version\n---\n\nLocal.\n"
+        )
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
+        )
+        with (
+            patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}),
+            patch("tools.skills_tool.SKILLS_DIR", local_skills),
+        ):
+            from tools.skills_tool import _find_all_skills
+            skills = _find_all_skills()
+        matching = [s for s in skills if s["name"] == "my-external-skill"]
+        assert len(matching) == 1
+        assert matching[0]["description"] == "Local version"
+
+
+class TestExternalSkillView:
+    def test_skill_view_finds_external(self, hermes_home, external_skills_dir):
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
+        )
+        local_skills = hermes_home / "skills"
+        with (
+            patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}),
+            patch("tools.skills_tool.SKILLS_DIR", local_skills),
+        ):
+            from tools.skills_tool import skill_view
+            result = json.loads(skill_view("my-external-skill"))
+        assert result["success"] is True
+        assert "external things" in result["content"]

tests/agent/test_memory_plugin_e2e.py

@@ -0,0 +1,341 @@
+"""End-to-end test: a SQLite-backed memory plugin exercising the full interface.
+
+This proves a real plugin can register as a MemoryProvider and get wired
+into the agent loop via MemoryManager. Uses SQLite + FTS5 (stdlib, no
+external deps, no API keys).
+"""
+
+import json
+import os
+import sqlite3
+import tempfile
+import pytest
+from unittest.mock import patch, MagicMock
+
+from agent.memory_provider import MemoryProvider
+from agent.memory_manager import MemoryManager
+from agent.builtin_memory_provider import BuiltinMemoryProvider
+
+
+# ---------------------------------------------------------------------------
+# SQLite FTS5 memory provider — a real, minimal plugin implementation
+# ---------------------------------------------------------------------------
+
+
+class SQLiteMemoryProvider(MemoryProvider):
+    """Minimal SQLite + FTS5 memory provider for testing.
+
+    Demonstrates the full MemoryProvider interface with a real backend.
+    No external dependencies — just stdlib sqlite3.
+    """
+
+    def __init__(self, db_path: str = ":memory:"):
+        self._db_path = db_path
+        self._conn = None
+
+    @property
+    def name(self) -> str:
+        return "sqlite_memory"
+
+    def is_available(self) -> bool:
+        return True  # SQLite is always available
+
+    def initialize(self, session_id: str, **kwargs) -> None:
+        self._conn = sqlite3.connect(self._db_path)
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("""
+            CREATE VIRTUAL TABLE IF NOT EXISTS memories
+            USING fts5(content, context, session_id)
+        """)
+        self._session_id = session_id
+
+    def system_prompt_block(self) -> str:
+        if not self._conn:
+            return ""
+        count = self._conn.execute("SELECT COUNT(*) FROM memories").fetchone()[0]
+        if count == 0:
+            return ""
+        return (
+            f"# SQLite Memory Plugin\n"
+            f"Active. {count} memories stored.\n"
+            f"Use sqlite_recall to search, sqlite_retain to store."
+        )
+
+    def prefetch(self, query: str) -> str:
+        if not self._conn or not query:
+            return ""
+        # FTS5 search
+        try:
+            rows = self._conn.execute(
+                "SELECT content FROM memories WHERE memories MATCH ? LIMIT 5",
+                (query,)
+            ).fetchall()
+            if not rows:
+                return ""
+            results = [row[0] for row in rows]
+            return "## SQLite Memory\n" + "\n".join(f"- {r}" for r in results)
+        except sqlite3.OperationalError:
+            return ""
+
+    def sync_turn(self, user_content: str, assistant_content: str) -> None:
+        if not self._conn:
+            return
+        combined = f"User: {user_content}\nAssistant: {assistant_content}"
+        self._conn.execute(
+            "INSERT INTO memories (content, context, session_id) VALUES (?, ?, ?)",
+            (combined, "conversation", self._session_id),
+        )
+        self._conn.commit()
+
+    def get_tool_schemas(self):
+        return [
+            {
+                "name": "sqlite_retain",
+                "description": "Store a fact to SQLite memory.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "content": {"type": "string", "description": "What to remember"},
+                        "context": {"type": "string", "description": "Category/context"},
+                    },
+                    "required": ["content"],
+                },
+            },
+            {
+                "name": "sqlite_recall",
+                "description": "Search SQLite memory.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {"type": "string", "description": "Search query"},
+                    },
+                    "required": ["query"],
+                },
+            },
+        ]
+
+    def handle_tool_call(self, tool_name: str, args: dict, **kwargs) -> str:
+        if tool_name == "sqlite_retain":
+            content = args.get("content", "")
+            context = args.get("context", "explicit")
+            if not content:
+                return json.dumps({"error": "content is required"})
+            self._conn.execute(
+                "INSERT INTO memories (content, context, session_id) VALUES (?, ?, ?)",
+                (content, context, self._session_id),
+            )
+            self._conn.commit()
+            return json.dumps({"result": "Stored."})
+
+        elif tool_name == "sqlite_recall":
+            query = args.get("query", "")
+            if not query:
+                return json.dumps({"error": "query is required"})
+            try:
+                rows = self._conn.execute(
+                    "SELECT content, context FROM memories WHERE memories MATCH ? LIMIT 10",
+                    (query,)
+                ).fetchall()
+                results = [{"content": r[0], "context": r[1]} for r in rows]
+                return json.dumps({"results": results})
+            except sqlite3.OperationalError:
+                return json.dumps({"results": []})
+
+        return json.dumps({"error": f"Unknown tool: {tool_name}"})
+
+    def on_memory_write(self, action, target, content):
+        """Mirror built-in memory writes to SQLite."""
+        if action == "add" and self._conn:
+            self._conn.execute(
+                "INSERT INTO memories (content, context, session_id) VALUES (?, ?, ?)",
+                (content, f"builtin_{target}", self._session_id),
+            )
+            self._conn.commit()
+
+    def shutdown(self):
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+
+# ---------------------------------------------------------------------------
+# End-to-end tests
+# ---------------------------------------------------------------------------
+
+
+class TestSQLiteMemoryPlugin:
+    """Full lifecycle test with the SQLite provider."""
+
+    def test_full_lifecycle(self):
+        """Exercise init → store → recall → sync → prefetch → shutdown."""
+        mgr = MemoryManager()
+        builtin = BuiltinMemoryProvider()
+        sqlite_mem = SQLiteMemoryProvider()
+
+        mgr.add_provider(builtin)
+        mgr.add_provider(sqlite_mem)
+
+        # Initialize
+        mgr.initialize_all(session_id="test-session-1", platform="cli")
+        assert sqlite_mem._conn is not None
+
+        # System prompt — empty at first
+        prompt = mgr.build_system_prompt()
+        assert "SQLite Memory Plugin" not in prompt
+
+        # Store via tool call
+        result = json.loads(mgr.handle_tool_call(
+            "sqlite_retain", {"content": "User prefers dark mode", "context": "preference"}
+        ))
+        assert result["result"] == "Stored."
+
+        # System prompt now shows count
+        prompt = mgr.build_system_prompt()
+        assert "1 memories stored" in prompt
+
+        # Recall via tool call
+        result = json.loads(mgr.handle_tool_call(
+            "sqlite_recall", {"query": "dark mode"}
+        ))
+        assert len(result["results"]) == 1
+        assert "dark mode" in result["results"][0]["content"]
+
+        # Sync a turn (auto-stores conversation)
+        mgr.sync_all("What's my theme?", "You prefer dark mode.")
+        count = sqlite_mem._conn.execute("SELECT COUNT(*) FROM memories").fetchone()[0]
+        assert count == 2  # 1 explicit + 1 synced
+
+        # Prefetch for next turn
+        prefetched = mgr.prefetch_all("dark mode")
+        assert "dark mode" in prefetched
+
+        # Memory bridge — mirroring builtin writes
+        mgr.on_memory_write("add", "user", "Timezone: US Pacific")
+        count = sqlite_mem._conn.execute("SELECT COUNT(*) FROM memories").fetchone()[0]
+        assert count == 3
+
+        # Shutdown
+        mgr.shutdown_all()
+        assert sqlite_mem._conn is None
+
+    def test_tool_routing_with_builtin(self):
+        """Verify builtin + plugin tools coexist without conflict."""
+        mgr = MemoryManager()
+        builtin = BuiltinMemoryProvider()
+        sqlite_mem = SQLiteMemoryProvider()
+        mgr.add_provider(builtin)
+        mgr.add_provider(sqlite_mem)
+        mgr.initialize_all(session_id="test-2")
+
+        # Builtin has no tools
+        assert len(builtin.get_tool_schemas()) == 0
+        # SQLite has 2 tools
+        schemas = mgr.get_all_tool_schemas()
+        names = {s["name"] for s in schemas}
+        assert names == {"sqlite_retain", "sqlite_recall"}
+
+        # Routing works
+        assert mgr.has_tool("sqlite_retain")
+        assert mgr.has_tool("sqlite_recall")
+        assert not mgr.has_tool("memory")  # builtin doesn't register this
+
+    def test_multiple_plugins_coexist(self):
+        """Two plugin providers can run simultaneously."""
+        mgr = MemoryManager()
+        p1 = SQLiteMemoryProvider()
+        p2 = SQLiteMemoryProvider()
+        # Hack name for p2
+        p2._name_override = "sqlite_memory_2"
+        original_name = p2.__class__.name
+        type(p2).name = property(lambda self: getattr(self, '_name_override', 'sqlite_memory'))
+
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+        mgr.initialize_all(session_id="test-3")
+
+        # Store in p1
+        p1._conn.execute(
+            "INSERT INTO memories (content, context, session_id) VALUES (?, ?, ?)",
+            ("fact from p1", "test", "test-3"),
+        )
+        p1._conn.commit()
+
+        # Store in p2
+        p2._conn.execute(
+            "INSERT INTO memories (content, context, session_id) VALUES (?, ?, ?)",
+            ("fact from p2", "test", "test-3"),
+        )
+        p2._conn.commit()
+
+        # Prefetch merges both
+        result = mgr.prefetch_all("fact")
+        assert "fact from p1" in result
+        assert "fact from p2" in result
+
+        # Sync goes to both
+        mgr.sync_all("user msg", "assistant msg")
+        count1 = p1._conn.execute("SELECT COUNT(*) FROM memories").fetchone()[0]
+        count2 = p2._conn.execute("SELECT COUNT(*) FROM memories").fetchone()[0]
+        assert count1 == 2  # 1 explicit + 1 synced
+        assert count2 == 2
+
+        # Restore class
+        type(p2).name = original_name
+        mgr.shutdown_all()
+
+    def test_provider_failure_isolation(self):
+        """Failing provider doesn't break others."""
+        mgr = MemoryManager()
+        good = SQLiteMemoryProvider()
+        bad = SQLiteMemoryProvider()
+
+        mgr.add_provider(good)
+        mgr.add_provider(bad)
+        mgr.initialize_all(session_id="test-4")
+
+        # Break bad provider's connection
+        bad._conn.close()
+        bad._conn = None
+
+        # Good provider still works
+        good._conn.execute(
+            "INSERT INTO memories (content, context, session_id) VALUES (?, ?, ?)",
+            ("still works", "test", "test-4"),
+        )
+        good._conn.commit()
+
+        # Sync — bad fails silently, good succeeds
+        mgr.sync_all("user", "assistant")
+        count = good._conn.execute("SELECT COUNT(*) FROM memories").fetchone()[0]
+        assert count == 2
+
+        mgr.shutdown_all()
+
+    def test_plugin_registration_flow(self):
+        """Simulate the full plugin registration → agent init path."""
+        from hermes_cli.plugins import PluginManager, PluginContext, PluginManifest
+
+        # Simulate plugin discovery
+        manager = PluginManager()
+        manifest = PluginManifest(name="sqlite-memory", source="test")
+        ctx = PluginContext(manifest, manager)
+
+        # Plugin registers its provider
+        provider = SQLiteMemoryProvider()
+        ctx.register_memory_provider(provider)
+
+        assert len(manager._memory_providers) == 1
+
+        # Simulate what AIAgent.__init__ does
+        mem_mgr = MemoryManager()
+        mem_mgr.add_provider(BuiltinMemoryProvider())
+        for plugin_provider in manager._memory_providers:
+            if plugin_provider.is_available():
+                mem_mgr.add_provider(plugin_provider)
+                plugin_provider.initialize(session_id="agent-session")
+
+        assert len(mem_mgr.providers) == 2
+        assert mem_mgr.provider_names == ["builtin", "sqlite_memory"]
+        assert provider._conn is not None  # initialized = connection established
+
+        mem_mgr.shutdown_all()

tests/agent/test_memory_provider.py

@@ -0,0 +1,550 @@
+"""Tests for the memory provider interface, manager, and builtin provider."""
+
+import json
+import pytest
+from unittest.mock import MagicMock, patch
+
+from agent.memory_provider import MemoryProvider
+from agent.memory_manager import MemoryManager
+from agent.builtin_memory_provider import BuiltinMemoryProvider
+
+
+# ---------------------------------------------------------------------------
+# Concrete test provider
+# ---------------------------------------------------------------------------
+
+
+class FakeMemoryProvider(MemoryProvider):
+    """Minimal concrete provider for testing."""
+
+    def __init__(self, name="fake", available=True, tools=None):
+        self._name = name
+        self._available = available
+        self._tools = tools or []
+        self.initialized = False
+        self.synced_turns = []
+        self.prefetch_queries = []
+        self.queued_prefetches = []
+        self.turn_starts = []
+        self.session_end_called = False
+        self.pre_compress_called = False
+        self.memory_writes = []
+        self.shutdown_called = False
+        self._prefetch_result = ""
+        self._prompt_block = ""
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def is_available(self) -> bool:
+        return self._available
+
+    def initialize(self, session_id, **kwargs):
+        self.initialized = True
+        self._init_kwargs = {"session_id": session_id, **kwargs}
+
+    def system_prompt_block(self) -> str:
+        return self._prompt_block
+
+    def prefetch(self, query):
+        self.prefetch_queries.append(query)
+        return self._prefetch_result
+
+    def queue_prefetch(self, query):
+        self.queued_prefetches.append(query)
+
+    def sync_turn(self, user_content, assistant_content):
+        self.synced_turns.append((user_content, assistant_content))
+
+    def get_tool_schemas(self):
+        return self._tools
+
+    def handle_tool_call(self, tool_name, args, **kwargs):
+        return json.dumps({"handled": tool_name, "args": args})
+
+    def shutdown(self):
+        self.shutdown_called = True
+
+    def on_turn_start(self, turn_number, message):
+        self.turn_starts.append((turn_number, message))
+
+    def on_session_end(self, messages):
+        self.session_end_called = True
+
+    def on_pre_compress(self, messages):
+        self.pre_compress_called = True
+
+    def on_memory_write(self, action, target, content):
+        self.memory_writes.append((action, target, content))
+
+
+# ---------------------------------------------------------------------------
+# MemoryProvider ABC tests
+# ---------------------------------------------------------------------------
+
+
+class TestMemoryProviderABC:
+    def test_cannot_instantiate_abstract(self):
+        """ABC cannot be instantiated directly."""
+        with pytest.raises(TypeError):
+            MemoryProvider()
+
+    def test_concrete_provider_works(self):
+        """Concrete implementation can be instantiated."""
+        p = FakeMemoryProvider()
+        assert p.name == "fake"
+        assert p.is_available()
+
+    def test_default_optional_hooks_are_noop(self):
+        """Optional hooks have default no-op implementations."""
+        p = FakeMemoryProvider()
+        # These should not raise
+        p.on_turn_start(1, "hello")
+        p.on_session_end([])
+        p.on_pre_compress([])
+        p.on_memory_write("add", "memory", "test")
+        p.queue_prefetch("query")
+        p.sync_turn("user", "assistant")
+        p.shutdown()
+
+
+# ---------------------------------------------------------------------------
+# MemoryManager tests
+# ---------------------------------------------------------------------------
+
+
+class TestMemoryManager:
+    def test_empty_manager(self):
+        mgr = MemoryManager()
+        assert mgr.providers == []
+        assert mgr.provider_names == []
+        assert mgr.get_all_tool_schemas() == []
+        assert mgr.build_system_prompt() == ""
+        assert mgr.prefetch_all("test") == ""
+
+    def test_add_provider(self):
+        mgr = MemoryManager()
+        p = FakeMemoryProvider("test1")
+        mgr.add_provider(p)
+        assert len(mgr.providers) == 1
+        assert mgr.provider_names == ["test1"]
+
+    def test_get_provider_by_name(self):
+        mgr = MemoryManager()
+        p = FakeMemoryProvider("test1")
+        mgr.add_provider(p)
+        assert mgr.get_provider("test1") is p
+        assert mgr.get_provider("nonexistent") is None
+
+    def test_multiple_providers(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1")
+        p2 = FakeMemoryProvider("p2")
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+        assert mgr.provider_names == ["p1", "p2"]
+
+    def test_system_prompt_merges_blocks(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1")
+        p1._prompt_block = "Block from p1"
+        p2 = FakeMemoryProvider("p2")
+        p2._prompt_block = "Block from p2"
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        result = mgr.build_system_prompt()
+        assert "Block from p1" in result
+        assert "Block from p2" in result
+
+    def test_system_prompt_skips_empty(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1")
+        p1._prompt_block = "Has content"
+        p2 = FakeMemoryProvider("p2")
+        p2._prompt_block = ""
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        result = mgr.build_system_prompt()
+        assert result == "Has content"
+
+    def test_prefetch_merges_results(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1")
+        p1._prefetch_result = "Memory from p1"
+        p2 = FakeMemoryProvider("p2")
+        p2._prefetch_result = "Memory from p2"
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        result = mgr.prefetch_all("what do you know?")
+        assert "Memory from p1" in result
+        assert "Memory from p2" in result
+        assert p1.prefetch_queries == ["what do you know?"]
+        assert p2.prefetch_queries == ["what do you know?"]
+
+    def test_prefetch_skips_empty(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1")
+        p1._prefetch_result = "Has memories"
+        p2 = FakeMemoryProvider("p2")
+        p2._prefetch_result = ""
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        result = mgr.prefetch_all("query")
+        assert result == "Has memories"
+
+    def test_queue_prefetch_all(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1")
+        p2 = FakeMemoryProvider("p2")
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        mgr.queue_prefetch_all("next turn")
+        assert p1.queued_prefetches == ["next turn"]
+        assert p2.queued_prefetches == ["next turn"]
+
+    def test_sync_all(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1")
+        p2 = FakeMemoryProvider("p2")
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        mgr.sync_all("user msg", "assistant msg")
+        assert p1.synced_turns == [("user msg", "assistant msg")]
+        assert p2.synced_turns == [("user msg", "assistant msg")]
+
+    def test_sync_failure_doesnt_block_others(self):
+        """If one provider's sync fails, others still run."""
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1")
+        p1.sync_turn = MagicMock(side_effect=RuntimeError("boom"))
+        p2 = FakeMemoryProvider("p2")
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        mgr.sync_all("user", "assistant")
+        # p1 failed but p2 still synced
+        assert p2.synced_turns == [("user", "assistant")]
+
+    # -- Tool routing -------------------------------------------------------
+
+    def test_tool_schemas_collected(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1", tools=[
+            {"name": "recall_p1", "description": "P1 recall", "parameters": {}}
+        ])
+        p2 = FakeMemoryProvider("p2", tools=[
+            {"name": "recall_p2", "description": "P2 recall", "parameters": {}}
+        ])
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        schemas = mgr.get_all_tool_schemas()
+        names = {s["name"] for s in schemas}
+        assert names == {"recall_p1", "recall_p2"}
+
+    def test_tool_name_conflict_first_wins(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1", tools=[
+            {"name": "shared_tool", "description": "From P1", "parameters": {}}
+        ])
+        p2 = FakeMemoryProvider("p2", tools=[
+            {"name": "shared_tool", "description": "From P2", "parameters": {}}
+        ])
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        assert mgr.has_tool("shared_tool")
+        result = json.loads(mgr.handle_tool_call("shared_tool", {"q": "test"}))
+        assert result["handled"] == "shared_tool"
+        # Should be handled by p1 (first registered)
+
+    def test_handle_unknown_tool(self):
+        mgr = MemoryManager()
+        result = json.loads(mgr.handle_tool_call("nonexistent", {}))
+        assert "error" in result
+
+    def test_tool_routing(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1", tools=[
+            {"name": "p1_tool", "description": "P1", "parameters": {}}
+        ])
+        p2 = FakeMemoryProvider("p2", tools=[
+            {"name": "p2_tool", "description": "P2", "parameters": {}}
+        ])
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        r1 = json.loads(mgr.handle_tool_call("p1_tool", {"a": 1}))
+        assert r1["handled"] == "p1_tool"
+        r2 = json.loads(mgr.handle_tool_call("p2_tool", {"b": 2}))
+        assert r2["handled"] == "p2_tool"
+
+    # -- Lifecycle hooks -----------------------------------------------------
+
+    def test_on_turn_start(self):
+        mgr = MemoryManager()
+        p = FakeMemoryProvider("p")
+        mgr.add_provider(p)
+        mgr.on_turn_start(3, "hello")
+        assert p.turn_starts == [(3, "hello")]
+
+    def test_on_session_end(self):
+        mgr = MemoryManager()
+        p = FakeMemoryProvider("p")
+        mgr.add_provider(p)
+        mgr.on_session_end([{"role": "user", "content": "hi"}])
+        assert p.session_end_called
+
+    def test_on_pre_compress(self):
+        mgr = MemoryManager()
+        p = FakeMemoryProvider("p")
+        mgr.add_provider(p)
+        mgr.on_pre_compress([{"role": "user", "content": "old"}])
+        assert p.pre_compress_called
+
+    def test_on_memory_write_skips_builtin(self):
+        """on_memory_write should skip the builtin provider."""
+        mgr = MemoryManager()
+        builtin = BuiltinMemoryProvider()
+        external = FakeMemoryProvider("external")
+        mgr.add_provider(builtin)
+        mgr.add_provider(external)
+
+        mgr.on_memory_write("add", "memory", "test fact")
+        assert external.memory_writes == [("add", "memory", "test fact")]
+
+    def test_shutdown_all_reverse_order(self):
+        mgr = MemoryManager()
+        order = []
+        p1 = FakeMemoryProvider("p1")
+        p1.shutdown = lambda: order.append("p1")
+        p2 = FakeMemoryProvider("p2")
+        p2.shutdown = lambda: order.append("p2")
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        mgr.shutdown_all()
+        assert order == ["p2", "p1"]  # reverse order
+
+    def test_initialize_all(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1")
+        p2 = FakeMemoryProvider("p2")
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        mgr.initialize_all(session_id="test-123", platform="cli")
+        assert p1.initialized
+        assert p2.initialized
+        assert p1._init_kwargs["session_id"] == "test-123"
+        assert p1._init_kwargs["platform"] == "cli"
+
+    # -- Error resilience ---------------------------------------------------
+
+    def test_prefetch_failure_doesnt_block(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1")
+        p1.prefetch = MagicMock(side_effect=RuntimeError("network error"))
+        p2 = FakeMemoryProvider("p2")
+        p2._prefetch_result = "p2 memory"
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        result = mgr.prefetch_all("query")
+        assert "p2 memory" in result
+
+    def test_system_prompt_failure_doesnt_block(self):
+        mgr = MemoryManager()
+        p1 = FakeMemoryProvider("p1")
+        p1.system_prompt_block = MagicMock(side_effect=RuntimeError("broken"))
+        p2 = FakeMemoryProvider("p2")
+        p2._prompt_block = "works fine"
+        mgr.add_provider(p1)
+        mgr.add_provider(p2)
+
+        result = mgr.build_system_prompt()
+        assert result == "works fine"
+
+
+# ---------------------------------------------------------------------------
+# BuiltinMemoryProvider tests
+# ---------------------------------------------------------------------------
+
+
+class TestBuiltinMemoryProvider:
+    def test_name(self):
+        p = BuiltinMemoryProvider()
+        assert p.name == "builtin"
+
+    def test_always_available(self):
+        p = BuiltinMemoryProvider()
+        assert p.is_available()
+
+    def test_no_tools(self):
+        """Builtin provider exposes no tools (memory tool is agent-level)."""
+        p = BuiltinMemoryProvider()
+        assert p.get_tool_schemas() == []
+
+    def test_system_prompt_with_store(self):
+        store = MagicMock()
+        store.format_for_system_prompt.side_effect = lambda t: f"BLOCK_{t}" if t == "memory" else f"BLOCK_{t}"
+
+        p = BuiltinMemoryProvider(
+            memory_store=store,
+            memory_enabled=True,
+            user_profile_enabled=True,
+        )
+        block = p.system_prompt_block()
+        assert "BLOCK_memory" in block
+        assert "BLOCK_user" in block
+
+    def test_system_prompt_memory_disabled(self):
+        store = MagicMock()
+        store.format_for_system_prompt.return_value = "content"
+
+        p = BuiltinMemoryProvider(
+            memory_store=store,
+            memory_enabled=False,
+            user_profile_enabled=False,
+        )
+        assert p.system_prompt_block() == ""
+
+    def test_system_prompt_no_store(self):
+        p = BuiltinMemoryProvider(memory_store=None, memory_enabled=True)
+        assert p.system_prompt_block() == ""
+
+    def test_prefetch_returns_empty(self):
+        p = BuiltinMemoryProvider()
+        assert p.prefetch("anything") == ""
+
+    def test_store_property(self):
+        store = MagicMock()
+        p = BuiltinMemoryProvider(memory_store=store)
+        assert p.store is store
+
+    def test_initialize_loads_from_disk(self):
+        store = MagicMock()
+        p = BuiltinMemoryProvider(memory_store=store)
+        p.initialize(session_id="test")
+        store.load_from_disk.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# Plugin registration tests
+# ---------------------------------------------------------------------------
+
+
+class TestSingleProviderGating:
+    """Only the configured provider should activate."""
+
+    def test_no_provider_configured_means_builtin_only(self):
+        """When memory.provider is empty, no plugin providers activate."""
+        mgr = MemoryManager()
+        builtin = BuiltinMemoryProvider()
+        mgr.add_provider(builtin)
+
+        # Simulate what run_agent.py does when provider="" 
+        configured = ""
+        available_plugins = [
+            FakeMemoryProvider("holographic"),
+            FakeMemoryProvider("mem0"),
+        ]
+        # With empty config, no plugins should be added
+        if configured:
+            for p in available_plugins:
+                if p.name == configured and p.is_available():
+                    mgr.add_provider(p)
+
+        assert mgr.provider_names == ["builtin"]
+
+    def test_configured_provider_activates(self):
+        """Only the named provider should be added."""
+        mgr = MemoryManager()
+        builtin = BuiltinMemoryProvider()
+        mgr.add_provider(builtin)
+
+        configured = "holographic"
+        p1 = FakeMemoryProvider("holographic")
+        p2 = FakeMemoryProvider("mem0")
+        p3 = FakeMemoryProvider("hindsight")
+
+        for p in [p1, p2, p3]:
+            if p.name == configured and p.is_available():
+                mgr.add_provider(p)
+
+        assert mgr.provider_names == ["builtin", "holographic"]
+        assert p1.initialized is False  # not initialized by the gating logic itself
+
+    def test_unavailable_provider_skipped(self):
+        """If the configured provider is unavailable, it should be skipped."""
+        mgr = MemoryManager()
+        builtin = BuiltinMemoryProvider()
+        mgr.add_provider(builtin)
+
+        configured = "holographic"
+        p1 = FakeMemoryProvider("holographic", available=False)
+
+        for p in [p1]:
+            if p.name == configured and p.is_available():
+                mgr.add_provider(p)
+
+        assert mgr.provider_names == ["builtin"]
+
+    def test_nonexistent_provider_results_in_builtin_only(self):
+        """If the configured name doesn't match any plugin, only builtin remains."""
+        mgr = MemoryManager()
+        builtin = BuiltinMemoryProvider()
+        mgr.add_provider(builtin)
+
+        configured = "nonexistent"
+        plugins = [FakeMemoryProvider("holographic"), FakeMemoryProvider("mem0")]
+
+        for p in plugins:
+            if p.name == configured and p.is_available():
+                mgr.add_provider(p)
+
+        assert mgr.provider_names == ["builtin"]
+
+
+class TestPluginMemoryProviderRegistration:
+    def test_register_memory_provider(self):
+        """PluginContext.register_memory_provider adds to manager list."""
+        from hermes_cli.plugins import PluginManager, PluginContext, PluginManifest
+
+        manager = PluginManager()
+        manifest = PluginManifest(
+            name="test-plugin",
+            version="1.0.0",
+            description="Test",
+            source="test",
+        )
+        ctx = PluginContext(manifest, manager)
+
+        fake_provider = FakeMemoryProvider("test-mem")
+        ctx.register_memory_provider(fake_provider)
+
+        assert len(manager._memory_providers) == 1
+        assert manager._memory_providers[0] is fake_provider
+
+    def test_get_plugin_memory_providers(self):
+        """get_plugin_memory_providers returns registered providers."""
+        from hermes_cli.plugins import PluginManager, get_plugin_memory_providers
+
+        with patch("hermes_cli.plugins.get_plugin_manager") as mock_get:
+            mgr = PluginManager()
+            p1 = FakeMemoryProvider("p1")
+            p2 = FakeMemoryProvider("p2")
+            mgr._memory_providers = [p1, p2]
+            mock_get.return_value = mgr
+
+            result = get_plugin_memory_providers()
+            assert len(result) == 2
+            assert result[0] is p1
+            assert result[1] is p2

tests/agent/test_prompt_builder.py

@@ -5,6 +5,8 @@ import importlib
 import logging
 import sys
 
+import pytest
+
 from agent.prompt_builder import (
     _scan_context_content,
     _truncate_content,
@@ -194,7 +196,7 @@ class TestParseSkillFile:
         )
         from unittest.mock import patch
 
-        with patch("tools.skills_tool.sys") as mock_sys:
+        with patch("agent.skill_utils.sys") as mock_sys:
             mock_sys.platform = "linux"
             is_compat, _, _ = _parse_skill_file(skill_file)
         assert is_compat is False
@@ -234,9 +236,6 @@ class TestPromptBuilderImports:
 # =========================================================================
 
 
-import pytest
-
-
 class TestBuildSkillsSystemPrompt:
     @pytest.fixture(autouse=True)
     def _clear_skills_cache(self):
@@ -296,7 +295,7 @@ class TestBuildSkillsSystemPrompt:
 
         from unittest.mock import patch
 
-        with patch("tools.skills_tool.sys") as mock_sys:
+        with patch("agent.skill_utils.sys") as mock_sys:
             mock_sys.platform = "linux"
             result = build_skills_system_prompt()
 
@@ -574,6 +573,10 @@ class TestBuildContextFilesPrompt:
         result = build_context_files_prompt(cwd=str(tmp_path))
         assert "Lowercase claude rules" in result
 
+    @pytest.mark.skipif(
+        sys.platform == "darwin",
+        reason="APFS default volume is case-insensitive; CLAUDE.md and claude.md alias the same path",
+    )
     def test_claude_md_uppercase_takes_priority(self, tmp_path):
         (tmp_path / "CLAUDE.md").write_text("From uppercase.")
         (tmp_path / "claude.md").write_text("From lowercase.")

tests/agent/test_skill_commands.py

@@ -246,20 +246,10 @@ Generate some audio.
     def test_preserves_remaining_remote_setup_warning(self, tmp_path, monkeypatch):
         monkeypatch.setenv("TERMINAL_ENV", "ssh")
         monkeypatch.delenv("TENOR_API_KEY", raising=False)
-
-        def fake_secret_callback(var_name, prompt, metadata=None):
-            os.environ[var_name] = "stored-in-test"
-            return {
-                "success": True,
-                "stored_as": var_name,
-                "validated": False,
-                "skipped": False,
-            }
-
         monkeypatch.setattr(
             skills_tool_module,
             "_secret_capture_callback",
-            fake_secret_callback,
+            None,
             raising=False,
         )
 

tests/gateway/test_mattermost.py

@@ -1,5 +1,6 @@
 """Tests for Mattermost platform adapter."""
 import json
+import os
 import time
 import pytest
 from unittest.mock import MagicMock, patch, AsyncMock
@@ -269,6 +270,7 @@ class TestMattermostWebSocketParsing:
     def setup_method(self):
         self.adapter = _make_adapter()
         self.adapter._bot_user_id = "bot_user_id"
+        self.adapter._bot_username = "hermes-bot"
         # Mock handle_message to capture the MessageEvent without processing
         self.adapter.handle_message = AsyncMock()
 
@@ -293,7 +295,8 @@ class TestMattermostWebSocketParsing:
         await self.adapter._handle_ws_event(event)
         assert self.adapter.handle_message.called
         msg_event = self.adapter.handle_message.call_args[0][0]
-        assert msg_event.text == "@bot_user_id Hello from Matrix!"
+        # @mention is stripped from the message text
+        assert msg_event.text == "Hello from Matrix!"
         assert msg_event.message_id == "post_abc"
 
     @pytest.mark.asyncio
@@ -410,6 +413,87 @@ class TestMattermostWebSocketParsing:
         assert not self.adapter.handle_message.called
 
 
+# ---------------------------------------------------------------------------
+# Mention behavior (require_mention + free_response_channels)
+# ---------------------------------------------------------------------------
+
+class TestMattermostMentionBehavior:
+    def setup_method(self):
+        self.adapter = _make_adapter()
+        self.adapter._bot_user_id = "bot_user_id"
+        self.adapter._bot_username = "hermes-bot"
+        self.adapter.handle_message = AsyncMock()
+
+    def _make_event(self, message, channel_type="O", channel_id="chan_456"):
+        post_data = {
+            "id": "post_mention",
+            "user_id": "user_123",
+            "channel_id": channel_id,
+            "message": message,
+        }
+        return {
+            "event": "posted",
+            "data": {
+                "post": json.dumps(post_data),
+                "channel_type": channel_type,
+                "sender_name": "@alice",
+            },
+        }
+
+    @pytest.mark.asyncio
+    async def test_require_mention_true_skips_without_mention(self):
+        """Default: messages without @mention in channels are skipped."""
+        with patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
+            os.environ.pop("MATTERMOST_FREE_RESPONSE_CHANNELS", None)
+            await self.adapter._handle_ws_event(self._make_event("hello"))
+            assert not self.adapter.handle_message.called
+
+    @pytest.mark.asyncio
+    async def test_require_mention_false_responds_to_all(self):
+        """MATTERMOST_REQUIRE_MENTION=false: respond to all channel messages."""
+        with patch.dict(os.environ, {"MATTERMOST_REQUIRE_MENTION": "false"}):
+            await self.adapter._handle_ws_event(self._make_event("hello"))
+            assert self.adapter.handle_message.called
+
+    @pytest.mark.asyncio
+    async def test_free_response_channel_responds_without_mention(self):
+        """Messages in free-response channels don't need @mention."""
+        with patch.dict(os.environ, {"MATTERMOST_FREE_RESPONSE_CHANNELS": "chan_456,chan_789"}):
+            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
+            await self.adapter._handle_ws_event(self._make_event("hello", channel_id="chan_456"))
+            assert self.adapter.handle_message.called
+
+    @pytest.mark.asyncio
+    async def test_non_free_channel_still_requires_mention(self):
+        """Channels NOT in free-response list still require @mention."""
+        with patch.dict(os.environ, {"MATTERMOST_FREE_RESPONSE_CHANNELS": "chan_789"}):
+            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
+            await self.adapter._handle_ws_event(self._make_event("hello", channel_id="chan_456"))
+            assert not self.adapter.handle_message.called
+
+    @pytest.mark.asyncio
+    async def test_dm_always_responds(self):
+        """DMs (channel_type=D) always respond regardless of mention settings."""
+        with patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
+            await self.adapter._handle_ws_event(self._make_event("hello", channel_type="D"))
+            assert self.adapter.handle_message.called
+
+    @pytest.mark.asyncio
+    async def test_mention_stripped_from_text(self):
+        """@mention is stripped from message text."""
+        with patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
+            await self.adapter._handle_ws_event(
+                self._make_event("@hermes-bot what is 2+2")
+            )
+            assert self.adapter.handle_message.called
+            msg = self.adapter.handle_message.call_args[0][0]
+            assert "@hermes-bot" not in msg.text
+            assert "2+2" in msg.text
+
+
 # ---------------------------------------------------------------------------
 # File upload (send_image)
 # ---------------------------------------------------------------------------

tests/gateway/test_signal.py

@@ -1,11 +1,42 @@
 """Tests for Signal messenger platform adapter."""
+import base64
 import json
 import pytest
 from unittest.mock import MagicMock, patch, AsyncMock
+from urllib.parse import quote
 
 from gateway.config import Platform, PlatformConfig
 
 
+# ---------------------------------------------------------------------------
+# Shared Helpers
+# ---------------------------------------------------------------------------
+
+def _make_signal_adapter(monkeypatch, account="+15551234567", **extra):
+    """Create a SignalAdapter with sensible test defaults."""
+    monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", extra.pop("group_allowed", ""))
+    from gateway.platforms.signal import SignalAdapter
+    config = PlatformConfig()
+    config.enabled = True
+    config.extra = {
+        "http_url": "http://localhost:8080",
+        "account": account,
+        **extra,
+    }
+    return SignalAdapter(config)
+
+
+def _stub_rpc(return_value):
+    """Return an async mock for SignalAdapter._rpc that captures call params."""
+    captured = []
+
+    async def mock_rpc(method, params, rpc_id=None):
+        captured.append({"method": method, "params": dict(params)})
+        return return_value
+
+    return mock_rpc, captured
+
+
 # ---------------------------------------------------------------------------
 # Platform & Config
 # ---------------------------------------------------------------------------
@@ -61,48 +92,22 @@ class TestSignalConfigLoading:
 # ---------------------------------------------------------------------------
 
 class TestSignalAdapterInit:
-    def _make_config(self, **extra):
-        config = PlatformConfig()
-        config.enabled = True
-        config.extra = {
-            "http_url": "http://localhost:8080",
-            "account": "+15551234567",
-            **extra,
-        }
-        return config
-
     def test_init_parses_config(self, monkeypatch):
-        monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", "group123,group456")
-
-        from gateway.platforms.signal import SignalAdapter
-        adapter = SignalAdapter(self._make_config())
-
+        adapter = _make_signal_adapter(monkeypatch, group_allowed="group123,group456")
         assert adapter.http_url == "http://localhost:8080"
         assert adapter.account == "+15551234567"
         assert "group123" in adapter.group_allow_from
 
     def test_init_empty_allowlist(self, monkeypatch):
-        monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", "")
-
-        from gateway.platforms.signal import SignalAdapter
-        adapter = SignalAdapter(self._make_config())
-
+        adapter = _make_signal_adapter(monkeypatch)
         assert len(adapter.group_allow_from) == 0
 
     def test_init_strips_trailing_slash(self, monkeypatch):
-        monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", "")
-
-        from gateway.platforms.signal import SignalAdapter
-        adapter = SignalAdapter(self._make_config(http_url="http://localhost:8080/"))
-
+        adapter = _make_signal_adapter(monkeypatch, http_url="http://localhost:8080/")
         assert adapter.http_url == "http://localhost:8080"
 
     def test_self_message_filtering(self, monkeypatch):
-        monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", "")
-
-        from gateway.platforms.signal import SignalAdapter
-        adapter = SignalAdapter(self._make_config())
-
+        adapter = _make_signal_adapter(monkeypatch)
         assert adapter._account_normalized == "+15551234567"
 
 
@@ -189,6 +194,73 @@ class TestSignalHelpers:
         assert check_signal_requirements() is False
 
 
+# ---------------------------------------------------------------------------
+# SSE URL Encoding (Bug Fix: phone numbers with + must be URL-encoded)
+# ---------------------------------------------------------------------------
+
+class TestSignalSSEUrlEncoding:
+    """Verify that phone numbers with + are URL-encoded in the SSE endpoint."""
+
+    def test_sse_url_encodes_plus_in_account(self):
+        """The + in E.164 phone numbers must be percent-encoded in the SSE query string."""
+        encoded = quote("+31612345678", safe="")
+        assert encoded == "%2B31612345678"
+
+    def test_sse_url_encoding_preserves_digits(self):
+        """Digits and country codes should pass through URL encoding unchanged."""
+        assert quote("+15551234567", safe="") == "%2B15551234567"
+
+
+# ---------------------------------------------------------------------------
+# Attachment Fetch (Bug Fix: parameter must be "id" not "attachmentId")
+# ---------------------------------------------------------------------------
+
+class TestSignalAttachmentFetch:
+    """Verify that _fetch_attachment uses the correct RPC parameter name."""
+
+    @pytest.mark.asyncio
+    async def test_fetch_attachment_uses_id_parameter(self, monkeypatch):
+        """RPC getAttachment must use 'id', not 'attachmentId' (signal-cli requirement)."""
+        adapter = _make_signal_adapter(monkeypatch)
+
+        png_data = b"\x89PNG\r\n\x1a\n" + b"\x00" * 100
+        b64_data = base64.b64encode(png_data).decode()
+
+        adapter._rpc, captured = _stub_rpc({"data": b64_data})
+
+        with patch("gateway.platforms.signal.cache_image_from_bytes", return_value="/tmp/test.png"):
+            await adapter._fetch_attachment("attachment-123")
+
+        call = captured[0]
+        assert call["method"] == "getAttachment"
+        assert call["params"]["id"] == "attachment-123"
+        assert "attachmentId" not in call["params"], "Must NOT use 'attachmentId' — causes NullPointerException in signal-cli"
+        assert call["params"]["account"] == "+15551234567"
+
+    @pytest.mark.asyncio
+    async def test_fetch_attachment_returns_none_on_empty(self, monkeypatch):
+        adapter = _make_signal_adapter(monkeypatch)
+        adapter._rpc, _ = _stub_rpc(None)
+        path, ext = await adapter._fetch_attachment("missing-id")
+        assert path is None
+        assert ext == ""
+
+    @pytest.mark.asyncio
+    async def test_fetch_attachment_handles_dict_response(self, monkeypatch):
+        adapter = _make_signal_adapter(monkeypatch)
+
+        pdf_data = b"%PDF-1.4" + b"\x00" * 100
+        b64_data = base64.b64encode(pdf_data).decode()
+
+        adapter._rpc, _ = _stub_rpc({"data": b64_data})
+
+        with patch("gateway.platforms.signal.cache_document_from_bytes", return_value="/tmp/test.pdf"):
+            path, ext = await adapter._fetch_attachment("doc-456")
+
+        assert path == "/tmp/test.pdf"
+        assert ext == ".pdf"
+
+
 # ---------------------------------------------------------------------------
 # Session Source
 # ---------------------------------------------------------------------------

tests/hermes_cli/test_profiles.py

@@ -0,0 +1,622 @@
+"""Comprehensive tests for hermes_cli.profiles module.
+
+Tests cover: validation, directory resolution, CRUD operations, active profile
+management, export/import, renaming, alias collision checks, profile isolation,
+and shell completion generation.
+"""
+
+import json
+import os
+import tarfile
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from hermes_cli.profiles import (
+    validate_profile_name,
+    get_profile_dir,
+    create_profile,
+    delete_profile,
+    list_profiles,
+    set_active_profile,
+    get_active_profile,
+    get_active_profile_name,
+    resolve_profile_env,
+    check_alias_collision,
+    rename_profile,
+    export_profile,
+    import_profile,
+    generate_bash_completion,
+    generate_zsh_completion,
+    _get_profiles_root,
+    _get_default_hermes_home,
+)
+
+
+# ---------------------------------------------------------------------------
+# Shared fixture: redirect Path.home() and HERMES_HOME for profile tests
+# ---------------------------------------------------------------------------
+
+@pytest.fixture()
+def profile_env(tmp_path, monkeypatch):
+    """Set up an isolated environment for profile tests.
+
+    * Path.home() -> tmp_path  (so _get_profiles_root() = tmp_path/.hermes/profiles)
+    * HERMES_HOME  -> tmp_path/.hermes  (so get_hermes_home() agrees)
+    * Creates the bare-minimum ~/.hermes directory.
+    """
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    default_home = tmp_path / ".hermes"
+    default_home.mkdir(exist_ok=True)
+    monkeypatch.setenv("HERMES_HOME", str(default_home))
+    return tmp_path
+
+
+# ===================================================================
+# TestValidateProfileName
+# ===================================================================
+
+class TestValidateProfileName:
+    """Tests for validate_profile_name()."""
+
+    @pytest.mark.parametrize("name", ["coder", "work-bot", "a1", "my_agent"])
+    def test_valid_names_accepted(self, name):
+        # Should not raise
+        validate_profile_name(name)
+
+    @pytest.mark.parametrize("name", ["UPPER", "has space", ".hidden", "-leading"])
+    def test_invalid_names_rejected(self, name):
+        with pytest.raises(ValueError):
+            validate_profile_name(name)
+
+    def test_too_long_rejected(self):
+        long_name = "a" * 65
+        with pytest.raises(ValueError):
+            validate_profile_name(long_name)
+
+    def test_max_length_accepted(self):
+        # 64 chars total: 1 leading + 63 remaining = 64, within [0,63] range
+        name = "a" * 64
+        validate_profile_name(name)
+
+    def test_default_accepted(self):
+        # 'default' is a special-case pass-through
+        validate_profile_name("default")
+
+    def test_empty_string_rejected(self):
+        with pytest.raises(ValueError):
+            validate_profile_name("")
+
+
+# ===================================================================
+# TestGetProfileDir
+# ===================================================================
+
+class TestGetProfileDir:
+    """Tests for get_profile_dir()."""
+
+    def test_default_returns_hermes_home(self, profile_env):
+        tmp_path = profile_env
+        result = get_profile_dir("default")
+        assert result == tmp_path / ".hermes"
+
+    def test_named_profile_returns_profiles_subdir(self, profile_env):
+        tmp_path = profile_env
+        result = get_profile_dir("coder")
+        assert result == tmp_path / ".hermes" / "profiles" / "coder"
+
+
+# ===================================================================
+# TestCreateProfile
+# ===================================================================
+
+class TestCreateProfile:
+    """Tests for create_profile()."""
+
+    def test_creates_directory_with_subdirs(self, profile_env):
+        profile_dir = create_profile("coder", no_alias=True)
+        assert profile_dir.is_dir()
+        for subdir in ["memories", "sessions", "skills", "skins", "logs",
+                        "plans", "workspace", "cron"]:
+            assert (profile_dir / subdir).is_dir(), f"Missing subdir: {subdir}"
+
+    def test_duplicate_raises_file_exists(self, profile_env):
+        create_profile("coder", no_alias=True)
+        with pytest.raises(FileExistsError):
+            create_profile("coder", no_alias=True)
+
+    def test_default_raises_value_error(self, profile_env):
+        with pytest.raises(ValueError, match="default"):
+            create_profile("default", no_alias=True)
+
+    def test_invalid_name_raises_value_error(self, profile_env):
+        with pytest.raises(ValueError):
+            create_profile("INVALID!", no_alias=True)
+
+    def test_clone_config_copies_files(self, profile_env):
+        tmp_path = profile_env
+        default_home = tmp_path / ".hermes"
+        # Create source config files in default profile
+        (default_home / "config.yaml").write_text("model: test")
+        (default_home / ".env").write_text("KEY=val")
+        (default_home / "SOUL.md").write_text("Be helpful.")
+
+        profile_dir = create_profile("coder", clone_config=True, no_alias=True)
+
+        assert (profile_dir / "config.yaml").read_text() == "model: test"
+        assert (profile_dir / ".env").read_text() == "KEY=val"
+        assert (profile_dir / "SOUL.md").read_text() == "Be helpful."
+
+    def test_clone_all_copies_entire_tree(self, profile_env):
+        tmp_path = profile_env
+        default_home = tmp_path / ".hermes"
+        # Populate default with some content
+        (default_home / "memories").mkdir(exist_ok=True)
+        (default_home / "memories" / "note.md").write_text("remember this")
+        (default_home / "config.yaml").write_text("model: gpt-4")
+        # Runtime files that should be stripped
+        (default_home / "gateway.pid").write_text("12345")
+        (default_home / "gateway_state.json").write_text("{}")
+        (default_home / "processes.json").write_text("[]")
+
+        profile_dir = create_profile("coder", clone_all=True, no_alias=True)
+
+        # Content should be copied
+        assert (profile_dir / "memories" / "note.md").read_text() == "remember this"
+        assert (profile_dir / "config.yaml").read_text() == "model: gpt-4"
+        # Runtime files should be stripped
+        assert not (profile_dir / "gateway.pid").exists()
+        assert not (profile_dir / "gateway_state.json").exists()
+        assert not (profile_dir / "processes.json").exists()
+
+    def test_clone_config_missing_files_skipped(self, profile_env):
+        """Clone config gracefully skips files that don't exist in source."""
+        profile_dir = create_profile("coder", clone_config=True, no_alias=True)
+        # No error; optional files just not copied
+        assert not (profile_dir / "config.yaml").exists()
+        assert not (profile_dir / ".env").exists()
+        assert not (profile_dir / "SOUL.md").exists()
+
+
+# ===================================================================
+# TestDeleteProfile
+# ===================================================================
+
+class TestDeleteProfile:
+    """Tests for delete_profile()."""
+
+    def test_removes_directory(self, profile_env):
+        profile_dir = create_profile("coder", no_alias=True)
+        assert profile_dir.is_dir()
+        # Mock gateway import to avoid real systemd/launchd interaction
+        with patch("hermes_cli.profiles._cleanup_gateway_service"):
+            delete_profile("coder", yes=True)
+        assert not profile_dir.is_dir()
+
+    def test_default_raises_value_error(self, profile_env):
+        with pytest.raises(ValueError, match="default"):
+            delete_profile("default", yes=True)
+
+    def test_nonexistent_raises_file_not_found(self, profile_env):
+        with pytest.raises(FileNotFoundError):
+            delete_profile("nonexistent", yes=True)
+
+
+# ===================================================================
+# TestListProfiles
+# ===================================================================
+
+class TestListProfiles:
+    """Tests for list_profiles()."""
+
+    def test_returns_default_when_no_named_profiles(self, profile_env):
+        profiles = list_profiles()
+        names = [p.name for p in profiles]
+        assert "default" in names
+
+    def test_includes_named_profiles(self, profile_env):
+        create_profile("alpha", no_alias=True)
+        create_profile("beta", no_alias=True)
+        profiles = list_profiles()
+        names = [p.name for p in profiles]
+        assert "alpha" in names
+        assert "beta" in names
+
+    def test_sorted_alphabetically(self, profile_env):
+        create_profile("zebra", no_alias=True)
+        create_profile("alpha", no_alias=True)
+        create_profile("middle", no_alias=True)
+        profiles = list_profiles()
+        named = [p.name for p in profiles if not p.is_default]
+        assert named == sorted(named)
+
+    def test_default_is_first(self, profile_env):
+        create_profile("alpha", no_alias=True)
+        profiles = list_profiles()
+        assert profiles[0].name == "default"
+        assert profiles[0].is_default is True
+
+
+# ===================================================================
+# TestActiveProfile
+# ===================================================================
+
+class TestActiveProfile:
+    """Tests for set_active_profile() / get_active_profile()."""
+
+    def test_set_and_get_roundtrip(self, profile_env):
+        create_profile("coder", no_alias=True)
+        set_active_profile("coder")
+        assert get_active_profile() == "coder"
+
+    def test_no_file_returns_default(self, profile_env):
+        assert get_active_profile() == "default"
+
+    def test_empty_file_returns_default(self, profile_env):
+        tmp_path = profile_env
+        active_path = tmp_path / ".hermes" / "active_profile"
+        active_path.write_text("")
+        assert get_active_profile() == "default"
+
+    def test_set_to_default_removes_file(self, profile_env):
+        tmp_path = profile_env
+        create_profile("coder", no_alias=True)
+        set_active_profile("coder")
+        active_path = tmp_path / ".hermes" / "active_profile"
+        assert active_path.exists()
+
+        set_active_profile("default")
+        assert not active_path.exists()
+
+    def test_set_nonexistent_raises(self, profile_env):
+        with pytest.raises(FileNotFoundError):
+            set_active_profile("nonexistent")
+
+
+# ===================================================================
+# TestGetActiveProfileName
+# ===================================================================
+
+class TestGetActiveProfileName:
+    """Tests for get_active_profile_name()."""
+
+    def test_default_hermes_home_returns_default(self, profile_env):
+        # HERMES_HOME points to tmp_path/.hermes which is the default
+        assert get_active_profile_name() == "default"
+
+    def test_profile_path_returns_profile_name(self, profile_env, monkeypatch):
+        tmp_path = profile_env
+        create_profile("coder", no_alias=True)
+        profile_dir = tmp_path / ".hermes" / "profiles" / "coder"
+        monkeypatch.setenv("HERMES_HOME", str(profile_dir))
+        assert get_active_profile_name() == "coder"
+
+    def test_custom_path_returns_custom(self, profile_env, monkeypatch):
+        tmp_path = profile_env
+        custom = tmp_path / "some" / "other" / "path"
+        custom.mkdir(parents=True)
+        monkeypatch.setenv("HERMES_HOME", str(custom))
+        assert get_active_profile_name() == "custom"
+
+
+# ===================================================================
+# TestResolveProfileEnv
+# ===================================================================
+
+class TestResolveProfileEnv:
+    """Tests for resolve_profile_env()."""
+
+    def test_existing_profile_returns_path(self, profile_env):
+        tmp_path = profile_env
+        create_profile("coder", no_alias=True)
+        result = resolve_profile_env("coder")
+        assert result == str(tmp_path / ".hermes" / "profiles" / "coder")
+
+    def test_default_returns_default_home(self, profile_env):
+        tmp_path = profile_env
+        result = resolve_profile_env("default")
+        assert result == str(tmp_path / ".hermes")
+
+    def test_nonexistent_raises_file_not_found(self, profile_env):
+        with pytest.raises(FileNotFoundError):
+            resolve_profile_env("nonexistent")
+
+    def test_invalid_name_raises_value_error(self, profile_env):
+        with pytest.raises(ValueError):
+            resolve_profile_env("INVALID!")
+
+
+# ===================================================================
+# TestAliasCollision
+# ===================================================================
+
+class TestAliasCollision:
+    """Tests for check_alias_collision()."""
+
+    def test_normal_name_returns_none(self, profile_env):
+        # Mock 'which' to return not-found
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=1, stdout="")
+            result = check_alias_collision("mybot")
+        assert result is None
+
+    def test_reserved_name_returns_message(self, profile_env):
+        result = check_alias_collision("hermes")
+        assert result is not None
+        assert "reserved" in result.lower()
+
+    def test_subcommand_returns_message(self, profile_env):
+        result = check_alias_collision("chat")
+        assert result is not None
+        assert "subcommand" in result.lower()
+
+    def test_default_is_reserved(self, profile_env):
+        result = check_alias_collision("default")
+        assert result is not None
+        assert "reserved" in result.lower()
+
+
+# ===================================================================
+# TestRenameProfile
+# ===================================================================
+
+class TestRenameProfile:
+    """Tests for rename_profile()."""
+
+    def test_renames_directory(self, profile_env):
+        tmp_path = profile_env
+        create_profile("oldname", no_alias=True)
+        old_dir = tmp_path / ".hermes" / "profiles" / "oldname"
+        assert old_dir.is_dir()
+
+        # Mock alias collision to avoid subprocess calls
+        with patch("hermes_cli.profiles.check_alias_collision", return_value="skip"):
+            new_dir = rename_profile("oldname", "newname")
+
+        assert not old_dir.is_dir()
+        assert new_dir.is_dir()
+        assert new_dir == tmp_path / ".hermes" / "profiles" / "newname"
+
+    def test_default_raises_value_error(self, profile_env):
+        with pytest.raises(ValueError, match="default"):
+            rename_profile("default", "newname")
+
+    def test_rename_to_default_raises_value_error(self, profile_env):
+        create_profile("coder", no_alias=True)
+        with pytest.raises(ValueError, match="default"):
+            rename_profile("coder", "default")
+
+    def test_nonexistent_raises_file_not_found(self, profile_env):
+        with pytest.raises(FileNotFoundError):
+            rename_profile("nonexistent", "newname")
+
+    def test_target_exists_raises_file_exists(self, profile_env):
+        create_profile("alpha", no_alias=True)
+        create_profile("beta", no_alias=True)
+        with pytest.raises(FileExistsError):
+            rename_profile("alpha", "beta")
+
+
+# ===================================================================
+# TestExportImport
+# ===================================================================
+
+class TestExportImport:
+    """Tests for export_profile() / import_profile()."""
+
+    def test_export_creates_tar_gz(self, profile_env, tmp_path):
+        create_profile("coder", no_alias=True)
+        # Put a marker file so we can verify content
+        profile_dir = get_profile_dir("coder")
+        (profile_dir / "marker.txt").write_text("hello")
+
+        output = tmp_path / "export" / "coder.tar.gz"
+        output.parent.mkdir(parents=True, exist_ok=True)
+        result = export_profile("coder", str(output))
+
+        assert Path(result).exists()
+        assert tarfile.is_tarfile(str(result))
+
+    def test_import_restores_from_archive(self, profile_env, tmp_path):
+        # Create and export a profile
+        create_profile("coder", no_alias=True)
+        profile_dir = get_profile_dir("coder")
+        (profile_dir / "marker.txt").write_text("hello")
+
+        archive_path = tmp_path / "export" / "coder.tar.gz"
+        archive_path.parent.mkdir(parents=True, exist_ok=True)
+        export_profile("coder", str(archive_path))
+
+        # Delete the profile, then import it back under a new name
+        import shutil
+        shutil.rmtree(profile_dir)
+        assert not profile_dir.is_dir()
+
+        imported = import_profile(str(archive_path), name="coder")
+        assert imported.is_dir()
+        assert (imported / "marker.txt").read_text() == "hello"
+
+    def test_import_to_existing_name_raises(self, profile_env, tmp_path):
+        create_profile("coder", no_alias=True)
+        profile_dir = get_profile_dir("coder")
+
+        archive_path = tmp_path / "export" / "coder.tar.gz"
+        archive_path.parent.mkdir(parents=True, exist_ok=True)
+        export_profile("coder", str(archive_path))
+
+        # Importing to same existing name should fail
+        with pytest.raises(FileExistsError):
+            import_profile(str(archive_path), name="coder")
+
+    def test_export_nonexistent_raises(self, profile_env, tmp_path):
+        with pytest.raises(FileNotFoundError):
+            export_profile("nonexistent", str(tmp_path / "out.tar.gz"))
+
+
+# ===================================================================
+# TestProfileIsolation
+# ===================================================================
+
+class TestProfileIsolation:
+    """Verify that two profiles have completely separate paths."""
+
+    def test_separate_config_paths(self, profile_env):
+        create_profile("alpha", no_alias=True)
+        create_profile("beta", no_alias=True)
+        alpha_dir = get_profile_dir("alpha")
+        beta_dir = get_profile_dir("beta")
+        assert alpha_dir / "config.yaml" != beta_dir / "config.yaml"
+        assert str(alpha_dir) not in str(beta_dir)
+
+    def test_separate_state_db_paths(self, profile_env):
+        alpha_dir = get_profile_dir("alpha")
+        beta_dir = get_profile_dir("beta")
+        assert alpha_dir / "state.db" != beta_dir / "state.db"
+
+    def test_separate_skills_paths(self, profile_env):
+        create_profile("alpha", no_alias=True)
+        create_profile("beta", no_alias=True)
+        alpha_dir = get_profile_dir("alpha")
+        beta_dir = get_profile_dir("beta")
+        assert alpha_dir / "skills" != beta_dir / "skills"
+        # Verify both exist and are independent dirs
+        assert (alpha_dir / "skills").is_dir()
+        assert (beta_dir / "skills").is_dir()
+
+
+# ===================================================================
+# TestCompletion
+# ===================================================================
+
+class TestCompletion:
+    """Tests for bash/zsh completion generators."""
+
+    def test_bash_completion_contains_complete(self):
+        script = generate_bash_completion()
+        assert len(script) > 0
+        assert "complete" in script
+
+    def test_zsh_completion_contains_compdef(self):
+        script = generate_zsh_completion()
+        assert len(script) > 0
+        assert "compdef" in script
+
+    def test_bash_completion_has_hermes_profiles_function(self):
+        script = generate_bash_completion()
+        assert "_hermes_profiles" in script
+
+    def test_zsh_completion_has_hermes_function(self):
+        script = generate_zsh_completion()
+        assert "_hermes" in script
+
+
+# ===================================================================
+# TestGetProfilesRoot / TestGetDefaultHermesHome (internal helpers)
+# ===================================================================
+
+class TestInternalHelpers:
+    """Tests for _get_profiles_root() and _get_default_hermes_home()."""
+
+    def test_profiles_root_under_home(self, profile_env):
+        tmp_path = profile_env
+        root = _get_profiles_root()
+        assert root == tmp_path / ".hermes" / "profiles"
+
+    def test_default_hermes_home(self, profile_env):
+        tmp_path = profile_env
+        home = _get_default_hermes_home()
+        assert home == tmp_path / ".hermes"
+
+
+# ===================================================================
+# Edge cases and additional coverage
+# ===================================================================
+
+class TestEdgeCases:
+    """Additional edge-case tests."""
+
+    def test_create_profile_returns_correct_path(self, profile_env):
+        tmp_path = profile_env
+        result = create_profile("mybot", no_alias=True)
+        expected = tmp_path / ".hermes" / "profiles" / "mybot"
+        assert result == expected
+
+    def test_list_profiles_default_info_fields(self, profile_env):
+        profiles = list_profiles()
+        default = [p for p in profiles if p.name == "default"][0]
+        assert default.is_default is True
+        assert default.gateway_running is False
+        assert default.skill_count == 0
+
+    def test_gateway_running_check_with_pid_file(self, profile_env):
+        """Verify _check_gateway_running reads pid file and probes os.kill."""
+        from hermes_cli.profiles import _check_gateway_running
+        tmp_path = profile_env
+        default_home = tmp_path / ".hermes"
+
+        # No pid file -> not running
+        assert _check_gateway_running(default_home) is False
+
+        # Write a PID file with a JSON payload
+        pid_file = default_home / "gateway.pid"
+        pid_file.write_text(json.dumps({"pid": 99999}))
+
+        # os.kill(99999, 0) should raise ProcessLookupError -> not running
+        assert _check_gateway_running(default_home) is False
+
+        # Mock os.kill to simulate a running process
+        with patch("os.kill", return_value=None):
+            assert _check_gateway_running(default_home) is True
+
+    def test_gateway_running_check_plain_pid(self, profile_env):
+        """Pid file containing just a number (legacy format)."""
+        from hermes_cli.profiles import _check_gateway_running
+        tmp_path = profile_env
+        default_home = tmp_path / ".hermes"
+        pid_file = default_home / "gateway.pid"
+        pid_file.write_text("99999")
+
+        with patch("os.kill", return_value=None):
+            assert _check_gateway_running(default_home) is True
+
+    def test_profile_name_boundary_single_char(self):
+        """Single alphanumeric character is valid."""
+        validate_profile_name("a")
+        validate_profile_name("1")
+
+    def test_profile_name_boundary_all_hyphens(self):
+        """Name starting with hyphen is invalid."""
+        with pytest.raises(ValueError):
+            validate_profile_name("-abc")
+
+    def test_profile_name_underscore_start(self):
+        """Name starting with underscore is invalid (must start with [a-z0-9])."""
+        with pytest.raises(ValueError):
+            validate_profile_name("_abc")
+
+    def test_clone_from_named_profile(self, profile_env):
+        """Clone config from a named (non-default) profile."""
+        tmp_path = profile_env
+        # Create source profile with config
+        source_dir = create_profile("source", no_alias=True)
+        (source_dir / "config.yaml").write_text("model: cloned")
+        (source_dir / ".env").write_text("SECRET=yes")
+
+        target_dir = create_profile(
+            "target", clone_from="source", clone_config=True, no_alias=True,
+        )
+        assert (target_dir / "config.yaml").read_text() == "model: cloned"
+        assert (target_dir / ".env").read_text() == "SECRET=yes"
+
+    def test_delete_clears_active_profile(self, profile_env):
+        """Deleting the active profile resets active to default."""
+        tmp_path = profile_env
+        create_profile("coder", no_alias=True)
+        set_active_profile("coder")
+        assert get_active_profile() == "coder"
+
+        with patch("hermes_cli.profiles._cleanup_gateway_service"):
+            delete_profile("coder", yes=True)
+
+        assert get_active_profile() == "default"

tests/plugins/test_holographic.py

@@ -0,0 +1,248 @@
+"""Tests for holographic.py — pure HRR math operations.
+
+All tests are synthetic: no filesystem, no database, no external state.
+"""
+
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import numpy as np
+import pytest
+
+# Plugin path: prefer home dir install, fall back to in-repo copy
+_plugin_dir = Path.home() / ".hermes" / "plugins" / "hermes-memory-store"
+if not _plugin_dir.exists():
+    _plugin_dir = Path(__file__).resolve().parent.parent.parent / "plugins" / "hermes-memory-store"
+sys.path.insert(0, str(_plugin_dir))
+
+from holographic import (
+    _HAS_NUMPY,
+    bind,
+    bundle,
+    bytes_to_phases,
+    encode_atom,
+    encode_fact,
+    encode_text,
+    phases_to_bytes,
+    similarity,
+    snr_estimate,
+    unbind,
+)
+
+
+DIM = 256  # Smaller dim for fast tests; math properties hold at any dim.
+
+
+class TestEncodeAtom:
+    def test_deterministic(self):
+        """Same input always produces the identical vector."""
+        v1 = encode_atom("hello", DIM)
+        v2 = encode_atom("hello", DIM)
+        np.testing.assert_array_equal(v1, v2)
+
+    def test_shape_and_dtype(self):
+        v = encode_atom("test", DIM)
+        assert v.shape == (DIM,)
+        assert v.dtype == np.float64
+
+    def test_phase_range(self):
+        """All phases must be in [0, 2π)."""
+        v = encode_atom("range_check", DIM)
+        assert np.all(v >= 0.0)
+        assert np.all(v < 2.0 * np.pi)
+
+    def test_near_orthogonal(self):
+        """Random unrelated words should have near-zero similarity."""
+        words = ["apple", "quantum", "bicycle", "telescope", "jazz"]
+        vectors = [encode_atom(w, DIM) for w in words]
+        for i in range(len(vectors)):
+            for j in range(i + 1, len(vectors)):
+                sim = similarity(vectors[i], vectors[j])
+                assert abs(sim) < 0.15, f"'{words[i]}' vs '{words[j]}': sim={sim:.4f}"
+
+
+class TestBindUnbind:
+    def test_roundtrip(self):
+        """unbind(bind(a, b), b) should recover a exactly."""
+        a = encode_atom("concept_a", DIM)
+        b = encode_atom("concept_b", DIM)
+        bound = bind(a, b)
+        recovered = unbind(bound, b)
+        np.testing.assert_allclose(recovered, a, atol=1e-10)
+
+    def test_commutative(self):
+        """bind(a, b) == bind(b, a) — phase addition is commutative."""
+        a = encode_atom("alpha", DIM)
+        b = encode_atom("beta", DIM)
+        np.testing.assert_allclose(bind(a, b), bind(b, a), atol=1e-10)
+
+    def test_bound_dissimilar_to_inputs(self):
+        """The bound vector should be quasi-orthogonal to both inputs."""
+        a = encode_atom("dog", DIM)
+        b = encode_atom("cat", DIM)
+        bound = bind(a, b)
+        assert abs(similarity(bound, a)) < 0.15
+        assert abs(similarity(bound, b)) < 0.15
+
+
+class TestBundle:
+    def test_preserves_similarity(self):
+        """Bundled vector should be similar to each of its components."""
+        vecs = [encode_atom(f"item_{i}", DIM) for i in range(3)]
+        bundled = bundle(*vecs)
+        for v in vecs:
+            sim = similarity(bundled, v)
+            assert sim > 0.2, f"Bundle lost signal: sim={sim:.4f}"
+
+    def test_capacity_degrades(self):
+        """Similarity to each component should decrease as more items are added."""
+        target = encode_atom("target", DIM)
+        sims = []
+        for n in [2, 5, 10, 20]:
+            others = [encode_atom(f"noise_{i}", DIM) for i in range(n - 1)]
+            bundled = bundle(target, *others)
+            sims.append(similarity(bundled, target))
+        # Similarity should generally decrease (allow minor non-monotonicity)
+        assert sims[0] > sims[-1], f"No degradation: {sims}"
+
+
+class TestSimilarity:
+    def test_identity(self):
+        """similarity(a, a) should be exactly 1.0."""
+        a = encode_atom("self", DIM)
+        assert similarity(a, a) == pytest.approx(1.0)
+
+    def test_orthogonal_near_zero(self):
+        """Random vectors should have similarity near 0."""
+        sims = []
+        for i in range(10):
+            a = encode_atom(f"rand_a_{i}", DIM)
+            b = encode_atom(f"rand_b_{i}", DIM)
+            sims.append(similarity(a, b))
+        mean_sim = np.mean(sims)
+        assert abs(mean_sim) < 0.1, f"Mean similarity too high: {mean_sim:.4f}"
+
+
+class TestEncodeText:
+    def test_order_invariant(self):
+        """Bag-of-words should be order-invariant."""
+        v1 = encode_text("the quick brown fox", DIM)
+        v2 = encode_text("fox brown quick the", DIM)
+        sim = similarity(v1, v2)
+        assert sim == pytest.approx(1.0, abs=1e-10)
+
+    def test_similar_texts_high_similarity(self):
+        """Texts sharing words should have high similarity."""
+        v1 = encode_text("the cat sat on the mat", DIM)
+        v2 = encode_text("the cat on the mat", DIM)
+        sim = similarity(v1, v2)
+        assert sim > 0.5, f"Similar texts low sim: {sim:.4f}"
+
+    def test_empty_text(self):
+        """Empty text should return a valid vector (the __hrr_empty__ atom)."""
+        v = encode_text("", DIM)
+        assert v.shape == (DIM,)
+
+
+class TestEncodeFact:
+    def test_entity_extraction(self):
+        """Unbinding entity from fact should recover content signal."""
+        content = "prefers rust for systems programming"
+        entities = ["peppi"]
+
+        fact_vec = encode_fact(content, entities, DIM)
+        content_vec = encode_text(content, DIM)
+
+        # Unbind: fact - bind(entity, ROLE_ENTITY) should be similar to bind(content, ROLE_CONTENT)
+        role_entity = encode_atom("__hrr_role_entity__", DIM)
+        role_content = encode_atom("__hrr_role_content__", DIM)
+        entity_vec = encode_atom("peppi", DIM)
+
+        # Extract what's associated with peppi's entity role
+        probe = unbind(fact_vec, bind(entity_vec, role_entity))
+
+        # The extracted signal should have nonzero similarity to the content-role binding
+        content_bound = bind(content_vec, role_content)
+        sim = similarity(probe, content_bound)
+        # At DIM=256, 2-component bundle: SNR≈11, but phase cosine similarity compresses
+        # the signal. Noise baseline is ~0.035 std; signal should be above 0.03.
+        assert sim > 0.03, f"Entity extraction failed: sim={sim:.4f}"
+
+    def test_multiple_entities(self):
+        """Facts with multiple entities should encode all of them."""
+        fact_vec = encode_fact("loves pizza", ["alice", "bob"], DIM)
+        assert fact_vec.shape == (DIM,)
+        # Both entities should be recoverable (above noise floor)
+        role_entity = encode_atom("__hrr_role_entity__", DIM)
+        for name in ["alice", "bob"]:
+            entity_vec = encode_atom(name, DIM)
+            probe = unbind(fact_vec, bind(entity_vec, role_entity))
+            # Just verify it's a valid vector (deeper tests would check signal)
+            assert probe.shape == (DIM,)
+
+
+class TestSerialization:
+    def test_roundtrip(self):
+        """bytes_to_phases(phases_to_bytes(v)) should recover v exactly."""
+        v = encode_atom("serialize_me", DIM)
+        data = phases_to_bytes(v)
+        recovered = bytes_to_phases(data)
+        np.testing.assert_array_equal(v, recovered)
+
+    def test_byte_size(self):
+        """float64 * dim = 8 * dim bytes."""
+        v = encode_atom("size_check", DIM)
+        data = phases_to_bytes(v)
+        assert len(data) == DIM * 8
+
+
+class TestSNREstimate:
+    def test_formula(self):
+        """SNR should match sqrt(dim / n_items)."""
+        import math
+        assert snr_estimate(1024, 4) == pytest.approx(math.sqrt(1024 / 4))
+        assert snr_estimate(1024, 256) == pytest.approx(math.sqrt(1024 / 256))
+
+    def test_empty(self):
+        """Zero items → infinite SNR."""
+        assert snr_estimate(1024, 0) == float("inf")
+
+    def test_warning_logged(self, caplog):
+        """SNR < 2.0 should emit a warning."""
+        import logging
+        with caplog.at_level(logging.WARNING):
+            snr_estimate(4, 4)  # SNR = 1.0
+        assert "near capacity" in caplog.text.lower()
+
+
+class TestNumpyGuard:
+    def test_raises_without_numpy(self):
+        """All public functions should raise RuntimeError when numpy is absent."""
+        import holographic
+
+        original = holographic._HAS_NUMPY
+        try:
+            holographic._HAS_NUMPY = False
+            with pytest.raises(RuntimeError, match="numpy is required"):
+                encode_atom("test", DIM)
+            with pytest.raises(RuntimeError, match="numpy is required"):
+                bind(np.zeros(DIM), np.zeros(DIM))
+            with pytest.raises(RuntimeError, match="numpy is required"):
+                unbind(np.zeros(DIM), np.zeros(DIM))
+            with pytest.raises(RuntimeError, match="numpy is required"):
+                bundle(np.zeros(DIM))
+            with pytest.raises(RuntimeError, match="numpy is required"):
+                similarity(np.zeros(DIM), np.zeros(DIM))
+            with pytest.raises(RuntimeError, match="numpy is required"):
+                encode_text("test", DIM)
+            with pytest.raises(RuntimeError, match="numpy is required"):
+                encode_fact("test", ["e"], DIM)
+            with pytest.raises(RuntimeError, match="numpy is required"):
+                phases_to_bytes(np.zeros(DIM))
+            with pytest.raises(RuntimeError, match="numpy is required"):
+                bytes_to_phases(b"\x00" * DIM * 8)
+            with pytest.raises(RuntimeError, match="numpy is required"):
+                snr_estimate(DIM, 1)
+        finally:
+            holographic._HAS_NUMPY = original

tests/plugins/test_holographic_provider.py

@@ -0,0 +1,336 @@
+"""Tests for the holographic memory MemoryProvider adapter.
+
+Tests the HolographicMemoryProvider interface — registration, tool handling,
+prefetch, session end hooks, and memory bridging.
+"""
+
+import json
+import sys
+import pytest
+from pathlib import Path
+from unittest.mock import MagicMock
+
+# Add plugin dir to path so imports work
+_plugin_dir = Path(__file__).resolve().parent.parent.parent / "plugins" / "hermes-memory-store"
+sys.path.insert(0, str(_plugin_dir))
+
+from agent.memory_manager import MemoryManager
+from agent.builtin_memory_provider import BuiltinMemoryProvider
+
+
+def _make_provider(tmp_path, config=None):
+    """Create a HolographicMemoryProvider with a temp DB."""
+    # Import inside function to avoid module-level issues
+    sys.path.insert(0, str(_plugin_dir))
+    from plugins import HolographicMemoryProvider  # noqa: F811
+    # Use the full import path
+    from importlib import import_module
+    init_mod = import_module("plugins.hermes-memory-store")
+
+    cfg = config or {}
+    cfg.setdefault("db_path", str(tmp_path / "test.db"))
+    provider = init_mod.HolographicMemoryProvider(config=cfg)
+    provider.initialize(session_id="test-session")
+    return provider
+
+
+@pytest.fixture
+def provider(tmp_path):
+    """Create an initialized holographic provider."""
+    sys.path.insert(0, str(_plugin_dir.parent))
+    # Direct import
+    spec_path = _plugin_dir / "__init__.py"
+    import importlib.util
+    spec = importlib.util.spec_from_file_location(
+        "hermes_memory_store_test",
+        spec_path,
+        submodule_search_locations=[str(_plugin_dir)],
+    )
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["hermes_memory_store_test"] = mod
+    # Pre-populate submodule references
+    store_spec = importlib.util.spec_from_file_location(
+        "hermes_memory_store_test.store",
+        _plugin_dir / "store.py",
+    )
+    store_mod = importlib.util.module_from_spec(store_spec)
+    sys.modules["hermes_memory_store_test.store"] = store_mod
+    store_spec.loader.exec_module(store_mod)
+
+    retrieval_spec = importlib.util.spec_from_file_location(
+        "hermes_memory_store_test.retrieval",
+        _plugin_dir / "retrieval.py",
+    )
+    retrieval_mod = importlib.util.module_from_spec(retrieval_spec)
+    sys.modules["hermes_memory_store_test.retrieval"] = retrieval_mod
+    retrieval_spec.loader.exec_module(retrieval_mod)
+
+    spec.loader.exec_module(mod)
+
+    cfg = {"db_path": str(tmp_path / "test.db")}
+    p = mod.HolographicMemoryProvider(config=cfg)
+    p.initialize(session_id="test-session")
+    yield p
+    p.shutdown()
+
+    # Cleanup
+    for key in list(sys.modules):
+        if key.startswith("hermes_memory_store_test"):
+            del sys.modules[key]
+
+
+class TestProviderRegistration:
+    def test_register_calls_register_memory_provider(self, tmp_path):
+        """register(ctx) should call ctx.register_memory_provider()."""
+        import importlib.util
+
+        spec = importlib.util.spec_from_file_location(
+            "hermes_memory_store_reg",
+            _plugin_dir / "__init__.py",
+            submodule_search_locations=[str(_plugin_dir)],
+        )
+        mod = importlib.util.module_from_spec(spec)
+        sys.modules["hermes_memory_store_reg"] = mod
+
+        store_spec = importlib.util.spec_from_file_location(
+            "hermes_memory_store_reg.store", _plugin_dir / "store.py")
+        store_mod = importlib.util.module_from_spec(store_spec)
+        sys.modules["hermes_memory_store_reg.store"] = store_mod
+        store_spec.loader.exec_module(store_mod)
+
+        retrieval_spec = importlib.util.spec_from_file_location(
+            "hermes_memory_store_reg.retrieval", _plugin_dir / "retrieval.py")
+        retrieval_mod = importlib.util.module_from_spec(retrieval_spec)
+        sys.modules["hermes_memory_store_reg.retrieval"] = retrieval_mod
+        retrieval_spec.loader.exec_module(retrieval_mod)
+
+        spec.loader.exec_module(mod)
+
+        ctx = MagicMock()
+        mod.register(ctx)
+        ctx.register_memory_provider.assert_called_once()
+        registered = ctx.register_memory_provider.call_args[0][0]
+        assert registered.name == "holographic"
+
+        for key in list(sys.modules):
+            if key.startswith("hermes_memory_store_reg"):
+                del sys.modules[key]
+
+
+class TestToolHandling:
+    def test_add_and_search(self, provider):
+        """Add a fact via tool call, then search for it."""
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "add", "content": "User prefers vim over emacs"}
+        ))
+        assert "fact_id" in result
+        fact_id = result["fact_id"]
+
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "search", "query": "vim emacs"}
+        ))
+        assert result["count"] >= 1
+        contents = [r["content"] for r in result["results"]]
+        assert any("vim" in c for c in contents)
+
+    def test_add_and_probe(self, provider):
+        """Add facts about an entity, then probe it."""
+        provider.handle_tool_call(
+            "fact_store", {"action": "add", "content": "Peppi uses Rust for systems work"}
+        )
+        provider.handle_tool_call(
+            "fact_store", {"action": "add", "content": "Peppi prefers Neovim"}
+        )
+
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "probe", "entity": "peppi"}
+        ))
+        assert result["count"] >= 1
+
+    def test_related(self, provider):
+        """Test related entity lookup."""
+        provider.handle_tool_call(
+            "fact_store", {"action": "add", "content": "Peppi uses Rust for systems work"}
+        )
+        provider.handle_tool_call(
+            "fact_store", {"action": "add", "content": "Rust ensures memory safety"}
+        )
+
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "related", "entity": "rust"}
+        ))
+        assert "results" in result
+        assert "count" in result
+
+    def test_reason(self, provider):
+        """Test compositional reasoning across entities."""
+        provider.handle_tool_call(
+            "fact_store", {"action": "add", "content": "Peppi uses Rust for backend work"}
+        )
+        provider.handle_tool_call(
+            "fact_store", {"action": "add", "content": "The backend handles API requests"}
+        )
+
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "reason", "entities": ["peppi", "backend"]}
+        ))
+        assert "results" in result
+
+    def test_feedback(self, provider):
+        """Test trust scoring via feedback."""
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "add", "content": "Test feedback fact"}
+        ))
+        fact_id = result["fact_id"]
+
+        result = json.loads(provider.handle_tool_call(
+            "fact_feedback", {"action": "helpful", "fact_id": fact_id}
+        ))
+        assert "error" not in result
+
+    def test_update_and_remove(self, provider):
+        """Test CRUD operations."""
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "add", "content": "Will be updated"}
+        ))
+        fact_id = result["fact_id"]
+
+        # Update
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "update", "fact_id": fact_id, "content": "Updated content"}
+        ))
+        assert result["updated"]
+
+        # Remove
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "remove", "fact_id": fact_id}
+        ))
+        assert result["removed"]
+
+    def test_all_handlers_return_json(self, provider):
+        """Every tool call must return valid JSON."""
+        # Add a fact first
+        r = provider.handle_tool_call("fact_store", {"action": "add", "content": "JSON test"})
+        parsed = json.loads(r)
+        fact_id = parsed["fact_id"]
+
+        # Test every action
+        actions = [
+            ("fact_store", {"action": "search", "query": "JSON"}),
+            ("fact_store", {"action": "list"}),
+            ("fact_store", {"action": "probe", "entity": "test"}),
+            ("fact_store", {"action": "related", "entity": "test"}),
+            ("fact_store", {"action": "reason", "entities": ["test"]}),
+            ("fact_store", {"action": "contradict"}),
+            ("fact_feedback", {"action": "helpful", "fact_id": fact_id}),
+        ]
+        for tool_name, args in actions:
+            result = provider.handle_tool_call(tool_name, args)
+            json.loads(result)  # Should not raise
+
+
+class TestPrefetch:
+    def test_prefetch_returns_matching_facts(self, provider):
+        """Prefetch should return facts matching the query."""
+        provider.handle_tool_call(
+            "fact_store", {"action": "add", "content": "The deploy pipeline uses Docker"}
+        )
+        result = provider.prefetch("deploy pipeline")
+        assert "Docker" in result or "deploy" in result
+
+    def test_prefetch_empty_when_no_facts(self, provider):
+        assert provider.prefetch("anything") == ""
+
+
+class TestSystemPromptBlock:
+    def test_empty_when_no_facts(self, provider):
+        assert provider.system_prompt_block() == ""
+
+    def test_shows_count_with_facts(self, provider):
+        provider.handle_tool_call(
+            "fact_store", {"action": "add", "content": "Fact one"}
+        )
+        provider.handle_tool_call(
+            "fact_store", {"action": "add", "content": "Fact two"}
+        )
+        block = provider.system_prompt_block()
+        assert "2 facts" in block
+        assert "Holographic" in block
+
+
+class TestSessionEndHook:
+    def test_extracts_preferences(self, provider):
+        """on_session_end should extract preference patterns."""
+        provider._config["auto_extract"] = True
+        messages = [
+            {"role": "user", "content": "I prefer dark mode for all my editors"},
+            {"role": "assistant", "content": "Noted, I'll remember that."},
+        ]
+        provider.on_session_end(messages)
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "list"}
+        ))
+        assert result["count"] >= 1
+
+    def test_skips_when_disabled(self, provider):
+        """on_session_end should do nothing when auto_extract is False."""
+        provider._config["auto_extract"] = False
+        messages = [
+            {"role": "user", "content": "I prefer dark mode"},
+        ]
+        provider.on_session_end(messages)
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "list"}
+        ))
+        assert result["count"] == 0
+
+    def test_skips_assistant_messages(self, provider):
+        """Only user messages should be scanned."""
+        provider._config["auto_extract"] = True
+        messages = [
+            {"role": "assistant", "content": "I prefer to help you with that"},
+        ]
+        provider.on_session_end(messages)
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "list"}
+        ))
+        assert result["count"] == 0
+
+
+class TestMemoryBridge:
+    def test_mirrors_builtin_writes(self, provider):
+        """on_memory_write should store facts from the builtin memory tool."""
+        provider.on_memory_write("add", "user", "Timezone: US Pacific")
+        result = json.loads(provider.handle_tool_call(
+            "fact_store", {"action": "search", "query": "timezone pacific"}
+        ))
+        assert result["count"] >= 1
+
+
+class TestManagerIntegration:
+    def test_coexists_with_builtin(self, provider):
+        """Holographic provider works alongside builtin in MemoryManager."""
+        mgr = MemoryManager()
+        mgr.add_provider(BuiltinMemoryProvider())
+        mgr.add_provider(provider)
+
+        assert mgr.provider_names == ["builtin", "holographic"]
+
+        # Tools from holographic are available
+        schemas = mgr.get_all_tool_schemas()
+        names = {s["name"] for s in schemas}
+        assert "fact_store" in names
+        assert "fact_feedback" in names
+
+        # Tool routing works
+        result = json.loads(mgr.handle_tool_call(
+            "fact_store", {"action": "add", "content": "Manager integration test"}
+        ))
+        assert result["status"] == "added"
+
+        # Memory bridge fires
+        mgr.on_memory_write("add", "memory", "Test fact from builtin")
+        result = json.loads(mgr.handle_tool_call(
+            "fact_store", {"action": "search", "query": "test fact builtin"}
+        ))
+        assert result["count"] >= 1

tests/tools/test_credential_files.py

@@ -0,0 +1,158 @@
+"""Tests for credential file passthrough registry (tools/credential_files.py)."""
+
+import os
+from pathlib import Path
+
+import pytest
+
+from tools.credential_files import (
+    clear_credential_files,
+    get_credential_file_mounts,
+    register_credential_file,
+    register_credential_files,
+    reset_config_cache,
+)
+
+
+@pytest.fixture(autouse=True)
+def _clean_registry():
+    """Reset registry between tests."""
+    clear_credential_files()
+    reset_config_cache()
+    yield
+    clear_credential_files()
+    reset_config_cache()
+
+
+class TestRegisterCredentialFile:
+    def test_registers_existing_file(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        (tmp_path / "token.json").write_text('{"token": "abc"}')
+
+        result = register_credential_file("token.json")
+
+        assert result is True
+        mounts = get_credential_file_mounts()
+        assert len(mounts) == 1
+        assert mounts[0]["host_path"] == str(tmp_path / "token.json")
+        assert mounts[0]["container_path"] == "/root/.hermes/token.json"
+
+    def test_skips_missing_file(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+
+        result = register_credential_file("nonexistent.json")
+
+        assert result is False
+        assert get_credential_file_mounts() == []
+
+    def test_custom_container_base(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        (tmp_path / "cred.json").write_text("{}")
+
+        register_credential_file("cred.json", container_base="/home/user/.hermes")
+
+        mounts = get_credential_file_mounts()
+        assert mounts[0]["container_path"] == "/home/user/.hermes/cred.json"
+
+    def test_deduplicates_by_container_path(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        (tmp_path / "token.json").write_text("{}")
+
+        register_credential_file("token.json")
+        register_credential_file("token.json")
+
+        mounts = get_credential_file_mounts()
+        assert len(mounts) == 1
+
+
+class TestRegisterCredentialFiles:
+    def test_string_entries(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        (tmp_path / "a.json").write_text("{}")
+        (tmp_path / "b.json").write_text("{}")
+
+        missing = register_credential_files(["a.json", "b.json"])
+
+        assert missing == []
+        assert len(get_credential_file_mounts()) == 2
+
+    def test_dict_entries(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        (tmp_path / "token.json").write_text("{}")
+
+        missing = register_credential_files([
+            {"path": "token.json", "description": "OAuth token"},
+        ])
+
+        assert missing == []
+        assert len(get_credential_file_mounts()) == 1
+
+    def test_returns_missing_files(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        (tmp_path / "exists.json").write_text("{}")
+
+        missing = register_credential_files([
+            "exists.json",
+            "missing.json",
+            {"path": "also_missing.json"},
+        ])
+
+        assert missing == ["missing.json", "also_missing.json"]
+        assert len(get_credential_file_mounts()) == 1
+
+    def test_empty_list(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        assert register_credential_files([]) == []
+
+
+class TestConfigCredentialFiles:
+    def test_loads_from_config(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        (tmp_path / "oauth.json").write_text("{}")
+        (tmp_path / "config.yaml").write_text(
+            "terminal:\n  credential_files:\n    - oauth.json\n"
+        )
+
+        mounts = get_credential_file_mounts()
+
+        assert len(mounts) == 1
+        assert mounts[0]["host_path"] == str(tmp_path / "oauth.json")
+
+    def test_config_skips_missing_files(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        (tmp_path / "config.yaml").write_text(
+            "terminal:\n  credential_files:\n    - nonexistent.json\n"
+        )
+
+        mounts = get_credential_file_mounts()
+        assert mounts == []
+
+    def test_combines_skill_and_config(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        (tmp_path / "skill_token.json").write_text("{}")
+        (tmp_path / "config_token.json").write_text("{}")
+        (tmp_path / "config.yaml").write_text(
+            "terminal:\n  credential_files:\n    - config_token.json\n"
+        )
+
+        register_credential_file("skill_token.json")
+        mounts = get_credential_file_mounts()
+
+        assert len(mounts) == 2
+        paths = {m["container_path"] for m in mounts}
+        assert "/root/.hermes/skill_token.json" in paths
+        assert "/root/.hermes/config_token.json" in paths
+
+
+class TestGetMountsRechecksExistence:
+    def test_removed_file_excluded_from_mounts(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        token = tmp_path / "token.json"
+        token.write_text("{}")
+
+        register_credential_file("token.json")
+        assert len(get_credential_file_mounts()) == 1
+
+        # Delete the file after registration
+        token.unlink()
+        assert get_credential_file_mounts() == []

tests/tools/test_send_message_missing_platforms.py

@@ -0,0 +1,334 @@
+"""Tests for _send_mattermost, _send_matrix, _send_homeassistant, _send_dingtalk."""
+
+import asyncio
+import os
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from tools.send_message_tool import (
+    _send_dingtalk,
+    _send_homeassistant,
+    _send_mattermost,
+    _send_matrix,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_aiohttp_resp(status, json_data=None, text_data=None):
+    """Build a minimal async-context-manager mock for an aiohttp response."""
+    resp = AsyncMock()
+    resp.status = status
+    resp.json = AsyncMock(return_value=json_data or {})
+    resp.text = AsyncMock(return_value=text_data or "")
+    return resp
+
+
+def _make_aiohttp_session(resp):
+    """Wrap a response mock in a session mock that supports async-with for post/put."""
+    request_ctx = MagicMock()
+    request_ctx.__aenter__ = AsyncMock(return_value=resp)
+    request_ctx.__aexit__ = AsyncMock(return_value=False)
+
+    session = MagicMock()
+    session.post = MagicMock(return_value=request_ctx)
+    session.put = MagicMock(return_value=request_ctx)
+
+    session_ctx = MagicMock()
+    session_ctx.__aenter__ = AsyncMock(return_value=session)
+    session_ctx.__aexit__ = AsyncMock(return_value=False)
+    return session_ctx, session
+
+
+# ---------------------------------------------------------------------------
+# _send_mattermost
+# ---------------------------------------------------------------------------
+
+
+class TestSendMattermost:
+    def test_success(self):
+        resp = _make_aiohttp_resp(201, json_data={"id": "post123"})
+        session_ctx, session = _make_aiohttp_session(resp)
+
+        with patch("aiohttp.ClientSession", return_value=session_ctx), \
+             patch.dict(os.environ, {"MATTERMOST_URL": "", "MATTERMOST_TOKEN": ""}, clear=False):
+            extra = {"url": "https://mm.example.com"}
+            result = asyncio.run(_send_mattermost("tok-abc", extra, "channel1", "hello"))
+
+        assert result == {"success": True, "platform": "mattermost", "chat_id": "channel1", "message_id": "post123"}
+        session.post.assert_called_once()
+        call_kwargs = session.post.call_args
+        assert call_kwargs[0][0] == "https://mm.example.com/api/v4/posts"
+        assert call_kwargs[1]["headers"]["Authorization"] == "Bearer tok-abc"
+        assert call_kwargs[1]["json"] == {"channel_id": "channel1", "message": "hello"}
+
+    def test_http_error(self):
+        resp = _make_aiohttp_resp(400, text_data="Bad Request")
+        session_ctx, _ = _make_aiohttp_session(resp)
+
+        with patch("aiohttp.ClientSession", return_value=session_ctx):
+            result = asyncio.run(_send_mattermost(
+                "tok", {"url": "https://mm.example.com"}, "ch", "hi"
+            ))
+
+        assert "error" in result
+        assert "400" in result["error"]
+        assert "Bad Request" in result["error"]
+
+    def test_missing_config(self):
+        with patch.dict(os.environ, {"MATTERMOST_URL": "", "MATTERMOST_TOKEN": ""}, clear=False):
+            result = asyncio.run(_send_mattermost("", {}, "ch", "hi"))
+
+        assert "error" in result
+        assert "MATTERMOST_URL" in result["error"] or "not configured" in result["error"]
+
+    def test_env_var_fallback(self):
+        resp = _make_aiohttp_resp(200, json_data={"id": "p99"})
+        session_ctx, session = _make_aiohttp_session(resp)
+
+        with patch("aiohttp.ClientSession", return_value=session_ctx), \
+             patch.dict(os.environ, {"MATTERMOST_URL": "https://mm.env.com", "MATTERMOST_TOKEN": "env-tok"}, clear=False):
+            result = asyncio.run(_send_mattermost("", {}, "ch", "hi"))
+
+        assert result["success"] is True
+        call_kwargs = session.post.call_args
+        assert "https://mm.env.com" in call_kwargs[0][0]
+        assert call_kwargs[1]["headers"]["Authorization"] == "Bearer env-tok"
+
+
+# ---------------------------------------------------------------------------
+# _send_matrix
+# ---------------------------------------------------------------------------
+
+
+class TestSendMatrix:
+    def test_success(self):
+        resp = _make_aiohttp_resp(200, json_data={"event_id": "$abc123"})
+        session_ctx, session = _make_aiohttp_session(resp)
+
+        with patch("aiohttp.ClientSession", return_value=session_ctx), \
+             patch.dict(os.environ, {"MATRIX_HOMESERVER": "", "MATRIX_ACCESS_TOKEN": ""}, clear=False):
+            extra = {"homeserver": "https://matrix.example.com"}
+            result = asyncio.run(_send_matrix("syt_tok", extra, "!room:example.com", "hello matrix"))
+
+        assert result == {
+            "success": True,
+            "platform": "matrix",
+            "chat_id": "!room:example.com",
+            "message_id": "$abc123",
+        }
+        session.put.assert_called_once()
+        call_kwargs = session.put.call_args
+        url = call_kwargs[0][0]
+        assert url.startswith("https://matrix.example.com/_matrix/client/v3/rooms/!room:example.com/send/m.room.message/")
+        assert call_kwargs[1]["headers"]["Authorization"] == "Bearer syt_tok"
+        assert call_kwargs[1]["json"] == {"msgtype": "m.text", "body": "hello matrix"}
+
+    def test_http_error(self):
+        resp = _make_aiohttp_resp(403, text_data="Forbidden")
+        session_ctx, _ = _make_aiohttp_session(resp)
+
+        with patch("aiohttp.ClientSession", return_value=session_ctx):
+            result = asyncio.run(_send_matrix(
+                "tok", {"homeserver": "https://matrix.example.com"},
+                "!room:example.com", "hi"
+            ))
+
+        assert "error" in result
+        assert "403" in result["error"]
+        assert "Forbidden" in result["error"]
+
+    def test_missing_config(self):
+        with patch.dict(os.environ, {"MATRIX_HOMESERVER": "", "MATRIX_ACCESS_TOKEN": ""}, clear=False):
+            result = asyncio.run(_send_matrix("", {}, "!room:example.com", "hi"))
+
+        assert "error" in result
+        assert "MATRIX_HOMESERVER" in result["error"] or "not configured" in result["error"]
+
+    def test_env_var_fallback(self):
+        resp = _make_aiohttp_resp(200, json_data={"event_id": "$ev1"})
+        session_ctx, session = _make_aiohttp_session(resp)
+
+        with patch("aiohttp.ClientSession", return_value=session_ctx), \
+             patch.dict(os.environ, {
+                 "MATRIX_HOMESERVER": "https://matrix.env.com",
+                 "MATRIX_ACCESS_TOKEN": "env-tok",
+             }, clear=False):
+            result = asyncio.run(_send_matrix("", {}, "!r:env.com", "hi"))
+
+        assert result["success"] is True
+        url = session.put.call_args[0][0]
+        assert "matrix.env.com" in url
+
+    def test_txn_id_is_unique_across_calls(self):
+        """Each call should generate a distinct transaction ID in the URL."""
+        txn_ids = []
+
+        def capture(*args, **kwargs):
+            url = args[0]
+            txn_ids.append(url.rsplit("/", 1)[-1])
+            ctx = MagicMock()
+            ctx.__aenter__ = AsyncMock(return_value=_make_aiohttp_resp(200, json_data={"event_id": "$x"}))
+            ctx.__aexit__ = AsyncMock(return_value=False)
+            return ctx
+
+        session = MagicMock()
+        session.put = capture
+        session_ctx = MagicMock()
+        session_ctx.__aenter__ = AsyncMock(return_value=session)
+        session_ctx.__aexit__ = AsyncMock(return_value=False)
+
+        extra = {"homeserver": "https://matrix.example.com"}
+
+        import time
+        with patch("aiohttp.ClientSession", return_value=session_ctx):
+            asyncio.run(_send_matrix("tok", extra, "!r:example.com", "first"))
+        time.sleep(0.002)
+        with patch("aiohttp.ClientSession", return_value=session_ctx):
+            asyncio.run(_send_matrix("tok", extra, "!r:example.com", "second"))
+
+        assert len(txn_ids) == 2
+        assert txn_ids[0] != txn_ids[1]
+
+
+# ---------------------------------------------------------------------------
+# _send_homeassistant
+# ---------------------------------------------------------------------------
+
+
+class TestSendHomeAssistant:
+    def test_success(self):
+        resp = _make_aiohttp_resp(200)
+        session_ctx, session = _make_aiohttp_session(resp)
+
+        with patch("aiohttp.ClientSession", return_value=session_ctx), \
+             patch.dict(os.environ, {"HASS_URL": "", "HASS_TOKEN": ""}, clear=False):
+            extra = {"url": "https://hass.example.com"}
+            result = asyncio.run(_send_homeassistant("hass-tok", extra, "mobile_app_phone", "alert!"))
+
+        assert result == {"success": True, "platform": "homeassistant", "chat_id": "mobile_app_phone"}
+        session.post.assert_called_once()
+        call_kwargs = session.post.call_args
+        assert call_kwargs[0][0] == "https://hass.example.com/api/services/notify/notify"
+        assert call_kwargs[1]["headers"]["Authorization"] == "Bearer hass-tok"
+        assert call_kwargs[1]["json"] == {"message": "alert!", "target": "mobile_app_phone"}
+
+    def test_http_error(self):
+        resp = _make_aiohttp_resp(401, text_data="Unauthorized")
+        session_ctx, _ = _make_aiohttp_session(resp)
+
+        with patch("aiohttp.ClientSession", return_value=session_ctx):
+            result = asyncio.run(_send_homeassistant(
+                "bad-tok", {"url": "https://hass.example.com"},
+                "target", "msg"
+            ))
+
+        assert "error" in result
+        assert "401" in result["error"]
+        assert "Unauthorized" in result["error"]
+
+    def test_missing_config(self):
+        with patch.dict(os.environ, {"HASS_URL": "", "HASS_TOKEN": ""}, clear=False):
+            result = asyncio.run(_send_homeassistant("", {}, "target", "msg"))
+
+        assert "error" in result
+        assert "HASS_URL" in result["error"] or "not configured" in result["error"]
+
+    def test_env_var_fallback(self):
+        resp = _make_aiohttp_resp(200)
+        session_ctx, session = _make_aiohttp_session(resp)
+
+        with patch("aiohttp.ClientSession", return_value=session_ctx), \
+             patch.dict(os.environ, {"HASS_URL": "https://hass.env.com", "HASS_TOKEN": "env-tok"}, clear=False):
+            result = asyncio.run(_send_homeassistant("", {}, "notify_target", "hi"))
+
+        assert result["success"] is True
+        url = session.post.call_args[0][0]
+        assert "hass.env.com" in url
+
+
+# ---------------------------------------------------------------------------
+# _send_dingtalk
+# ---------------------------------------------------------------------------
+
+
+class TestSendDingtalk:
+    def _make_httpx_resp(self, status_code=200, json_data=None):
+        resp = MagicMock()
+        resp.status_code = status_code
+        resp.json = MagicMock(return_value=json_data or {"errcode": 0, "errmsg": "ok"})
+        resp.raise_for_status = MagicMock()
+        return resp
+
+    def _make_httpx_client(self, resp):
+        client = AsyncMock()
+        client.post = AsyncMock(return_value=resp)
+        client_ctx = MagicMock()
+        client_ctx.__aenter__ = AsyncMock(return_value=client)
+        client_ctx.__aexit__ = AsyncMock(return_value=False)
+        return client_ctx, client
+
+    def test_success(self):
+        resp = self._make_httpx_resp(json_data={"errcode": 0, "errmsg": "ok"})
+        client_ctx, client = self._make_httpx_client(resp)
+
+        with patch("httpx.AsyncClient", return_value=client_ctx):
+            extra = {"webhook_url": "https://oapi.dingtalk.com/robot/send?access_token=abc"}
+            result = asyncio.run(_send_dingtalk(extra, "ignored", "hello dingtalk"))
+
+        assert result == {"success": True, "platform": "dingtalk", "chat_id": "ignored"}
+        client.post.assert_awaited_once()
+        call_kwargs = client.post.await_args
+        assert call_kwargs[0][0] == "https://oapi.dingtalk.com/robot/send?access_token=abc"
+        assert call_kwargs[1]["json"] == {"msgtype": "text", "text": {"content": "hello dingtalk"}}
+
+    def test_api_error_in_response_body(self):
+        """DingTalk always returns HTTP 200 but signals errors via errcode."""
+        resp = self._make_httpx_resp(json_data={"errcode": 310000, "errmsg": "sign not match"})
+        client_ctx, _ = self._make_httpx_client(resp)
+
+        with patch("httpx.AsyncClient", return_value=client_ctx):
+            result = asyncio.run(_send_dingtalk(
+                {"webhook_url": "https://oapi.dingtalk.com/robot/send?access_token=bad"},
+                "ch", "hi"
+            ))
+
+        assert "error" in result
+        assert "sign not match" in result["error"]
+
+    def test_http_error(self):
+        """If raise_for_status throws, the error is caught and returned."""
+        resp = self._make_httpx_resp(status_code=429)
+        resp.raise_for_status = MagicMock(side_effect=Exception("429 Too Many Requests"))
+        client_ctx, _ = self._make_httpx_client(resp)
+
+        with patch("httpx.AsyncClient", return_value=client_ctx):
+            result = asyncio.run(_send_dingtalk(
+                {"webhook_url": "https://oapi.dingtalk.com/robot/send?access_token=tok"},
+                "ch", "hi"
+            ))
+
+        assert "error" in result
+        assert "DingTalk send failed" in result["error"]
+
+    def test_missing_config(self):
+        with patch.dict(os.environ, {"DINGTALK_WEBHOOK_URL": ""}, clear=False):
+            result = asyncio.run(_send_dingtalk({}, "ch", "hi"))
+
+        assert "error" in result
+        assert "DINGTALK_WEBHOOK_URL" in result["error"] or "not configured" in result["error"]
+
+    def test_env_var_fallback(self):
+        resp = self._make_httpx_resp(json_data={"errcode": 0, "errmsg": "ok"})
+        client_ctx, client = self._make_httpx_client(resp)
+
+        with patch("httpx.AsyncClient", return_value=client_ctx), \
+             patch.dict(os.environ, {"DINGTALK_WEBHOOK_URL": "https://oapi.dingtalk.com/robot/send?access_token=env"}, clear=False):
+            result = asyncio.run(_send_dingtalk({}, "ch", "hi"))
+
+        assert result["success"] is True
+        call_kwargs = client.post.await_args
+        assert "access_token=env" in call_kwargs[0][0]

tests/tools/test_transcription_tools.py

@@ -96,6 +96,7 @@ class TestGetProviderFallbackPriority:
         monkeypatch.setenv("GROQ_API_KEY", "gsk-test")
         monkeypatch.setenv("VOICE_TOOLS_OPENAI_KEY", "sk-test")
         with patch("tools.transcription_tools._HAS_FASTER_WHISPER", False), \
+             patch("tools.transcription_tools._has_local_command", return_value=False), \
              patch("tools.transcription_tools._HAS_OPENAI", True):
             from tools.transcription_tools import _get_provider
             assert _get_provider({}) == "groq"
@@ -130,9 +131,10 @@ class TestExplicitProviderRespected:
     def test_explicit_local_no_fallback_to_openai(self, monkeypatch):
         """GH-1774: provider=local must not silently fall back to openai
         even when an OpenAI API key is set."""
-        monkeypatch.setenv("OPENAI_API_KEY", "sk-real-key-here")
+        monkeypatch.setenv("OPENAI_API_KEY", "***")
         monkeypatch.delenv("GROQ_API_KEY", raising=False)
         with patch("tools.transcription_tools._HAS_FASTER_WHISPER", False), \
+             patch("tools.transcription_tools._has_local_command", return_value=False), \
              patch("tools.transcription_tools._HAS_OPENAI", True):
             from tools.transcription_tools import _get_provider
             result = _get_provider({"provider": "local"})
@@ -141,6 +143,7 @@ class TestExplicitProviderRespected:
     def test_explicit_local_no_fallback_to_groq(self, monkeypatch):
         monkeypatch.setenv("GROQ_API_KEY", "gsk-test")
         with patch("tools.transcription_tools._HAS_FASTER_WHISPER", False), \
+             patch("tools.transcription_tools._has_local_command", return_value=False), \
              patch("tools.transcription_tools._HAS_OPENAI", True):
             from tools.transcription_tools import _get_provider
             result = _get_provider({"provider": "local"})
@@ -181,6 +184,7 @@ class TestExplicitProviderRespected:
         monkeypatch.setenv("OPENAI_API_KEY", "sk-real-key")
         monkeypatch.delenv("GROQ_API_KEY", raising=False)
         with patch("tools.transcription_tools._HAS_FASTER_WHISPER", False), \
+             patch("tools.transcription_tools._has_local_command", return_value=False), \
              patch("tools.transcription_tools._HAS_OPENAI", True):
             from tools.transcription_tools import _get_provider
             # Empty dict = no explicit provider, uses DEFAULT_PROVIDER auto-detect
@@ -191,6 +195,7 @@ class TestExplicitProviderRespected:
         monkeypatch.setenv("GROQ_API_KEY", "gsk-test")
         monkeypatch.setenv("OPENAI_API_KEY", "sk-real-key")
         with patch("tools.transcription_tools._HAS_FASTER_WHISPER", False), \
+             patch("tools.transcription_tools._has_local_command", return_value=False), \
              patch("tools.transcription_tools._HAS_OPENAI", True):
             from tools.transcription_tools import _get_provider
             result = _get_provider({})

tools/credential_files.py

@@ -0,0 +1,163 @@
+"""Credential file passthrough registry for remote terminal backends.
+
+Skills that declare ``required_credential_files`` in their frontmatter need
+those files available inside sandboxed execution environments (Modal, Docker).
+By default remote backends create bare containers with no host files.
+
+This module provides a session-scoped registry so skill-declared credential
+files (and user-configured overrides) are mounted into remote sandboxes.
+
+Two sources feed the registry:
+
+1. **Skill declarations** — when a skill is loaded via ``skill_view``, its
+   ``required_credential_files`` entries are registered here if the files
+   exist on the host.
+2. **User config** — ``terminal.credential_files`` in config.yaml lets users
+   explicitly list additional files to mount.
+
+Remote backends (``tools/environments/modal.py``, ``docker.py``) call
+:func:`get_credential_file_mounts` at sandbox creation time.
+
+Each registered entry is a dict::
+
+    {
+        "host_path": "/home/user/.hermes/google_token.json",
+        "container_path": "/root/.hermes/google_token.json",
+    }
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Dict, List
+
+logger = logging.getLogger(__name__)
+
+# Session-scoped list of credential files to mount.
+# Key: container_path (deduplicated), Value: host_path
+_registered_files: Dict[str, str] = {}
+
+# Cache for config-based file list (loaded once per process).
+_config_files: List[Dict[str, str]] | None = None
+
+
+def _resolve_hermes_home() -> Path:
+    return Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
+
+
+def register_credential_file(
+    relative_path: str,
+    container_base: str = "/root/.hermes",
+) -> bool:
+    """Register a credential file for mounting into remote sandboxes.
+
+    *relative_path* is relative to ``HERMES_HOME`` (e.g. ``google_token.json``).
+    Returns True if the file exists on the host and was registered.
+    """
+    hermes_home = _resolve_hermes_home()
+    host_path = hermes_home / relative_path
+    if not host_path.is_file():
+        logger.debug("credential_files: skipping %s (not found)", host_path)
+        return False
+
+    container_path = f"{container_base.rstrip('/')}/{relative_path}"
+    _registered_files[container_path] = str(host_path)
+    logger.debug("credential_files: registered %s -> %s", host_path, container_path)
+    return True
+
+
+def register_credential_files(
+    entries: list,
+    container_base: str = "/root/.hermes",
+) -> List[str]:
+    """Register multiple credential files from skill frontmatter entries.
+
+    Each entry is either a string (relative path) or a dict with a ``path``
+    key.  Returns the list of relative paths that were NOT found on the host
+    (i.e. missing files).
+    """
+    missing = []
+    for entry in entries:
+        if isinstance(entry, str):
+            rel_path = entry.strip()
+        elif isinstance(entry, dict):
+            rel_path = (entry.get("path") or "").strip()
+        else:
+            continue
+        if not rel_path:
+            continue
+        if not register_credential_file(rel_path, container_base):
+            missing.append(rel_path)
+    return missing
+
+
+def _load_config_files() -> List[Dict[str, str]]:
+    """Load ``terminal.credential_files`` from config.yaml (cached)."""
+    global _config_files
+    if _config_files is not None:
+        return _config_files
+
+    result: List[Dict[str, str]] = []
+    try:
+        hermes_home = _resolve_hermes_home()
+        config_path = hermes_home / "config.yaml"
+        if config_path.exists():
+            import yaml
+
+            with open(config_path) as f:
+                cfg = yaml.safe_load(f) or {}
+            cred_files = cfg.get("terminal", {}).get("credential_files")
+            if isinstance(cred_files, list):
+                for item in cred_files:
+                    if isinstance(item, str) and item.strip():
+                        host_path = hermes_home / item.strip()
+                        if host_path.is_file():
+                            container_path = f"/root/.hermes/{item.strip()}"
+                            result.append({
+                                "host_path": str(host_path),
+                                "container_path": container_path,
+                            })
+    except Exception as e:
+        logger.debug("Could not read terminal.credential_files from config: %s", e)
+
+    _config_files = result
+    return _config_files
+
+
+def get_credential_file_mounts() -> List[Dict[str, str]]:
+    """Return all credential files that should be mounted into remote sandboxes.
+
+    Each item has ``host_path`` and ``container_path`` keys.
+    Combines skill-registered files and user config.
+    """
+    mounts: Dict[str, str] = {}
+
+    # Skill-registered files
+    for container_path, host_path in _registered_files.items():
+        # Re-check existence (file may have been deleted since registration)
+        if Path(host_path).is_file():
+            mounts[container_path] = host_path
+
+    # Config-based files
+    for entry in _load_config_files():
+        cp = entry["container_path"]
+        if cp not in mounts and Path(entry["host_path"]).is_file():
+            mounts[cp] = entry["host_path"]
+
+    return [
+        {"host_path": hp, "container_path": cp}
+        for cp, hp in mounts.items()
+    ]
+
+
+def clear_credential_files() -> None:
+    """Reset the skill-scoped registry (e.g. on session reset)."""
+    _registered_files.clear()
+
+
+def reset_config_cache() -> None:
+    """Force re-read of config on next access (for testing)."""
+    global _config_files
+    _config_files = None

tools/environments/docker.py

@@ -312,6 +312,24 @@ class DockerEnvironment(BaseEnvironment):
         elif workspace_explicitly_mounted:
             logger.debug("Skipping docker cwd mount: /workspace already mounted by user config")
 
+        # Mount credential files (OAuth tokens, etc.) declared by skills.
+        # Read-only so the container can authenticate but not modify host creds.
+        try:
+            from tools.credential_files import get_credential_file_mounts
+
+            for mount_entry in get_credential_file_mounts():
+                volume_args.extend([
+                    "-v",
+                    f"{mount_entry['host_path']}:{mount_entry['container_path']}:ro",
+                ])
+                logger.info(
+                    "Docker: mounting credential %s -> %s",
+                    mount_entry["host_path"],
+                    mount_entry["container_path"],
+                )
+        except Exception as e:
+            logger.debug("Docker: could not load credential file mounts: %s", e)
+
         logger.info(f"Docker volume_args: {volume_args}")
         all_run_args = list(_SECURITY_ARGS) + writable_args + resource_args + volume_args
         logger.info(f"Docker run_args: {all_run_args}")
@@ -406,8 +424,17 @@ class DockerEnvironment(BaseEnvironment):
         if effective_stdin is not None:
             cmd.append("-i")
         cmd.extend(["-w", work_dir])
-        hermes_env = _load_hermes_env_vars() if self._forward_env else {}
-        for key in self._forward_env:
+        # Combine explicit docker_forward_env with skill-declared env_passthrough
+        # vars so skills that declare required_environment_variables (e.g. Notion)
+        # have their keys forwarded into the container automatically.
+        forward_keys = set(self._forward_env)
+        try:
+            from tools.env_passthrough import get_all_passthrough
+            forward_keys |= get_all_passthrough()
+        except Exception:
+            pass
+        hermes_env = _load_hermes_env_vars() if forward_keys else {}
+        for key in sorted(forward_keys):
             value = os.getenv(key)
             if value is None:
                 value = hermes_env.get(key)

tools/environments/modal.py

@@ -137,6 +137,28 @@ class ModalEnvironment(BaseEnvironment):
                 ],
             )
 
+        # Mount credential files (OAuth tokens, etc.) declared by skills.
+        # These are read-only copies so the sandbox can authenticate with
+        # external services but can't modify the host's credentials.
+        cred_mounts = []
+        try:
+            from tools.credential_files import get_credential_file_mounts
+
+            for mount_entry in get_credential_file_mounts():
+                cred_mounts.append(
+                    _modal.Mount.from_local_file(
+                        mount_entry["host_path"],
+                        remote_path=mount_entry["container_path"],
+                    )
+                )
+                logger.info(
+                    "Modal: mounting credential %s -> %s",
+                    mount_entry["host_path"],
+                    mount_entry["container_path"],
+                )
+        except Exception as e:
+            logger.debug("Modal: could not load credential file mounts: %s", e)
+
         # Start the async worker thread and create sandbox on it
         # so all gRPC channels are bound to the worker's event loop.
         self._worker.start()
@@ -145,23 +167,90 @@ class ModalEnvironment(BaseEnvironment):
             app = await _modal.App.lookup.aio(
                 "hermes-agent", create_if_missing=True
             )
+            create_kwargs = dict(sandbox_kwargs)
+            if cred_mounts:
+                existing_mounts = list(create_kwargs.pop("mounts", []))
+                existing_mounts.extend(cred_mounts)
+                create_kwargs["mounts"] = existing_mounts
             sandbox = await _modal.Sandbox.create.aio(
                 "sleep", "infinity",
                 image=effective_image,
                 app=app,
-                timeout=int(sandbox_kwargs.pop("timeout", 3600)),
-                **sandbox_kwargs,
+                timeout=int(create_kwargs.pop("timeout", 3600)),
+                **create_kwargs,
             )
             return app, sandbox
 
         self._app, self._sandbox = self._worker.run_coroutine(
             _create_sandbox(), timeout=300
         )
+        # Track synced credential files to avoid redundant pushes.
+        # Key: container_path, Value: (mtime, size) of last synced version.
+        self._synced_creds: Dict[str, tuple] = {}
         logger.info("Modal: sandbox created (task=%s)", self._task_id)
 
+    def _sync_credential_files(self) -> None:
+        """Push credential files into the running sandbox.
+
+        Mounts are set at sandbox creation, but credentials may be created
+        later (e.g. OAuth setup mid-session).  This writes the current file
+        content into the sandbox via exec(), so new/updated credentials are
+        available without recreating the sandbox.
+        """
+        try:
+            from tools.credential_files import get_credential_file_mounts
+
+            mounts = get_credential_file_mounts()
+            if not mounts:
+                return
+
+            for entry in mounts:
+                host_path = entry["host_path"]
+                container_path = entry["container_path"]
+                hp = Path(host_path)
+                try:
+                    stat = hp.stat()
+                    file_key = (stat.st_mtime, stat.st_size)
+                except OSError:
+                    continue
+
+                # Skip if already synced with same mtime+size
+                if self._synced_creds.get(container_path) == file_key:
+                    continue
+
+                try:
+                    content = hp.read_text(encoding="utf-8")
+                except Exception:
+                    continue
+
+                # Write via base64 to avoid shell escaping issues with JSON
+                import base64
+                b64 = base64.b64encode(content.encode("utf-8")).decode("ascii")
+                container_dir = str(Path(container_path).parent)
+                cmd = (
+                    f"mkdir -p {shlex.quote(container_dir)} && "
+                    f"echo {shlex.quote(b64)} | base64 -d > {shlex.quote(container_path)}"
+                )
+
+                _cp = container_path  # capture for closure
+
+                async def _write():
+                    proc = await self._sandbox.exec.aio("bash", "-c", cmd)
+                    await proc.wait.aio()
+
+                self._worker.run_coroutine(_write(), timeout=15)
+                self._synced_creds[container_path] = file_key
+                logger.debug("Modal: synced credential %s -> %s", host_path, container_path)
+        except Exception as e:
+            logger.debug("Modal: credential file sync failed: %s", e)
+
     def execute(self, command: str, cwd: str = "", *,
                 timeout: int | None = None,
                 stdin_data: str | None = None) -> dict:
+        # Sync credential files before each command so mid-session
+        # OAuth setups are picked up without requiring a restart.
+        self._sync_credential_files()
+
         if stdin_data is not None:
             marker = f"HERMES_EOF_{uuid.uuid4().hex[:8]}"
             while marker in stdin_data:

tools/send_message_tool.py

@@ -343,6 +343,14 @@ async def _send_to_platform(platform, pconfig, chat_id, message, thread_id=None,
             result = await _send_email(pconfig.extra, chat_id, chunk)
         elif platform == Platform.SMS:
             result = await _send_sms(pconfig.api_key, chat_id, chunk)
+        elif platform == Platform.MATTERMOST:
+            result = await _send_mattermost(pconfig.token, pconfig.extra, chat_id, chunk)
+        elif platform == Platform.MATRIX:
+            result = await _send_matrix(pconfig.token, pconfig.extra, chat_id, chunk)
+        elif platform == Platform.HOMEASSISTANT:
+            result = await _send_homeassistant(pconfig.token, pconfig.extra, chat_id, chunk)
+        elif platform == Platform.DINGTALK:
+            result = await _send_dingtalk(pconfig.extra, chat_id, chunk)
         else:
             result = {"error": f"Direct sending not yet implemented for {platform.value}"}
 
@@ -666,6 +674,109 @@ async def _send_sms(auth_token, chat_id, message):
         return {"error": f"SMS send failed: {e}"}
 
 
+async def _send_mattermost(token, extra, chat_id, message):
+    """Send via Mattermost REST API."""
+    try:
+        import aiohttp
+    except ImportError:
+        return {"error": "aiohttp not installed. Run: pip install aiohttp"}
+    try:
+        base_url = (extra.get("url") or os.getenv("MATTERMOST_URL", "")).rstrip("/")
+        token = token or os.getenv("MATTERMOST_TOKEN", "")
+        if not base_url or not token:
+            return {"error": "Mattermost not configured (MATTERMOST_URL, MATTERMOST_TOKEN required)"}
+        url = f"{base_url}/api/v4/posts"
+        headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
+        async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30)) as session:
+            async with session.post(url, headers=headers, json={"channel_id": chat_id, "message": message}) as resp:
+                if resp.status not in (200, 201):
+                    body = await resp.text()
+                    return {"error": f"Mattermost API error ({resp.status}): {body}"}
+                data = await resp.json()
+        return {"success": True, "platform": "mattermost", "chat_id": chat_id, "message_id": data.get("id")}
+    except Exception as e:
+        return {"error": f"Mattermost send failed: {e}"}
+
+
+async def _send_matrix(token, extra, chat_id, message):
+    """Send via Matrix Client-Server API."""
+    try:
+        import aiohttp
+    except ImportError:
+        return {"error": "aiohttp not installed. Run: pip install aiohttp"}
+    try:
+        homeserver = (extra.get("homeserver") or os.getenv("MATRIX_HOMESERVER", "")).rstrip("/")
+        token = token or os.getenv("MATRIX_ACCESS_TOKEN", "")
+        if not homeserver or not token:
+            return {"error": "Matrix not configured (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN required)"}
+        txn_id = f"hermes_{int(time.time() * 1000)}"
+        url = f"{homeserver}/_matrix/client/v3/rooms/{chat_id}/send/m.room.message/{txn_id}"
+        headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
+        async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30)) as session:
+            async with session.put(url, headers=headers, json={"msgtype": "m.text", "body": message}) as resp:
+                if resp.status not in (200, 201):
+                    body = await resp.text()
+                    return {"error": f"Matrix API error ({resp.status}): {body}"}
+                data = await resp.json()
+        return {"success": True, "platform": "matrix", "chat_id": chat_id, "message_id": data.get("event_id")}
+    except Exception as e:
+        return {"error": f"Matrix send failed: {e}"}
+
+
+async def _send_homeassistant(token, extra, chat_id, message):
+    """Send via Home Assistant notify service."""
+    try:
+        import aiohttp
+    except ImportError:
+        return {"error": "aiohttp not installed. Run: pip install aiohttp"}
+    try:
+        hass_url = (extra.get("url") or os.getenv("HASS_URL", "")).rstrip("/")
+        token = token or os.getenv("HASS_TOKEN", "")
+        if not hass_url or not token:
+            return {"error": "Home Assistant not configured (HASS_URL, HASS_TOKEN required)"}
+        url = f"{hass_url}/api/services/notify/notify"
+        headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
+        async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=30)) as session:
+            async with session.post(url, headers=headers, json={"message": message, "target": chat_id}) as resp:
+                if resp.status not in (200, 201):
+                    body = await resp.text()
+                    return {"error": f"Home Assistant API error ({resp.status}): {body}"}
+        return {"success": True, "platform": "homeassistant", "chat_id": chat_id}
+    except Exception as e:
+        return {"error": f"Home Assistant send failed: {e}"}
+
+
+async def _send_dingtalk(extra, chat_id, message):
+    """Send via DingTalk robot webhook.
+
+    Note: The gateway's DingTalk adapter uses per-session webhook URLs from
+    incoming messages (dingtalk-stream SDK).  For cross-platform send_message
+    delivery we use a static robot webhook URL instead, which must be
+    configured via ``DINGTALK_WEBHOOK_URL`` env var or ``webhook_url`` in the
+    platform's extra config.
+    """
+    try:
+        import httpx
+    except ImportError:
+        return {"error": "httpx not installed"}
+    try:
+        webhook_url = extra.get("webhook_url") or os.getenv("DINGTALK_WEBHOOK_URL", "")
+        if not webhook_url:
+            return {"error": "DingTalk not configured. Set DINGTALK_WEBHOOK_URL env var or webhook_url in dingtalk platform extra config."}
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            resp = await client.post(
+                webhook_url,
+                json={"msgtype": "text", "text": {"content": message}},
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            if data.get("errcode", 0) != 0:
+                return {"error": f"DingTalk API error: {data.get('errmsg', 'unknown')}"}
+        return {"success": True, "platform": "dingtalk", "chat_id": chat_id}
+    except Exception as e:
+        return {"error": f"DingTalk send failed: {e}"}
+
+
 def _check_send_message():
     """Gate send_message on gateway running (always available on messaging platforms)."""
     platform = os.getenv("HERMES_SESSION_PLATFORM", "")

tools/skills_tool.py

@@ -494,7 +494,7 @@ def _is_skill_disabled(name: str, platform: str = None) -> bool:
 
 
 def _find_all_skills(*, skip_disabled: bool = False) -> List[Dict[str, Any]]:
-    """Recursively find all skills in ~/.hermes/skills/.
+    """Recursively find all skills in ~/.hermes/skills/ and external dirs.
 
     Args:
         skip_disabled: If True, return ALL skills regardless of disabled
@@ -504,59 +504,68 @@ def _find_all_skills(*, skip_disabled: bool = False) -> List[Dict[str, Any]]:
     Returns:
         List of skill metadata dicts (name, description, category).
     """
-    skills = []
+    from agent.skill_utils import get_external_skills_dirs
 
-    if not SKILLS_DIR.exists():
-        return skills
+    skills = []
+    seen_names: set = set()
 
     # Load disabled set once (not per-skill)
     disabled = set() if skip_disabled else _get_disabled_skill_names()
 
+    # Scan local dir first, then external dirs (local takes precedence)
+    dirs_to_scan = []
+    if SKILLS_DIR.exists():
+        dirs_to_scan.append(SKILLS_DIR)
+    dirs_to_scan.extend(get_external_skills_dirs())
 
-    for skill_md in SKILLS_DIR.rglob("SKILL.md"):
-        if any(part in _EXCLUDED_SKILL_DIRS for part in skill_md.parts):
-            continue
-
-        skill_dir = skill_md.parent
-
-        try:
-            content = skill_md.read_text(encoding="utf-8")[:4000]
-            frontmatter, body = _parse_frontmatter(content)
-
-            if not skill_matches_platform(frontmatter):
+    for scan_dir in dirs_to_scan:
+        for skill_md in scan_dir.rglob("SKILL.md"):
+            if any(part in _EXCLUDED_SKILL_DIRS for part in skill_md.parts):
                 continue
 
-            name = frontmatter.get("name", skill_dir.name)[:MAX_NAME_LENGTH]
-            if name in disabled:
+            skill_dir = skill_md.parent
+
+            try:
+                content = skill_md.read_text(encoding="utf-8")[:4000]
+                frontmatter, body = _parse_frontmatter(content)
+
+                if not skill_matches_platform(frontmatter):
+                    continue
+
+                name = frontmatter.get("name", skill_dir.name)[:MAX_NAME_LENGTH]
+                if name in seen_names:
+                    continue
+                if name in disabled:
+                    continue
+
+                description = frontmatter.get("description", "")
+                if not description:
+                    for line in body.strip().split("\n"):
+                        line = line.strip()
+                        if line and not line.startswith("#"):
+                            description = line
+                            break
+
+                if len(description) > MAX_DESCRIPTION_LENGTH:
+                    description = description[:MAX_DESCRIPTION_LENGTH - 3] + "..."
+
+                category = _get_category_from_path(skill_md)
+
+                seen_names.add(name)
+                skills.append({
+                    "name": name,
+                    "description": description,
+                    "category": category,
+                })
+
+            except (UnicodeDecodeError, PermissionError) as e:
+                logger.debug("Failed to read skill file %s: %s", skill_md, e)
+                continue
+            except Exception as e:
+                logger.debug(
+                    "Skipping skill at %s: failed to parse: %s", skill_md, e, exc_info=True
+                )
                 continue
-
-            description = frontmatter.get("description", "")
-            if not description:
-                for line in body.strip().split("\n"):
-                    line = line.strip()
-                    if line and not line.startswith("#"):
-                        description = line
-                        break
-
-            if len(description) > MAX_DESCRIPTION_LENGTH:
-                description = description[:MAX_DESCRIPTION_LENGTH - 3] + "..."
-
-            category = _get_category_from_path(skill_md)
-
-            skills.append({
-                "name": name,
-                "description": description,
-                "category": category,
-            })
-
-        except (UnicodeDecodeError, PermissionError) as e:
-            logger.debug("Failed to read skill file %s: %s", skill_md, e)
-            continue
-        except Exception as e:
-            logger.debug(
-                "Skipping skill at %s: failed to parse: %s", skill_md, e, exc_info=True
-            )
-            continue
 
     return skills
 
@@ -756,7 +765,15 @@ def skill_view(name: str, file_path: str = None, task_id: str = None) -> str:
         JSON string with skill content or error message
     """
     try:
-        if not SKILLS_DIR.exists():
+        from agent.skill_utils import get_external_skills_dirs
+
+        # Build list of all skill directories to search
+        all_dirs = []
+        if SKILLS_DIR.exists():
+            all_dirs.append(SKILLS_DIR)
+        all_dirs.extend(get_external_skills_dirs())
+
+        if not all_dirs:
             return json.dumps(
                 {
                     "success": False,
@@ -768,27 +785,37 @@ def skill_view(name: str, file_path: str = None, task_id: str = None) -> str:
         skill_dir = None
         skill_md = None
 
-        # Try direct path first (e.g., "mlops/axolotl")
-        direct_path = SKILLS_DIR / name
-        if direct_path.is_dir() and (direct_path / "SKILL.md").exists():
-            skill_dir = direct_path
-            skill_md = direct_path / "SKILL.md"
-        elif direct_path.with_suffix(".md").exists():
-            skill_md = direct_path.with_suffix(".md")
+        # Search all dirs: local first, then external (first match wins)
+        for search_dir in all_dirs:
+            # Try direct path first (e.g., "mlops/axolotl")
+            direct_path = search_dir / name
+            if direct_path.is_dir() and (direct_path / "SKILL.md").exists():
+                skill_dir = direct_path
+                skill_md = direct_path / "SKILL.md"
+                break
+            elif direct_path.with_suffix(".md").exists():
+                skill_md = direct_path.with_suffix(".md")
+                break
 
-        # Search by directory name
+        # Search by directory name across all dirs
         if not skill_md:
-            for found_skill_md in SKILLS_DIR.rglob("SKILL.md"):
-                if found_skill_md.parent.name == name:
-                    skill_dir = found_skill_md.parent
-                    skill_md = found_skill_md
+            for search_dir in all_dirs:
+                for found_skill_md in search_dir.rglob("SKILL.md"):
+                    if found_skill_md.parent.name == name:
+                        skill_dir = found_skill_md.parent
+                        skill_md = found_skill_md
+                        break
+                if skill_md:
                     break
 
         # Legacy: flat .md files
         if not skill_md:
-            for found_md in SKILLS_DIR.rglob(f"{name}.md"):
-                if found_md.name != "SKILL.md":
-                    skill_md = found_md
+            for search_dir in all_dirs:
+                for found_md in search_dir.rglob(f"{name}.md"):
+                    if found_md.name != "SKILL.md":
+                        skill_md = found_md
+                        break
+                if skill_md:
                     break
 
         if not skill_md or not skill_md.exists():
@@ -815,12 +842,21 @@ def skill_view(name: str, file_path: str = None, task_id: str = None) -> str:
                 ensure_ascii=False,
             )
 
-        # Security: warn if skill is loaded from outside the trusted skills directory
+        # Security: warn if skill is loaded from outside trusted directories
+        # (local skills dir + configured external_dirs are all trusted)
+        _outside_skills_dir = True
+        _trusted_dirs = [SKILLS_DIR.resolve()]
         try:
-            skill_md.resolve().relative_to(SKILLS_DIR.resolve())
-            _outside_skills_dir = False
-        except ValueError:
-            _outside_skills_dir = True
+            _trusted_dirs.extend(d.resolve() for d in all_dirs[1:])
+        except Exception:
+            pass
+        for _td in _trusted_dirs:
+            try:
+                skill_md.resolve().relative_to(_td)
+                _outside_skills_dir = False
+                break
+            except ValueError:
+                continue
 
         # Security: detect common prompt injection patterns
         _INJECTION_PATTERNS = [
@@ -1058,7 +1094,11 @@ def skill_view(name: str, file_path: str = None, task_id: str = None) -> str:
         if script_files:
             linked_files["scripts"] = script_files
 
-        rel_path = str(skill_md.relative_to(SKILLS_DIR))
+        try:
+            rel_path = str(skill_md.relative_to(SKILLS_DIR))
+        except ValueError:
+            # External skill — use path relative to the skill's own parent dir
+            rel_path = str(skill_md.relative_to(skill_md.parent.parent)) if skill_md.parent.parent else skill_md.name
         skill_name = frontmatter.get(
             "name", skill_md.stem if not skill_dir else skill_dir.name
         )
@@ -1106,6 +1146,27 @@ def skill_view(name: str, file_path: str = None, task_id: str = None) -> str:
                     exc_info=True,
                 )
 
+        # Register credential files for mounting into remote sandboxes
+        # (Modal, Docker).  Files that exist on the host are registered;
+        # missing ones are added to the setup_needed indicators.
+        required_cred_files_raw = frontmatter.get("required_credential_files", [])
+        if not isinstance(required_cred_files_raw, list):
+            required_cred_files_raw = []
+        missing_cred_files: list = []
+        if required_cred_files_raw:
+            try:
+                from tools.credential_files import register_credential_files
+
+                missing_cred_files = register_credential_files(required_cred_files_raw)
+                if missing_cred_files:
+                    setup_needed = True
+            except Exception:
+                logger.debug(
+                    "Could not register credential files for skill %s",
+                    skill_name,
+                    exc_info=True,
+                )
+
         result = {
             "success": True,
             "name": skill_name,
@@ -1121,6 +1182,7 @@ def skill_view(name: str, file_path: str = None, task_id: str = None) -> str:
             "required_environment_variables": required_env_vars,
             "required_commands": [],
             "missing_required_environment_variables": remaining_missing_required_envs,
+            "missing_credential_files": missing_cred_files,
             "missing_required_commands": [],
             "setup_needed": setup_needed,
             "setup_skipped": capture_result["setup_skipped"],
@@ -1139,6 +1201,8 @@ def skill_view(name: str, file_path: str = None, task_id: str = None) -> str:
         if setup_needed:
             missing_items = [
                 f"env ${env_name}" for env_name in remaining_missing_required_envs
+            ] + [
+                f"file {path}" for path in missing_cred_files
             ]
             setup_note = _build_setup_note(
                 SkillReadinessStatus.SETUP_NEEDED,

tools/terminal_tool.py

@@ -48,6 +48,7 @@ logger = logging.getLogger(__name__)
 # long-running subprocesses immediately instead of blocking until timeout.
 # ---------------------------------------------------------------------------
 from tools.interrupt import is_interrupted, _interrupt_event  # noqa: F401 — re-exported
+# display_hermes_home imported lazily at call site (stale-module safety during hermes update)
 
 
 # =============================================================================
@@ -157,7 +158,8 @@ def _handle_sudo_failure(output: str, env_type: str) -> str:
     
     for failure in sudo_failures:
         if failure in output:
-            return output + "\n\n💡 Tip: To enable sudo over messaging, add SUDO_PASSWORD to ~/.hermes/.env on the agent machine."
+            from hermes_constants import display_hermes_home as _dhh
+            return output + f"\n\n💡 Tip: To enable sudo over messaging, add SUDO_PASSWORD to {_dhh()}/.env on the agent machine."
     
     return output
 
@@ -1283,7 +1285,8 @@ if __name__ == "__main__":
     print(f"  TERMINAL_MODAL_IMAGE: {os.getenv('TERMINAL_MODAL_IMAGE', default_img)}")
     print(f"  TERMINAL_DAYTONA_IMAGE: {os.getenv('TERMINAL_DAYTONA_IMAGE', default_img)}")
     print(f"  TERMINAL_CWD: {os.getenv('TERMINAL_CWD', os.getcwd())}")
-    print(f"  TERMINAL_SANDBOX_DIR: {os.getenv('TERMINAL_SANDBOX_DIR', '~/.hermes/sandboxes')}")
+    from hermes_constants import display_hermes_home as _dhh
+    print(f"  TERMINAL_SANDBOX_DIR: {os.getenv('TERMINAL_SANDBOX_DIR', f'{_dhh()}/sandboxes')}")
     print(f"  TERMINAL_TIMEOUT: {os.getenv('TERMINAL_TIMEOUT', '60')}")
     print(f"  TERMINAL_LIFETIME_SECONDS: {os.getenv('TERMINAL_LIFETIME_SECONDS', '300')}")
 

tools/tts_tool.py

@@ -832,7 +832,7 @@ TTS_SCHEMA = {
             },
             "output_path": {
                 "type": "string",
-                "description": "Optional custom file path to save the audio. Defaults to ~/.hermes/cache/audio/<timestamp>.mp3"
+                "description": "Optional custom file path to save the audio. Defaults to ~/.hermes/audio_cache/<timestamp>.mp3"
             }
         },
         "required": ["text"]

website/docs/developer-guide/contributing.md

@@ -90,6 +90,7 @@ pytest tests/ -v
 - **Comments**: Only when explaining non-obvious intent, trade-offs, or API quirks
 - **Error handling**: Catch specific exceptions. Use `logger.warning()`/`logger.error()` with `exc_info=True` for unexpected errors
 - **Cross-platform**: Never assume Unix (see below)
+- **Profile-safe paths**: Never hardcode `~/.hermes` — use `get_hermes_home()` from `hermes_constants` for code paths and `display_hermes_home()` for user-facing messages. See [AGENTS.md](https://github.com/NousResearch/hermes-agent/blob/main/AGENTS.md#profiles-multi-instance-support) for full rules.
 
 ## Cross-Platform Compatibility
 

website/docs/developer-guide/creating-skills.md

@@ -168,11 +168,38 @@ required_environment_variables:
 The user can skip setup and keep loading the skill. Hermes never exposes the raw secret value to the model. Gateway and messaging sessions show local setup guidance instead of collecting secrets in-band.
 
 :::tip Sandbox Passthrough
-When your skill is loaded, any declared `required_environment_variables` that are set are **automatically passed through** to `execute_code` and `terminal` sandboxes. Your skill's scripts can access `$TENOR_API_KEY` (or `os.environ["TENOR_API_KEY"]` in Python) without the user needing to configure anything extra. See [Environment Variable Passthrough](/docs/user-guide/security#environment-variable-passthrough) for details.
+When your skill is loaded, any declared `required_environment_variables` that are set are **automatically passed through** to `execute_code` and `terminal` sandboxes — including remote backends like Docker and Modal. Your skill's scripts can access `$TENOR_API_KEY` (or `os.environ["TENOR_API_KEY"]` in Python) without the user needing to configure anything extra. See [Environment Variable Passthrough](/docs/user-guide/security#environment-variable-passthrough) for details.
 :::
 
 Legacy `prerequisites.env_vars` remains supported as a backward-compatible alias.
 
+### Credential File Requirements (OAuth tokens, etc.)
+
+Skills that use OAuth or file-based credentials can declare files that need to be mounted into remote sandboxes. This is for credentials stored as **files** (not env vars) — typically OAuth token files produced by a setup script.
+
+```yaml
+required_credential_files:
+  - path: google_token.json
+    description: Google OAuth2 token (created by setup script)
+  - path: google_client_secret.json
+    description: Google OAuth2 client credentials
+```
+
+Each entry supports:
+- `path` (required) — file path relative to `~/.hermes/`
+- `description` (optional) — explains what the file is and how it's created
+
+When loaded, Hermes checks if these files exist. Missing files trigger `setup_needed`. Existing files are automatically:
+- **Mounted into Docker** containers as read-only bind mounts
+- **Synced into Modal** sandboxes (at creation + before each command, so mid-session OAuth works)
+- Available on **local** backend without any special handling
+
+:::tip When to use which
+Use `required_environment_variables` for simple API keys and tokens (strings stored in `~/.hermes/.env`). Use `required_credential_files` for OAuth token files, client secrets, service account JSON, certificates, or any credential that's a file on disk.
+:::
+
+See the `skills/productivity/google-workspace/SKILL.md` for a complete example using both.
+
 ## Skill Guidelines
 
 ### No External Dependencies

website/docs/reference/cli-commands.md

@@ -399,17 +399,22 @@ See [MCP Config Reference](./mcp-config-reference.md) and [Use MCP with Hermes](
 ## `hermes plugins`
 
 ```bash
-hermes plugins <subcommand>
+hermes plugins [subcommand]
 ```
 
-Manage Hermes Agent plugins.
+Manage Hermes Agent plugins. Running `hermes plugins` with no subcommand launches an interactive curses checklist to enable/disable installed plugins.
 
 | Subcommand | Description |
 |------------|-------------|
+| *(none)* | Interactive toggle UI — enable/disable plugins with arrow keys and space. |
 | `install <identifier> [--force]` | Install a plugin from a Git URL or `owner/repo`. |
 | `update <name>` | Pull latest changes for an installed plugin. |
 | `remove <name>` (aliases: `rm`, `uninstall`) | Remove an installed plugin. |
-| `list` (alias: `ls`) | List installed plugins. |
+| `enable <name>` | Enable a disabled plugin. |
+| `disable <name>` | Disable a plugin without removing it. |
+| `list` (alias: `ls`) | List installed plugins with enabled/disabled status. |
+
+Disabled plugins are stored in `config.yaml` under `plugins.disabled` and skipped during loading.
 
 See [Plugins](../user-guide/features/plugins.md) and [Build a Hermes Plugin](../guides/build-a-hermes-plugin.md).
 

website/docs/reference/environment-variables.md

@@ -105,7 +105,7 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
 |----------|-------------|
 | `TERMINAL_ENV` | Backend: `local`, `docker`, `ssh`, `singularity`, `modal`, `daytona` |
 | `TERMINAL_DOCKER_IMAGE` | Docker image (default: `python:3.11`) |
-| `TERMINAL_DOCKER_FORWARD_ENV` | JSON array of env var names to explicitly forward into Docker terminal sessions |
+| `TERMINAL_DOCKER_FORWARD_ENV` | JSON array of env var names to explicitly forward into Docker terminal sessions. Note: skill-declared `required_environment_variables` are forwarded automatically — you only need this for vars not declared by any skill. |
 | `TERMINAL_DOCKER_VOLUMES` | Additional Docker volume mounts (comma-separated `host:container` pairs) |
 | `TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE` | Advanced opt-in: mount the launch cwd into Docker `/workspace` (`true`/`false`, default: `false`) |
 | `TERMINAL_SINGULARITY_IMAGE` | Singularity image or `.sif` path |
@@ -200,6 +200,8 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
 | `MATTERMOST_TOKEN` | Bot token or personal access token for Mattermost |
 | `MATTERMOST_ALLOWED_USERS` | Comma-separated Mattermost user IDs allowed to message the bot |
 | `MATTERMOST_HOME_CHANNEL` | Channel ID for proactive message delivery (cron, notifications) |
+| `MATTERMOST_REQUIRE_MENTION` | Require `@mention` in channels (default: `true`). Set to `false` to respond to all messages. |
+| `MATTERMOST_FREE_RESPONSE_CHANNELS` | Comma-separated channel IDs where bot responds without `@mention` |
 | `MATTERMOST_REPLY_MODE` | Reply style: `thread` (threaded replies) or `off` (flat messages, default) |
 | `MATRIX_HOMESERVER` | Matrix homeserver URL (e.g. `https://matrix.org`) |
 | `MATRIX_ACCESS_TOKEN` | Matrix access token for bot authentication |

website/docs/reference/faq.md

@@ -489,6 +489,44 @@ If an MCP server crashes mid-request, Hermes will report a timeout. Check the se
 
 ---
 
+## Profiles
+
+### How do profiles differ from just setting HERMES_HOME?
+
+Profiles are a managed layer on top of `HERMES_HOME`. You *could* manually set `HERMES_HOME=/some/path` before every command, but profiles handle all the plumbing for you: creating the directory structure, generating shell aliases (`hermes-work`), tracking the active profile in `~/.hermes/active_profile`, and syncing skill updates across all profiles automatically. They also integrate with tab completion so you don't have to remember paths.
+
+### Can two profiles share the same bot token?
+
+No. Each messaging platform (Telegram, Discord, etc.) requires exclusive access to a bot token. If two profiles try to use the same token simultaneously, the second gateway will fail to connect. Create a separate bot per profile — for Telegram, talk to [@BotFather](https://t.me/BotFather) to make additional bots.
+
+### Do profiles share memory or sessions?
+
+No. Each profile has its own memory store, session database, and skills directory. They are completely isolated. If you want to start a new profile with existing memories and sessions, use `hermes profile create newname --clone-all` to copy everything from the current profile.
+
+### What happens when I run `hermes update`?
+
+`hermes update` pulls the latest code and reinstalls dependencies **once** (not per-profile). It then syncs updated skills to all profiles automatically. You only need to run `hermes update` once — it covers every profile on the machine.
+
+### Can I move a profile to a different machine?
+
+Yes. Export the profile to a portable archive and import it on the other machine:
+
+```bash
+# On the source machine
+hermes profile export work ./work-backup.tar.gz
+
+# Copy the file to the target machine, then:
+hermes profile import ./work-backup.tar.gz work
+```
+
+The imported profile will have all config, memories, sessions, and skills from the export. You may need to update paths or re-authenticate with providers if the new machine has a different setup.
+
+### How many profiles can I run?
+
+There is no hard limit. Each profile is just a directory under `~/.hermes/profiles/`. The practical limit depends on your disk space and how many concurrent gateways your system can handle (each gateway is a lightweight Python process). Running dozens of profiles is fine; each idle profile uses no resources.
+
+---
+
 ## Still Stuck?
 
 If your issue isn't covered here:

website/docs/reference/profile-commands.md

@@ -0,0 +1,280 @@
+---
+sidebar_position: 7
+---
+
+# Profile Commands Reference
+
+This page covers all commands related to [Hermes profiles](../user-guide/profiles.md). For general CLI commands, see [CLI Commands Reference](./cli-commands.md).
+
+## `hermes profile`
+
+```bash
+hermes profile <subcommand>
+```
+
+Top-level command for managing profiles. Running `hermes profile` without a subcommand shows help.
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List all profiles. |
+| `use` | Set the active (default) profile. |
+| `create` | Create a new profile. |
+| `delete` | Delete a profile. |
+| `show` | Show details about a profile. |
+| `alias` | Regenerate the shell alias for a profile. |
+| `rename` | Rename a profile. |
+| `export` | Export a profile to a tar.gz archive. |
+| `import` | Import a profile from a tar.gz archive. |
+
+## `hermes profile list`
+
+```bash
+hermes profile list
+```
+
+Lists all profiles. The currently active profile is marked with `*`.
+
+**Example:**
+
+```bash
+$ hermes profile list
+  default
+* work
+  dev
+  personal
+```
+
+No options.
+
+## `hermes profile use`
+
+```bash
+hermes profile use <name>
+```
+
+Sets `<name>` as the active profile. All subsequent `hermes` commands (without `-p`) will use this profile.
+
+| Argument | Description |
+|----------|-------------|
+| `<name>` | Profile name to activate. Use `default` to return to the base profile. |
+
+**Example:**
+
+```bash
+hermes profile use work
+hermes profile use default
+```
+
+## `hermes profile create`
+
+```bash
+hermes profile create <name> [options]
+```
+
+Creates a new profile.
+
+| Argument / Option | Description |
+|-------------------|-------------|
+| `<name>` | Name for the new profile. Must be a valid directory name (alphanumeric, hyphens, underscores). |
+| `--clone` | Copy `config.yaml`, `.env`, and `SOUL.md` from the current profile. |
+| `--clone-all` | Copy everything (config, memories, skills, sessions, state) from the current profile. |
+| `--from <profile>` | Clone from a specific profile instead of the current one. Used with `--clone` or `--clone-all`. |
+
+**Examples:**
+
+```bash
+# Blank profile — needs full setup
+hermes profile create mybot
+
+# Clone config only from current profile
+hermes profile create work --clone
+
+# Clone everything from current profile
+hermes profile create backup --clone-all
+
+# Clone config from a specific profile
+hermes profile create work2 --clone --from work
+```
+
+## `hermes profile delete`
+
+```bash
+hermes profile delete <name> [options]
+```
+
+Deletes a profile and removes its shell alias.
+
+| Argument / Option | Description |
+|-------------------|-------------|
+| `<name>` | Profile to delete. |
+| `--yes`, `-y` | Skip confirmation prompt. |
+
+**Example:**
+
+```bash
+hermes profile delete mybot
+hermes profile delete mybot --yes
+```
+
+:::warning
+This permanently deletes the profile's entire directory including all config, memories, sessions, and skills. Cannot delete the currently active profile.
+:::
+
+## `hermes profile show`
+
+```bash
+hermes profile show [name]
+```
+
+Displays details about a profile including its home directory, configured model, active platforms, and disk usage.
+
+| Argument | Description |
+|----------|-------------|
+| `[name]` | Profile to inspect. Defaults to the current active profile if omitted. |
+
+**Example:**
+
+```bash
+$ hermes profile show work
+Profile:    work
+Home:       ~/.hermes/profiles/work
+Model:      anthropic/claude-sonnet-4
+Platforms:  telegram, discord
+Skills:     12 installed
+Disk:       48 MB
+```
+
+## `hermes profile alias`
+
+```bash
+hermes profile alias <name>
+```
+
+Regenerates the shell alias script at `~/.local/bin/hermes-<name>`. Useful if the alias was accidentally deleted or if you need to update it after moving your Hermes installation.
+
+| Argument | Description |
+|----------|-------------|
+| `<name>` | Profile to create/update the alias for. |
+
+**Example:**
+
+```bash
+hermes profile alias work
+# Creates/updates ~/.local/bin/work
+```
+
+## `hermes profile rename`
+
+```bash
+hermes profile rename <old-name> <new-name>
+```
+
+Renames a profile. Updates the directory and shell alias.
+
+| Argument | Description |
+|----------|-------------|
+| `<old-name>` | Current profile name. |
+| `<new-name>` | New profile name. |
+
+**Example:**
+
+```bash
+hermes profile rename mybot assistant
+# ~/.hermes/profiles/mybot → ~/.hermes/profiles/assistant
+# ~/.local/bin/mybot → ~/.local/bin/assistant
+```
+
+## `hermes profile export`
+
+```bash
+hermes profile export <name> <output-path>
+```
+
+Exports a profile as a compressed tar.gz archive.
+
+| Argument | Description |
+|----------|-------------|
+| `<name>` | Profile to export. |
+| `<output-path>` | Path for the output archive (e.g., `./work-backup.tar.gz`). |
+
+**Example:**
+
+```bash
+hermes profile export work ./work-2026-03-29.tar.gz
+```
+
+## `hermes profile import`
+
+```bash
+hermes profile import <archive-path> [name]
+```
+
+Imports a profile from a tar.gz archive.
+
+| Argument | Description |
+|----------|-------------|
+| `<archive-path>` | Path to the tar.gz archive to import. |
+| `[name]` | Name for the imported profile. Defaults to the original profile name from the archive. |
+
+**Example:**
+
+```bash
+hermes profile import ./work-2026-03-29.tar.gz work-restored
+```
+
+## `hermes -p` / `hermes --profile`
+
+```bash
+hermes -p <name> <command> [options]
+hermes --profile <name> <command> [options]
+```
+
+Global flag to run any Hermes command under a specific profile without changing the sticky default. This overrides the active profile for the duration of the command.
+
+| Option | Description |
+|--------|-------------|
+| `-p <name>`, `--profile <name>` | Profile to use for this command. |
+
+**Examples:**
+
+```bash
+hermes -p work chat -q "Check the server status"
+hermes --profile dev gateway start
+hermes -p personal skills list
+hermes -p work config edit
+```
+
+## `hermes completion`
+
+```bash
+hermes completion <shell>
+```
+
+Generates shell completion scripts. Includes completions for profile names and profile subcommands.
+
+| Argument | Description |
+|----------|-------------|
+| `<shell>` | Shell to generate completions for: `bash`, `zsh`, or `fish`. |
+
+**Examples:**
+
+```bash
+# Install completions
+hermes completion bash >> ~/.bashrc
+hermes completion zsh >> ~/.zshrc
+hermes completion fish > ~/.config/fish/completions/hermes.fish
+
+# Reload shell
+source ~/.bashrc
+```
+
+After installation, tab completion works for:
+- `hermes profile <TAB>` — subcommands (list, use, create, etc.)
+- `hermes profile use <TAB>` — profile names
+- `hermes -p <TAB>` — profile names
+
+## See also
+
+- [Profiles User Guide](../user-guide/profiles.md)
+- [CLI Commands Reference](./cli-commands.md)
+- [FAQ — Profiles section](./faq.md#profiles)

website/docs/reference/skills-catalog.md

@@ -253,11 +253,18 @@ Skills for academic research, paper discovery, literature review, domain reconna
 | `arxiv` | Search and retrieve academic papers from arXiv using their free REST API. No API key needed. Search by keyword, author, category, or ID. Combine with web_extract or the ocr-and-documents skill to read full paper content. | `research/arxiv` |
 | `blogwatcher` | Monitor blogs and RSS/Atom feeds for updates using the blogwatcher CLI. Add blogs, scan for new articles, and track what you've read. | `research/blogwatcher` |
 | `domain-intel` | Passive domain reconnaissance using Python stdlib. Subdomain discovery, SSL certificate inspection, WHOIS lookups, DNS records, domain availability checks, and bulk multi-domain analysis. No API keys required. | `research/domain-intel` |
-| `duckduckgo-search` | Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Use the Python DDGS library or CLI to search, then web_extract for full content. | `research/duckduckgo-search` |
-| `parallel-cli` | Optional vendor skill for Parallel CLI — agent-native web search, extraction, deep research, enrichment, FindAll, and monitoring. | `research/parallel-cli` |
+| `duckduckgo-search` | Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Prefer the `ddgs` CLI when installed; use the Python DDGS library only after verifying that `ddgs` is available in the current runtime. | `research/duckduckgo-search` |
 | `ml-paper-writing` | Write publication-ready ML/AI papers for NeurIPS, ICML, ICLR, ACL, AAAI, COLM. Use when drafting papers from research repos, structuring arguments, verifying citations, or preparing camera-ready submissions. Includes LaTeX templates, reviewer guidelines, and citation verificatio… | `research/ml-paper-writing` |
 | `polymarket` | Query Polymarket prediction market data — search markets, get prices, orderbooks, and price history. Read-only via public REST APIs, no API key needed. | `research/polymarket` |
 
+## red-teaming
+
+Skills for LLM red-teaming, jailbreaking, and safety filter bypass research.
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `godmode` | Jailbreak API-served LLMs using G0DM0D3 techniques — Parseltongue input obfuscation (33 techniques), GODMODE CLASSIC system prompt templates, ULTRAPLINIAN multi-model racing, encoding escalation, and Hermes-native prefill/system prompt integration. Works on any model accessible via API including closed-source models. | `red-teaming/godmode` |
+
 ## smart-home
 
 Skills for controlling smart home devices — lights, switches, sensors, and home automation systems.
@@ -285,3 +292,84 @@ Skills for interacting with social platforms — posting, reading, monitoring, a
 | `systematic-debugging` | Use when encountering any bug, test failure, or unexpected behavior. 4-phase root cause investigation — NO fixes without understanding the problem first. | `software-development/systematic-debugging` |
 | `test-driven-development` | Use when implementing any feature or bugfix, before writing implementation code. Enforces RED-GREEN-REFACTOR cycle with test-first approach. | `software-development/test-driven-development` |
 | `writing-plans` | Use when you have a spec or requirements for a multi-step task. Creates comprehensive implementation plans with bite-sized tasks, exact file paths, and complete code examples. | `software-development/writing-plans` |
+
+---
+
+# Optional Skills
+
+Optional skills ship with the repository under `optional-skills/` but are **not active by default**. They cover heavier or niche use cases. Install them with:
+
+```bash
+hermes skills install official/<category>/<skill>
+```
+
+## autonomous-ai-agents
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `blackbox` | Delegate coding tasks to Blackbox AI CLI agent. Multi-model agent with built-in judge that runs tasks through multiple LLMs and picks the best result. Requires the blackbox CLI and a Blackbox AI API key. | `autonomous-ai-agents/blackbox` |
+
+## blockchain
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `base` | Query Base (Ethereum L2) blockchain data with USD pricing — wallet balances, token info, transaction details, gas analysis, contract inspection, whale detection, and live network stats. Uses Base RPC + CoinGecko. No API key required. | `blockchain/base` |
+| `solana` | Query Solana blockchain data with USD pricing — wallet balances, token portfolios with values, transaction details, NFTs, whale detection, and live network stats. Uses Solana RPC + CoinGecko. No API key required. | `blockchain/solana` |
+
+## creative
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `blender-mcp` | Control Blender directly from Hermes via socket connection to the blender-mcp addon. Create 3D objects, materials, animations, and run arbitrary Blender Python (bpy) code. | `creative/blender-mcp` |
+| `meme-generation` | Generate real meme images by picking a template and overlaying text with Pillow. Produces actual .png meme files. | `creative/meme-generation` |
+
+## devops
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `docker-management` | Manage Docker containers, images, volumes, networks, and Compose stacks — lifecycle ops, debugging, cleanup, and Dockerfile optimization. | `devops/docker-management` |
+
+## email
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `agentmail` | Give the agent its own dedicated email inbox via AgentMail. Send, receive, and manage email autonomously using agent-owned email addresses (e.g. hermes-agent@agentmail.to). | `email/agentmail` |
+
+## health
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `neuroskill-bci` | Connect to a running NeuroSkill instance and incorporate the user's real-time cognitive and emotional state (focus, relaxation, mood, cognitive load, drowsiness, heart rate, HRV, sleep staging, and 40+ derived EXG scores) into responses. Requires a BCI wearable (Muse 2/S or OpenBCI) and the NeuroSkill desktop app. | `health/neuroskill-bci` |
+
+## mcp
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `fastmcp` | Build, test, inspect, install, and deploy MCP servers with FastMCP in Python. Use when creating a new MCP server, wrapping an API or database as MCP tools, exposing resources or prompts, or preparing a FastMCP server for HTTP deployment. | `mcp/fastmcp` |
+
+## migration
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `openclaw-migration` | Migrate a user's OpenClaw customization footprint into Hermes Agent. Imports Hermes-compatible memories, SOUL.md, command allowlists, user skills, and selected workspace assets from ~/.openclaw, then reports what could not be migrated and why. | `migration/openclaw-migration` |
+
+## productivity
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `telephony` | Give Hermes phone capabilities — provision and persist a Twilio number, send and receive SMS/MMS, make direct calls, and place AI-driven outbound calls through Bland.ai or Vapi. | `productivity/telephony` |
+
+## research
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `bioinformatics` | Gateway to 400+ bioinformatics skills from bioSkills and ClawBio. Covers genomics, transcriptomics, single-cell, variant calling, pharmacogenomics, metagenomics, structural biology, and more. | `research/bioinformatics` |
+| `qmd` | Search personal knowledge bases, notes, docs, and meeting transcripts locally using qmd — a hybrid retrieval engine with BM25, vector search, and LLM reranking. Supports CLI and MCP integration. | `research/qmd` |
+
+## security
+
+| Skill | Description | Path |
+|-------|-------------|------|
+| `1password` | Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in, and reading/injecting secrets for commands. | `security/1password` |
+| `oss-forensics` | Supply chain investigation, evidence recovery, and forensic analysis for GitHub repositories. Covers deleted commit recovery, force-push detection, IOC extraction, multi-source evidence collection, and structured forensic reporting. | `security/oss-forensics` |
+| `sherlock` | OSINT username search across 400+ social networks. Hunt down social media accounts by username. | `security/sherlock` |

website/docs/user-guide/features/hooks.md

@@ -88,6 +88,26 @@ Handlers registered for `command:*` fire for any `command:` event (`command:mode
 
 ### Examples
 
+#### Boot Checklist (BOOT.md) — Built-in
+
+The gateway ships with a built-in `boot-md` hook that looks for `~/.hermes/BOOT.md` on every startup. If the file exists, the agent runs its instructions in a background session. No installation needed — just create the file.
+
+**Create `~/.hermes/BOOT.md`:**
+
+```markdown
+# Startup Checklist
+
+1. Check if any cron jobs failed overnight — run `hermes cron list`
+2. Send a message to Discord #general saying "Gateway restarted, all systems go"
+3. Check if /opt/app/deploy.log has any errors from the last 24 hours
+```
+
+The agent runs these instructions in a background thread so it doesn't block gateway startup. If nothing needs attention, the agent replies with `[SILENT]` and no message is delivered.
+
+:::tip
+No BOOT.md? The hook silently skips — zero overhead. Create the file whenever you need startup automation, delete it when you don't.
+:::
+
 #### Telegram Alert on Long Tasks
 
 Send yourself a message when the agent takes more than 10 steps:

website/docs/user-guide/features/plugins.md

@@ -87,9 +87,26 @@ The handler receives the argument string (everything after `/greet`) and returns
 
 ## Managing plugins
 
-```
-/plugins              # list loaded plugins in a session
-hermes config set display.show_cost true  # show cost in status bar
+```bash
+hermes plugins                  # interactive toggle UI — enable/disable with checkboxes
+hermes plugins list             # table view with enabled/disabled status
+hermes plugins install user/repo  # install from Git
+hermes plugins update my-plugin   # pull latest
+hermes plugins remove my-plugin   # uninstall
+hermes plugins enable my-plugin   # re-enable a disabled plugin
+hermes plugins disable my-plugin  # disable without removing
 ```
 
+Running `hermes plugins` with no arguments launches an interactive curses checklist (same UI as `hermes tools`) where you can toggle plugins on/off with arrow keys and space.
+
+Disabled plugins remain installed but are skipped during loading. The disabled list is stored in `config.yaml` under `plugins.disabled`:
+
+```yaml
+plugins:
+  disabled:
+    - my-noisy-plugin
+```
+
+In a running session, `/plugins` shows which plugins are currently loaded.
+
 See the **[full guide](/docs/guides/build-a-hermes-plugin)** for handler contracts, schema format, hook behavior, error handling, and common mistakes.

website/docs/user-guide/features/skills.md

@@ -8,7 +8,9 @@ description: "On-demand knowledge documents — progressive disclosure, agent-ma
 
 Skills are on-demand knowledge documents the agent can load when needed. They follow a **progressive disclosure** pattern to minimize token usage and are compatible with the [agentskills.io](https://agentskills.io/specification) open standard.
 
-All skills live in **`~/.hermes/skills/`** — a single directory that serves as the source of truth. On fresh install, bundled skills are copied from the repo. Hub-installed and agent-created skills also go here. The agent can modify or delete any skill.
+All skills live in **`~/.hermes/skills/`** — the primary directory and source of truth. On fresh install, bundled skills are copied from the repo. Hub-installed and agent-created skills also go here. The agent can modify or delete any skill.
+
+You can also point Hermes at **external skill directories** — additional folders scanned alongside the local one. See [External Skill Directories](#external-skill-directories) below.
 
 See also:
 
@@ -164,6 +166,47 @@ Once set, declared env vars are **automatically passed through** to `execute_cod
 └── .bundled_manifest              # Tracks seeded bundled skills
 ```
 
+## External Skill Directories
+
+If you maintain skills outside of Hermes — for example, a shared `~/.agents/skills/` directory used by multiple AI tools — you can tell Hermes to scan those directories too.
+
+Add `external_dirs` under the `skills` section in `~/.hermes/config.yaml`:
+
+```yaml
+skills:
+  external_dirs:
+    - ~/.agents/skills
+    - /home/shared/team-skills
+    - ${SKILLS_REPO}/skills
+```
+
+Paths support `~` expansion and `${VAR}` environment variable substitution.
+
+### How it works
+
+- **Read-only**: External dirs are only scanned for skill discovery. When the agent creates or edits a skill, it always writes to `~/.hermes/skills/`.
+- **Local precedence**: If the same skill name exists in both the local dir and an external dir, the local version wins.
+- **Full integration**: External skills appear in the system prompt index, `skills_list`, `skill_view`, and as `/skill-name` slash commands — no different from local skills.
+- **Non-existent paths are silently skipped**: If a configured directory doesn't exist, Hermes ignores it without errors. Useful for optional shared directories that may not be present on every machine.
+
+### Example
+
+```text
+~/.hermes/skills/               # Local (primary, read-write)
+├── devops/deploy-k8s/
+│   └── SKILL.md
+└── mlops/axolotl/
+    └── SKILL.md
+
+~/.agents/skills/               # External (read-only, shared)
+├── my-custom-workflow/
+│   └── SKILL.md
+└── team-conventions/
+    └── SKILL.md
+```
+
+All four skills appear in your skill index. If you create a new skill called `my-custom-workflow` locally, it shadows the external version.
+
 ## Agent-Managed Skills (skill_manage tool)
 
 The agent can create, update, and delete its own skills via the `skill_manage` tool. This is the agent's **procedural memory** — when it figures out a non-trivial workflow, it saves the approach as a skill for future reuse.

website/docs/user-guide/messaging/mattermost.md

@@ -149,6 +149,12 @@ MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c
 
 # Optional: reply mode (thread or off, default: off)
 # MATTERMOST_REPLY_MODE=thread
+
+# Optional: respond without @mention (default: true = require mention)
+# MATTERMOST_REQUIRE_MENTION=false
+
+# Optional: channels where bot responds without @mention (comma-separated channel IDs)
+# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2
 ```
 
 Optional behavior settings in `~/.hermes/config.yaml`:
@@ -206,6 +212,19 @@ Set it in your `~/.hermes/.env`:
 MATTERMOST_REPLY_MODE=thread
 ```
 
+## Mention Behavior
+
+By default, the bot only responds in channels when `@mentioned`. You can change this:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MATTERMOST_REQUIRE_MENTION` | `true` | Set to `false` to respond to all messages in channels (DMs always work). |
+| `MATTERMOST_FREE_RESPONSE_CHANNELS` | _(none)_ | Comma-separated channel IDs where the bot responds without `@mention`, even when require_mention is true. |
+
+To find a channel ID in Mattermost: open the channel, click the channel name header, and look for the ID in the URL or channel details.
+
+When the bot is `@mentioned`, the mention is automatically stripped from the message before processing.
+
 ## Troubleshooting
 
 ### Bot is not responding to messages

website/docs/user-guide/profiles.md

@@ -0,0 +1,202 @@
+---
+sidebar_position: 2
+---
+
+# Profiles: Running Multiple Agents
+
+Run multiple independent Hermes agents on the same machine — each with its own config, API keys, memory, sessions, skills, and gateway.
+
+## What are profiles?
+
+A profile is a fully isolated Hermes environment. Each profile gets its own directory containing its own `config.yaml`, `.env`, `SOUL.md`, memories, sessions, skills, cron jobs, and state database. Profiles let you run separate agents for different purposes — a coding assistant, a personal bot, a research agent — without any cross-contamination.
+
+When you create a profile, it automatically becomes its own command. Create a profile called `coder` and you immediately have `coder chat`, `coder setup`, `coder gateway start`, etc.
+
+## Quick start
+
+```bash
+hermes profile create coder       # creates profile + "coder" command alias
+coder setup                       # configure API keys and model
+coder chat                        # start chatting
+```
+
+That's it. `coder` is now a fully independent agent. It has its own config, its own memory, its own everything.
+
+## Creating a profile
+
+### Blank profile
+
+```bash
+hermes profile create mybot
+```
+
+Creates a fresh profile with bundled skills seeded. Run `mybot setup` to configure API keys, model, and gateway tokens.
+
+### Clone config only (`--clone`)
+
+```bash
+hermes profile create work --clone
+```
+
+Copies your current profile's `config.yaml`, `.env`, and `SOUL.md` into the new profile. Same API keys and model, but fresh sessions and memory. Edit `~/.hermes/profiles/work/.env` for different API keys, or `~/.hermes/profiles/work/SOUL.md` for a different personality.
+
+### Clone everything (`--clone-all`)
+
+```bash
+hermes profile create backup --clone-all
+```
+
+Copies **everything** — config, API keys, personality, all memories, full session history, skills, cron jobs, plugins. A complete snapshot. Useful for backups or forking an agent that already has context.
+
+### Clone from a specific profile
+
+```bash
+hermes profile create work --clone --clone-from coder
+```
+
+## Using profiles
+
+### Command aliases
+
+Every profile automatically gets a command alias at `~/.local/bin/<name>`:
+
+```bash
+coder chat                    # chat with the coder agent
+coder setup                   # configure coder's settings
+coder gateway start           # start coder's gateway
+coder doctor                  # check coder's health
+coder skills list             # list coder's skills
+coder config set model.model anthropic/claude-sonnet-4
+```
+
+The alias works with every hermes subcommand — it's just `hermes -p <name>` under the hood.
+
+### The `-p` flag
+
+You can also target a profile explicitly with any command:
+
+```bash
+hermes -p coder chat
+hermes --profile=coder doctor
+hermes chat -p coder -q "hello"    # works in any position
+```
+
+### Sticky default (`hermes profile use`)
+
+```bash
+hermes profile use coder
+hermes chat                   # now targets coder
+hermes tools                  # configures coder's tools
+hermes profile use default    # switch back
+```
+
+Sets a default so plain `hermes` commands target that profile. Like `kubectl config use-context`.
+
+### Knowing where you are
+
+The CLI always shows which profile is active:
+
+- **Prompt**: `coder ❯` instead of `❯`
+- **Banner**: Shows `Profile: coder` on startup
+- **`hermes profile`**: Shows current profile name, path, model, gateway status
+
+## Running gateways
+
+Each profile runs its own gateway as a separate process with its own bot token:
+
+```bash
+coder gateway start           # starts coder's gateway
+assistant gateway start       # starts assistant's gateway (separate process)
+```
+
+### Different bot tokens
+
+Each profile has its own `.env` file. Configure a different Telegram/Discord/Slack bot token in each:
+
+```bash
+# Edit coder's tokens
+nano ~/.hermes/profiles/coder/.env
+
+# Edit assistant's tokens
+nano ~/.hermes/profiles/assistant/.env
+```
+
+### Safety: token locks
+
+If two profiles accidentally use the same bot token, the second gateway will be blocked with a clear error naming the conflicting profile. Supported for Telegram, Discord, Slack, WhatsApp, and Signal.
+
+### Persistent services
+
+```bash
+coder gateway install         # creates hermes-gateway-coder systemd/launchd service
+assistant gateway install     # creates hermes-gateway-assistant service
+```
+
+Each profile gets its own service name. They run independently.
+
+## Configuring profiles
+
+Each profile has its own:
+
+- **`config.yaml`** — model, provider, toolsets, all settings
+- **`.env`** — API keys, bot tokens
+- **`SOUL.md`** — personality and instructions
+
+```bash
+coder config set model.model anthropic/claude-sonnet-4
+echo "You are a focused coding assistant." > ~/.hermes/profiles/coder/SOUL.md
+```
+
+## Updating
+
+`hermes update` pulls code once (shared) and syncs new bundled skills to **all** profiles automatically:
+
+```bash
+hermes update
+# → Code updated (12 commits)
+# → Skills synced: default (up to date), coder (+2 new), assistant (+2 new)
+```
+
+User-modified skills are never overwritten.
+
+## Managing profiles
+
+```bash
+hermes profile list           # show all profiles with status
+hermes profile show coder     # detailed info for one profile
+hermes profile rename coder dev-bot   # rename (updates alias + service)
+hermes profile export coder   # export to coder.tar.gz
+hermes profile import coder.tar.gz   # import from archive
+```
+
+## Deleting a profile
+
+```bash
+hermes profile delete coder
+```
+
+This stops the gateway, removes the systemd/launchd service, removes the command alias, and deletes all profile data. You'll be asked to type the profile name to confirm.
+
+Use `--yes` to skip confirmation: `hermes profile delete coder --yes`
+
+:::note
+You cannot delete the default profile (`~/.hermes`). To remove everything, use `hermes uninstall`.
+:::
+
+## Tab completion
+
+```bash
+# Bash
+eval "$(hermes completion bash)"
+
+# Zsh
+eval "$(hermes completion zsh)"
+```
+
+Add the line to your `~/.bashrc` or `~/.zshrc` for persistent completion. Completes profile names after `-p`, profile subcommands, and top-level commands.
+
+## How it works
+
+Profiles use the `HERMES_HOME` environment variable. When you run `coder chat`, the wrapper script sets `HERMES_HOME=~/.hermes/profiles/coder` before launching hermes. Since 119+ files in the codebase resolve paths via `get_hermes_home()`, everything automatically scopes to the profile's directory — config, sessions, memory, skills, state database, gateway PID, logs, and cron jobs.
+
+The default profile is simply `~/.hermes` itself. No migration needed — existing installs work identically.