feat(memory): pluggable memory provider interface with profile isolation by teknium1 · Pull Request #4154 · NousResearch/hermes-agent

teknium1 · 2026-03-31T03:18:03Z

Summary

Introduces a pluggable memory provider system for Hermes Agent. External memory backends (Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover) integrate as self-contained plugins under plugins/memory/, with standardized lifecycle hooks, tool registration, config management, and CLI setup. Only one external provider is active at a time alongside the always-on built-in memory (MEMORY.md / USER.md).

This PR fully replaces the previous Honcho-specific integration that was scattered across run_agent.py, gateway/run.py, cli.py, model_tools.py, and toolsets.py. All Honcho code now lives inside plugins/memory/honcho/.

Supersedes PR #3825.

Architecture

Core (3 new files in `agent/`)

File	Purpose
`agent/memory_provider.py`	`MemoryProvider` ABC — lifecycle hooks, tool schemas, config schema, `save_config()`
`agent/memory_manager.py`	`MemoryManager` — orchestrates builtin + one external provider, enforces single-provider limit
`agent/builtin_memory_provider.py`	Wraps existing MEMORY.md/USER.md as the always-on provider

Plugin Directory (`plugins/memory/<name>/`)

Each provider is fully self-contained:

plugins/memory/<name>/
├── __init__.py      # MemoryProvider implementation + register() entry point
├── plugin.yaml      # Metadata, pip_dependencies, hooks
├── README.md        # Setup instructions, config reference, tools table
└── (optional)       # Supporting modules (client.py, session.py, store.py, etc.)

Discovery (`plugins/memory/init.py`)

Scans plugins/memory/ at runtime. Not part of the general plugin system — dedicated scanner with its own load_memory_provider(name) that handles submodule registration for plugins with multiple files.

Integration Points in `run_agent.py` (all additive)

Hook	Location	What it does
Init	`__init__`	Creates MemoryManager, loads provider matching `memory.provider` config
Tool injection	After init	Appends provider tool schemas to `self.tools` and `self.valid_tool_names`
System prompt	`_build_system_prompt`	Adds provider's `system_prompt_block()`
Tool routing	`_invoke_tool`	Routes provider tool calls through `memory_manager.handle_tool_call()`
Memory bridge	After memory tool	Calls `on_memory_write()` to notify external provider of built-in memory writes
Pre-compress	`_compress_context`	Calls `on_pre_compress()` before context compression
Prefetch	API message building	Injects `prefetch_all()` result into current-turn user message
Turn sync	After response	`sync_all()` + `queue_prefetch_all()`
Session end	End of `run_conversation`	`on_session_end()` + `shutdown_all()`

MemoryProvider Interface

Required Methods

class MemoryProvider(ABC):
    name: str                              # Provider identifier
    is_available() -> bool                 # Can activate? NO network calls.
    initialize(session_id, **kwargs)       # kwargs includes hermes_home
    get_tool_schemas() -> list             # OpenAI function-calling format
    handle_tool_call(name, args) -> str    # JSON result string
    get_config_schema() -> list            # Fields for hermes memory setup
    save_config(values, hermes_home)       # Write native config

Optional Lifecycle Hooks

    system_prompt_block() -> str           # Static provider info for system prompt
    prefetch(query) -> str                 # Recall context for current turn
    queue_prefetch(query)                  # Pre-warm for next turn (background)
    sync_turn(user, assistant)             # Persist completed turn (MUST be non-blocking)
    on_session_end(messages)               # Final extraction/flush
    on_pre_compress(messages)              # Save insights before compression
    on_memory_write(action, target, content)  # Mirror built-in memory writes
    shutdown()                             # Clean exit

Threading Contract

sync_turn() MUST be non-blocking. All providers that do network I/O wrap their sync in daemon threads with join-before-new-thread guards.

Single Provider Enforcement

MemoryManager.add_provider() accepts unlimited "builtin" providers but only ONE non-builtin. A second attempt is rejected with a warning pointing to memory.provider in config.yaml.

Profile Isolation

initialize() receives hermes_home kwarg. All storage paths use this, not hardcoded ~/.hermes. Cloud providers auto-scope namespaces per profile.

Shipped Providers (7)

Provider	Tools	Storage	Dependencies	Unique Feature
Honcho	4	Cloud	`honcho-ai`	Dialectic user modeling, peer cards
OpenViking	5	Self-hosted	`httpx`	Filesystem hierarchy, tiered loading (L0/L1/L2), auto extraction
Mem0	3	Cloud	`mem0ai`	Server-side LLM extraction, circuit breaker
Hindsight	3	Cloud/Local	`hindsight-client`	Knowledge graph, reflect (cross-memory synthesis)
Holographic	2	Local SQLite	None	FTS5 + trust scoring + HRR algebra
RetainDB	5	Cloud	`requests`	Hybrid search (Vector + BM25 + Reranking)
ByteRover	3	Local/Cloud	`brv` CLI	Pre-compression extraction, knowledge tree

Dropped: Cognitive Memory (#727) — core math broken (24x decay rate, broken recency, importance-limited search).

CLI

hermes memory setup     # Interactive provider picker + config wizard + dep install
hermes memory status    # Show active provider, config, availability
hermes memory off       # Disable external provider (built-in only)
hermes honcho           # Migration redirect → hermes memory setup

Setup Wizard Flow

Discovers all providers from plugins/memory/
Curses picker with setup hints (requires API key / local / no setup)
Reads pip_dependencies from plugin.yaml, installs missing packages
Walks through get_config_schema() fields (secrets → .env, choices → curses picker)
Calls provider.save_config() to write native config
Writes memory.provider: <name> to config.yaml
Shows external deps guidance (e.g. ByteRover CLI install command)

Config Architecture

# config.yaml — only the activation key
memory:
  provider: openviking

Secrets go to .env. Non-secret config goes to each provider's native location via save_config():

Provider	Config file	Secrets in .env
Honcho	`$HERMES_HOME/honcho.json`	`HONCHO_API_KEY`
Mem0	`$HERMES_HOME/mem0.json`	`MEM0_API_KEY`
Hindsight	`$HERMES_HOME/hindsight/config.json`	`HINDSIGHT_API_KEY`
Holographic	`config.yaml` under `plugins.hermes-memory-store`	—
OpenViking	— (env vars only)	`OPENVIKING_ENDPOINT`, `OPENVIKING_API_KEY`
RetainDB	— (env vars only)	`RETAINDB_API_KEY`
ByteRover	— (env vars only)	`BRV_API_KEY`

Honcho Migration

For existing users

Auto-migration on first session: if HonchoClientConfig.from_global_config() returns enabled=True with credentials, memory.provider: honcho is automatically set in config.yaml. No user action needed, no data loss.

What was removed from the core

File	Lines removed	What
`run_agent.py`	~500	Init, 8 methods, system prompt block, tool dispatch, prefetch, sync
`cli.py`	~60	Session re-mapping, flush, shutdown, display, param
`gateway/run.py`	~100	Shared managers, shutdown methods, params
`model_tools.py`	~10	Import, params from handle_function_call
`toolsets.py`	~10	Honcho toolset definition, core tools list
`hermes_cli/main.py`	~80	Honcho argparse subparsers
`tools/honcho_tools.py`	279	Entire file deleted
`honcho_integration/cli.py`	794	Entire file deleted
`honcho_integration/`	Package removed	client.py + session.py moved to plugin

What was kept (inside the plugin)

plugins/memory/honcho/
├── __init__.py   # MemoryProvider adapter (350 lines)
├── client.py     # Config loading, SDK client creation (445 lines)
├── session.py    # Session management, queries, flush (991 lines)
├── plugin.yaml
└── README.md

Documentation

New pages

website/docs/user-guide/features/memory-providers.md — all 7 providers, setup, comparison, profile isolation
website/docs/developer-guide/memory-provider-plugin.md — how to build a new plugin

Updated pages

user-guide/features/memory.md — links to new Memory Providers page
user-guide/features/honcho.md — migration redirect
developer-guide/architecture.md — updated directory structure
developer-guide/gateway-internals.md — updated memory routing docs
sidebars.ts — added both new pages

Per-plugin docs

Each provider has a README.md with requirements, setup (wizard + manual), config reference, and tools table.

Test Plan

48 memory-specific tests (unit + E2E + discovery)
Full suite: 7186 passed, 4 pre-existing failures unrelated to this PR
E2E verified: discovery → dep check → config → activation → tool injection → tool routing → lifecycle hooks → prefetch → sync → session end

Credits

Based on work from PR #3825 and the original contributor PRs:

feat: add Hindsight memory integration (local memory option) #1811 Hindsight by @benfrank241
feat(plugin): hermes-memory-store with holographic retrieval #2351 Holographic by @dusterbloom
Add native RetainDB memory integration #2732 RetainDB by @Alinxus
feat: add Mem0 memory integration CLI commands and client support #2933 Mem0 by @kartik-mem0
feat(memory): add OpenViking context database integration #3369 OpenViking by @Mibayy
feat(memory): Integrate Byterover as a long-term memory system #3499 ByteRover by @hieuntg81

…olation Introduces a pluggable MemoryProvider ABC so external memory backends can integrate with Hermes without modifying core files. Each backend becomes a plugin implementing a standard interface, orchestrated by MemoryManager. Key architecture: - agent/memory_provider.py — ABC with core + optional lifecycle hooks - agent/memory_manager.py — single integration point in the agent loop - agent/builtin_memory_provider.py — wraps existing MEMORY.md/USER.md Profile isolation fixes applied to all 6 shipped plugins: - Cognitive Memory: use get_hermes_home() instead of raw env var - Hindsight Memory: check $HERMES_HOME/hindsight/config.json first, fall back to legacy ~/.hindsight/ for backward compat - Hermes Memory Store: replace hardcoded ~/.hermes paths with get_hermes_home() for config loading and DB path defaults - Mem0 Memory: use get_hermes_home() instead of raw env var - RetainDB Memory: auto-derive profile-scoped project name from hermes_home path (hermes-<profile>), explicit env var overrides - OpenViking Memory: read-only, no local state, isolation via .env MemoryManager.initialize_all() now injects hermes_home into kwargs so every provider can resolve profile-scoped storage without importing get_hermes_home() themselves. Plugin system: adds register_memory_provider() to PluginContext and get_plugin_memory_providers() accessor. Based on PR #3825. 46 tests (37 unit + 5 E2E + 4 plugin registration).

…rovider Remove cognitive-memory plugin (#727) — core mechanics are broken: decay runs 24x too fast (hourly not daily), prefetch uses row ID as timestamp, search limited by importance not similarity. Rewrite openviking-memory plugin from a read-only search wrapper into a full bidirectional memory provider using the complete OpenViking session lifecycle API: - sync_turn: records user/assistant messages to OpenViking session (threaded, non-blocking) - on_session_end: commits session to trigger automatic memory extraction into 6 categories (profile, preferences, entities, events, cases, patterns) - prefetch: background semantic search via find() endpoint - on_memory_write: mirrors built-in memory writes to the session - is_available: checks env var only, no network calls (ABC compliance) Tools expanded from 3 to 5: - viking_search: semantic search with mode/scope/limit - viking_read: tiered content (abstract ~100tok / overview ~2k / full) - viking_browse: filesystem-style navigation (list/tree/stat) - viking_remember: explicit memory storage via session - viking_add_resource: ingest URLs/docs into knowledge base Uses direct HTTP via httpx (no openviking SDK dependency needed). Response truncation on viking_read to prevent context flooding.

…ircuit breaker - Remove redundant mem0_context tool (identical to mem0_search with rerank=true, top_k=5 — wastes a tool slot and confuses the model) - Thread sync_turn so it's non-blocking — Mem0's server-side LLM extraction can take 5-10s, was stalling the agent after every turn - Add threading.Lock around _get_client() for thread-safe lazy init (prefetch and sync threads could race on first client creation) - Add circuit breaker: after 5 consecutive API failures, pause calls for 120s instead of hammering a down server every turn. Auto-resets after cooldown. Logs a warning when tripped. - Track success/failure in prefetch, sync_turn, and all tool calls - Wait for previous sync to finish before starting a new one (prevents unbounded thread accumulation on rapid turns) - Clean up shutdown to join both prefetch and sync threads

MemoryManager now rejects a second non-builtin provider with a warning. Built-in memory (MEMORY.md/USER.md) is always accepted. Only ONE external plugin provider is allowed at a time. This prevents tool schema bloat (some providers add 3-5 tools each) and conflicting memory backends. The warning message directs users to configure memory.provider in config.yaml to select which provider to activate. Updated all 47 tests to use builtin + one external pattern instead of multiple externals. Added test_second_external_rejected to verify the enforcement.

github-actions · 2026-03-31T03:18:20Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: exec() or eval() usage

Dynamic code execution can hide malicious behavior, especially when combined with base64 or network fetches.

Matches (first 20):

4568:+  multi-strategy retrieval (semantic + BM25 + graph + temporal), and

⚠️ WARNING: Outbound network calls (POST/PUT)

Outbound POST/PUT requests in new code could be data exfiltration. Verify the destination URLs are legitimate.

Matches (first 10):

5004:+        resp = self._httpx.post(

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/memory_setup.py
hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

Implements the ByteRover integration (from PR #3499 by hieuntg81) as a MemoryProvider plugin instead of direct run_agent.py modifications. ByteRover provides persistent memory via the brv CLI — a hierarchical knowledge tree with tiered retrieval (fuzzy text then LLM-driven search). Local-first with optional cloud sync. Plugin capabilities: - prefetch: background brv query for relevant context - sync_turn: curate conversation turns (threaded, non-blocking) - on_memory_write: mirror built-in memory writes to brv - on_pre_compress: extract insights before context compression Tools (3): - brv_query: search the knowledge tree - brv_curate: store facts/decisions/patterns - brv_status: check CLI version and context tree state Profile isolation: working directory at $HERMES_HOME/byterover/ (scoped per profile). Binary resolution cached with thread-safe double-checked locking. All write operations threaded to avoid blocking the agent (curate can take 120s with LLM processing).

github-actions · 2026-03-31T03:41:05Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: exec() or eval() usage

Dynamic code execution can hide malicious behavior, especially when combined with base64 or network fetches.

Matches (first 20):

2440:+a hierarchical context tree with tiered retrieval (fuzzy text → LLM-driven
4982:+  multi-strategy retrieval (semantic + BM25 + graph + temporal), and

⚠️ WARNING: Outbound network calls (POST/PUT)

Outbound POST/PUT requests in new code could be data exfiltration. Verify the destination URLs are legitimate.

Matches (first 10):

5418:+        resp = self._httpx.post(

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/memory_setup.py
hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

… key Plugin fixes: - Hindsight: thread sync_turn (was blocking up to 30s via _run_in_thread) - RetainDB: thread sync_turn (was blocking on HTTP POST) - Both: shutdown now joins sync threads alongside prefetch threads Holographic retrieval fixes: - reason(): removed dead intersection_key computation (bundled but never used in scoring). Now reuses pre-computed entity_residuals directly, moved role_content encoding outside the inner loop. - contradict(): added _MAX_CONTRADICT_FACTS=500 scaling guard. Above 500 facts, only checks the most recently updated ones to avoid O(n^2) explosion (~125K comparisons at 500 is acceptable). Config: - Added memory.provider key to DEFAULT_CONFIG ("" = builtin only). No version bump needed (deep_merge handles new keys automatically).

github-actions · 2026-03-31T04:16:00Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: exec() or eval() usage

Dynamic code execution can hide malicious behavior, especially when combined with base64 or network fetches.

Matches (first 20):

2452:+a hierarchical context tree with tiered retrieval (fuzzy text → LLM-driven
5000:+  multi-strategy retrieval (semantic + BM25 + graph + temporal), and

⚠️ WARNING: Outbound network calls (POST/PUT)

Outbound POST/PUT requests in new code could be data exfiltration. Verify the destination URLs are legitimate.

Matches (first 10):

5436:+        resp = self._httpx.post(

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/memory_setup.py
hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

Creates plugins/honcho-memory/ as a thin adapter over the existing honcho_integration/ package. All 4 Honcho tools (profile, search, context, conclude) move from the normal tool registry to the MemoryProvider interface. The plugin delegates all work to HonchoSessionManager — no Honcho logic is reimplemented. It uses the existing config chain: $HERMES_HOME/honcho.json -> ~/.honcho/config.json -> env vars. Lifecycle hooks: - initialize: creates HonchoSessionManager via existing client factory - prefetch: background dialectic query - sync_turn: records messages + flushes to API (threaded) - on_memory_write: mirrors user profile writes as conclusions - on_session_end: flushes all pending messages This is a prerequisite for the MemoryManager wiring in run_agent.py. Once wired, Honcho goes through the same provider interface as all other memory plugins, and the scattered Honcho code in run_agent.py can be consolidated into the single MemoryManager integration point.

github-actions · 2026-03-31T04:37:04Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: exec() or eval() usage

Dynamic code execution can hide malicious behavior, especially when combined with base64 or network fetches.

Matches (first 20):

2452:+a hierarchical context tree with tiered retrieval (fuzzy text → LLM-driven
5000:+  multi-strategy retrieval (semantic + BM25 + graph + temporal), and

⚠️ WARNING: Outbound network calls (POST/PUT)

Outbound POST/PUT requests in new code could be data exfiltration. Verify the destination URLs are legitimate.

Matches (first 10):

5802:+        resp = self._httpx.post(

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/memory_setup.py
hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

Adds 8 integration points for the external memory provider plugin, all purely additive (zero existing code modified): 1. Init (~L1130): Create MemoryManager, find matching plugin provider from memory.provider config, initialize with session context 2. Tool injection (~L1160): Append provider tool schemas to self.tools and self.valid_tool_names after memory_manager init 3. System prompt (~L2705): Add external provider's system_prompt_block alongside existing MEMORY.md/USER.md blocks 4. Tool routing (~L5362): Route provider tool calls through memory_manager.handle_tool_call() before the catchall handler 5. Memory write bridge (~L5353): Notify external provider via on_memory_write() when the built-in memory tool writes 6. Pre-compress (~L5233): Call on_pre_compress() before context compression discards messages 7. Prefetch (~L6421): Inject provider prefetch results into the current-turn user message (same pattern as Honcho turn context) 8. Turn sync + session end (~L8161, ~L8172): sync_all() after each completed turn, queue_prefetch_all() for next turn, on_session_end() + shutdown_all() at conversation end All hooks are wrapped in try/except — a failing provider never breaks the agent. The existing memory system, Honcho integration, and all other code paths are completely untouched. Full suite: 7222 passed, 4 pre-existing failures.

github-actions · 2026-03-31T05:16:21Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: exec() or eval() usage

Dynamic code execution can hide malicious behavior, especially when combined with base64 or network fetches.

Matches (first 20):

2452:+a hierarchical context tree with tiered retrieval (fuzzy text → LLM-driven
5000:+  multi-strategy retrieval (semantic + BM25 + graph + temporal), and

⚠️ WARNING: Outbound network calls (POST/PUT)

Outbound POST/PUT requests in new code could be data exfiltration. Verify the destination URLs are legitimate.

Matches (first 10):

5802:+        resp = self._httpx.post(

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/memory_setup.py
hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

Extracts all Honcho-specific code from run_agent.py, model_tools.py, toolsets.py, and gateway/run.py. Honcho is now exclusively available as a memory provider plugin (plugins/honcho-memory/). Removed from run_agent.py (-457 lines): - Honcho init block (session manager creation, activation, config) - 8 Honcho methods: _honcho_should_activate, _strip_honcho_tools, _activate_honcho, _register_honcho_exit_hook, _queue_honcho_prefetch, _honcho_prefetch, _honcho_save_user_observation, _honcho_sync - _inject_honcho_turn_context module-level function - Honcho system prompt block (tool descriptions, CLI commands) - Honcho context injection in api_messages building - Honcho params from __init__ (honcho_session_key, honcho_manager, honcho_config) - HONCHO_TOOL_NAMES constant - All honcho-specific tool dispatch forwarding Removed from other files: - model_tools.py: honcho_tools import, honcho params from handle_function_call - toolsets.py: honcho toolset definition, honcho tools from core tools list - gateway/run.py: honcho params from AIAgent constructor calls Removed tests (-339 lines): - 9 Honcho-specific test methods from test_run_agent.py - TestHonchoAtexitFlush class from test_exit_cleanup_interrupt.py Restored two regex constants (_SURROGATE_RE, _BUDGET_WARNING_RE) that were accidentally removed during the honcho function extraction. The honcho_integration/ package is kept intact — the plugin delegates to it. tools/honcho_tools.py registry entries are now dead code (import commented out in model_tools.py) but the file is preserved for reference. Full suite: 7207 passed, 4 pre-existing failures. Zero regressions.

github-actions · 2026-03-31T06:04:34Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: exec() or eval() usage

Dynamic code execution can hide malicious behavior, especially when combined with base64 or network fetches.

Matches (first 20):

2509:+a hierarchical context tree with tiered retrieval (fuzzy text → LLM-driven
5057:+  multi-strategy retrieval (semantic + BM25 + graph + temporal), and

⚠️ WARNING: Outbound network calls (POST/PUT)

Outbound POST/PUT requests in new code could be data exfiltration. Verify the destination URLs are legitimate.

Matches (first 10):

5859:+        resp = self._httpx.post(

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/memory_setup.py
hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

…ion notice Plugin restructure: - Move all memory plugins from plugins/<name>-memory/ to plugins/memory/<name>/ (byterover, hindsight, holographic, honcho, mem0, openviking, retaindb) - New plugins/memory/__init__.py discovery module that scans the directory directly, loading providers by name without the general plugin system - run_agent.py uses load_memory_provider() instead of get_plugin_memory_providers() CLI wiring: - hermes memory setup — interactive curses picker + config wizard - hermes memory status — show active provider, config, availability - hermes memory off — disable external provider (built-in only) - hermes honcho — now shows migration notice pointing to hermes memory setup Gateway cleanup: - Remove _get_or_create_gateway_honcho (already removed in prev commit) - Remove _shutdown_gateway_honcho and _shutdown_all_gateway_honcho methods - Remove all calls to shutdown methods (4 call sites) - Remove _honcho_managers/_honcho_configs dict references Dead code removal: - Delete tools/honcho_tools.py (279 lines, import was already commented out) - Delete tests/gateway/test_honcho_lifecycle.py (131 lines, tested removed methods) - Remove if False placeholder from run_agent.py Migration: - Honcho migration notice on startup: detects existing honcho.json or ~/.honcho/config.json, prints guidance to run hermes memory setup. Only fires when memory.provider is not set and not in quiet mode. Full suite: 7203 passed, 4 pre-existing failures. Zero regressions.

github-actions · 2026-03-31T06:47:21Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: exec() or eval() usage

Dynamic code execution can hide malicious behavior, especially when combined with base64 or network fetches.

Matches (first 20):

2894:+a hierarchical context tree with tiered retrieval (fuzzy text → LLM-driven
3657:+  multi-strategy retrieval (semantic + BM25 + graph + temporal), and

⚠️ WARNING: Outbound network calls (POST/PUT)

Outbound POST/PUT requests in new code could be data exfiltration. Verify the destination URLs are legitimate.

Matches (first 10):

6244:+        resp = self._httpx.post(

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/memory_setup.py
hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

Config architecture: - Add save_config(values, hermes_home) to MemoryProvider ABC - Honcho: writes to $HERMES_HOME/honcho.json (SDK native) - Mem0: writes to $HERMES_HOME/mem0.json - Hindsight: writes to $HERMES_HOME/hindsight/config.json - Holographic: writes to config.yaml under plugins.hermes-memory-store - OpenViking/RetainDB/ByteRover: env-var only (default no-op) Setup wizard (hermes memory setup): - Now calls provider.save_config() for non-secret config - Secrets still go to .env via env vars - Only memory.provider activation key goes to config.yaml Documentation: - README.md for each of the 7 providers in plugins/memory/<name>/ - Requirements, setup (wizard + manual), config reference, tools table - Consistent format across all providers The contract for new memory plugins: - get_config_schema() declares all fields (REQUIRED) - save_config() writes native config (REQUIRED if not env-var-only) - Secrets use env_var field in schema, written to .env by wizard - README.md in the plugin directory

github-actions · 2026-03-31T07:07:48Z

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: exec() or eval() usage

Dynamic code execution can hide malicious behavior, especially when combined with base64 or network fetches.

Matches (first 20):

2919:+Persistent memory via the `brv` CLI — hierarchical knowledge tree with tiered retrieval (fuzzy text → LLM-driven search).
2967:+a hierarchical context tree with tiered retrieval (fuzzy text → LLM-driven
3790:+  multi-strategy retrieval (semantic + BM25 + graph + temporal), and

⚠️ WARNING: Outbound network calls (POST/PUT)

Outbound POST/PUT requests in new code could be data exfiltration. Verify the destination URLs are legitimate.

Matches (first 10):

6595:+        resp = self._httpx.post(

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/memory_setup.py
hermes_cli/setup.py

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

New pages: - user-guide/features/memory-providers.md — comprehensive guide covering all 7 shipped providers (Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover). Each with setup, config, tools, cost, and unique features. Includes comparison table and profile isolation notes. - developer-guide/memory-provider-plugin.md — how to build a new memory provider plugin. Covers ABC, required methods, config schema, save_config, threading contract, profile isolation, testing. Updated pages: - user-guide/features/memory.md — replaced Honcho section with link to new Memory Providers page - user-guide/features/honcho.md — replaced with migration redirect to the new Memory Providers page - sidebars.ts — added both new pages to navigation

When honcho.json or ~/.honcho/config.json exists but memory.provider is not set, automatically set memory.provider: honcho in config.yaml and activate the plugin. The plugin reads the same config files, so all data and credentials are preserved. Zero user action needed. Persists the migration to config.yaml so it only fires once. Prints a one-line confirmation in non-quiet mode.

Check HonchoClientConfig.enabled AND (api_key OR base_url) before auto-migrating — not just file existence. Prevents false activation for users who disabled Honcho, stopped using it (config lingers), or have ~/.honcho/ from a different tool.

Reads pip_dependencies from plugin.yaml, checks which are missing, installs them via pip before config walkthrough. Also shows install guidance for external_dependencies (e.g. brv CLI for ByteRover). Updated all 7 plugin.yaml files with pip_dependencies: - honcho: honcho-ai - mem0: mem0ai - openviking: httpx - hindsight: hindsight-client - holographic: (none) - retaindb: requests - byterover: (external_dependencies for brv CLI)

cli.py: removed Honcho session re-mapping block (would crash importing deleted tools/honcho_tools.py), Honcho flush on compress, Honcho session display on startup, Honcho shutdown on exit, honcho_session_key AIAgent param. gateway/run.py: removed honcho_session_key params from helper methods, sync_honcho param, _honcho.shutdown() block. tests: fixed test_cron_session_with_honcho_key_skipped (was passing removed honcho_key param to _flush_memories_for_session).

Without this, plugins/memory/ wouldn't be included in non-editable installs. Hermes always runs from the repo checkout so this is belt- and-suspenders, but prevents breakage if the install method changes.

The heuristic dep.replace('-', '_') fails for packages where the pip name differs from the import name: honcho-ai→honcho, mem0ai→mem0, hindsight-client→hindsight_client. Added explicit mapping table so hermes memory setup doesn't try to reinstall already-installed packages.

- hermes_cli/plugins.py: removed register_memory_provider(), _memory_providers list, get_plugin_memory_providers() — memory providers now use plugins/memory/ discovery, not the general plugin system - hermes_cli/main.py: stripped 74 lines of dead honcho argparse subparsers (setup, status, sessions, map, peer, mode, tokens, identity, migrate) — kept only the migration redirect - agent/memory_provider.py: updated docstring to reflect new registration path - tests: replaced TestPluginMemoryProviderRegistration with TestPluginMemoryDiscovery that tests the actual plugins/memory/ discovery system. Added 3 new tests (discover, load, nonexistent).

cli.py (794 lines) was the old 'hermes honcho' command handler — nobody calls it since cmd_honcho was replaced with a migration redirect. Deleted tests that imported from removed code: - tests/honcho_integration/test_cli.py (tested _resolve_api_key) - tests/honcho_integration/test_config_isolation.py (tested CLI config paths) - tests/tools/test_honcho_tools.py (tested the deleted tools/honcho_tools.py) Remaining honcho_integration/ files (actively used by the plugin): - client.py (445 lines) — config loading, SDK client creation - session.py (991 lines) — session management, queries, flush

Moves client.py (445 lines) and session.py (991 lines) from the top-level honcho_integration/ package into plugins/memory/honcho/. No Honcho code remains in the main codebase. - plugins/memory/honcho/client.py — config loading, SDK client creation - plugins/memory/honcho/session.py — session management, queries, flush - Updated all imports: run_agent.py (auto-migration), hermes_cli/doctor.py, plugin __init__.py, session.py cross-import, all tests - Removed honcho_integration/ package and pyproject.toml entry - Renamed tests/honcho_integration/ → tests/honcho_plugin/

- architecture.md: replaced honcho_integration/ with plugins/memory/ - gateway-internals.md: replaced Honcho-specific session routing and flush lifecycle docs with generic memory provider interface docs

nicoloboschi

hey @teknium1 thanks for this work (finally!)

we maintain the official Hindsight integration for Hermes here .

ideally we will kill it in favour of this native integration

A few gaps in the current implementation compared to our SDK best practices:
I can do a follow up PR if you prefer!

Retain is missing key fields:

No timestamp
No document_id — re-retaining the same conversation creates duplicates instead of upserting
No tags — prevents scoped recall and multi-user isolation

Recall/reflect missing parameters:

No tags/tags_match filtering on recall — if tags are set on retain, recall needs them too
No max_tokens control on recall — agents should control how much context window they allocate
Reflect uses the same budget as recall, but they have different defaults for a reason (low vs
mid)

Client lifecycle issue:

_make_client() is called fresh per tool call / sync / prefetch — this is expensive especially
for HindsightEmbedded which manages a daemon process. Should create once in initialize() and
reuse.

Unused hooks:

on_session_end is declared in plugin.yaml but not implemented — good place to flush or retain a
session summary
on_pre_compress could retain messages about to be discarded so they're not lost from memory
on_memory_write could bridge built-in MEMORY.md writes to Hindsight

Self-hosted support:

Cloud client is created with Hindsight(api_key=...) but no base_url — self-hosted users with
HINDSIGHT_API_URL can't connect

Also the correct cloud url is ui.hindsight.vectorize.io

samherring99 · 2026-04-01T00:00:14Z

Some questions:

Is there ever a case where we'd want more than one memory provider active at a time? Why would we limit it to one active one at a time.
I keep seeing 'profile isolation' here but I don't under stand where that's actually happening.
Do we have any CI tests around these kind of things, and if not, can we add them?

zebster-cmd · 2026-04-01T23:48:59Z

Some questions:

1. Is there ever a case where we'd want more than one memory provider active at a time? Why would we limit it to one active one at a time.

2. I keep seeing 'profile isolation' here but I don't under stand where that's actually happening.

3. Do we have any CI tests around these kind of things, and if not, can we add them?

Would actually love to have multiple memory providers active at the same time. Honcho for conversational memory, openviking for rulebooks, context and protocol, and KGs for entity fact checking

kartik-mem0 · 2026-04-02T09:13:03Z

Hey @teknium1 , great work on the pluggable memory provider architecture the lifecycle hooks, circuit breaker, and threading patterns are well done.

I'm from the Mem0 team (I authored the original Mem0 integration in PR #2933). I reviewed the Mem0 plugin rewrite and found some regressions from the original implementation that would cause runtime issues.

Bug: Response format handling

MemoryClient.get_all() and MemoryClient.search() return {"results": [...]}, not a bare list. The plugin iterates directly over the response dict, so mem0_profile, mem0_search, and prefetch will silently return empty/incorrect results.

The original PR #2933 handled this correctly:

PR feat: add Mem0 memory integration CLI commands and client support #2933 (correct)
result = self._client.search(query, **kwargs)
if isinstance(result, list):
return result
return result.get("results", result.get("memories", []))
PR feat(memory): pluggable memory provider interface with profile isolation #4154 (broken)
results = client.search(query=query, user_id=self._user_id, ...)
lines = [r.get("memory", "") for r in results if r.get("memory")]

Regressions from the original implementation

Several features from PR #2933 were stripped in the rewrite:

Feature	PR #2933	PR #4154
v2 filter API	Uses version="v2" with proper OR filters for run_id wildcard scoping	Passes user_id= directly — misses session-scoped memories
keyword_search	Passed to every search call	In config defaults but never used
custom_instructions	Passed to client.add() for extraction control	Missing entirely
run_id / session scoping	Supported in add() for session-scoped memories	session_id received in initialize() but never used
mem0_context tool	Deep retrieval with forced reranking	Dropped
Config richness	memory_mode, recall_mode, session_strategy, keyword_search, custom_instructions	Only api_key, user_id, agent_id, rerank
Response format safety	isinstance(result, list) check + .get("results", ...) fallback	Direct iteration over response dict

Missing Mem0 features worth adding

delete(memory_id) / update(memory_id, text) — Without these, users can't correct or remove wrong memories
Pagination — get_all() supports page and page_size for large memory sets

Happy to help fix these or review a follow-up. The original PR #2933 can serve as reference for the correct API usage patterns.

…ion (salvage #4154) # Conflicts: # gateway/run.py # hermes_cli/main.py # honcho_integration/cli.py # tests/honcho_integration/test_cli.py # website/sidebars.ts

teknium1 · 2026-04-02T16:53:03Z

Salvaged onto current main as #4623. Resolved 5 conflicts (including integration with the just-merged #4616 Honcho profile scoping), fixed stale mock paths.

…ion (salvage NousResearch#4154) # Conflicts: # gateway/run.py # hermes_cli/main.py # honcho_integration/cli.py # tests/honcho_integration/test_cli.py # website/sidebars.ts

teknium1 added 4 commits March 30, 2026 17:09

teknium1 added 11 commits March 31, 2026 00:18

fix: include plugins/ in pyproject.toml package list

479b02e

Without this, plugins/memory/ wouldn't be included in non-editable installs. Hermes always runs from the repo checkout so this is belt- and-suspenders, but prevents breakage if the install method changes.

docs: update architecture + gateway-internals for memory provider system

2b22c57

- architecture.md: replaced honcho_integration/ with plugins/memory/ - gateway-internals.md: replaced Honcho-specific session routing and flush lifecycle docs with generic memory provider interface docs

nicoloboschi reviewed Mar 31, 2026

View reviewed changes

erosika mentioned this pull request Mar 31, 2026

feat(honcho): restore full integration parity in memory provider plugin #4355

Merged

benfrank241 mentioned this pull request Apr 1, 2026

docs(hermes): update integration page for memory provider architecture vectorize-io/hindsight#835

Closed

This was referenced Apr 2, 2026

feat(memory): pluggable memory provider interface with profile isolation, review fixes, and honcho CLI restoration #4623

Merged

feat(memory): add pluggable memory provider interface #3825

Closed

teknium1 closed this Apr 2, 2026

Conversation

teknium1 commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Architecture

Core (3 new files in agent/)

Plugin Directory (plugins/memory/<name>/)

Discovery (plugins/memory/__init__.py)

Integration Points in run_agent.py (all additive)

MemoryProvider Interface

Required Methods

Optional Lifecycle Hooks

Threading Contract

Single Provider Enforcement

Profile Isolation

Shipped Providers (7)

CLI

Setup Wizard Flow

Config Architecture

Honcho Migration

For existing users

What was removed from the core

What was kept (inside the plugin)

Documentation

New pages

Updated pages

Per-plugin docs

Test Plan

Credits

Uh oh!

github-actions Bot commented Mar 31, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: exec() or eval() usage

⚠️ WARNING: Outbound network calls (POST/PUT)

⚠️ WARNING: Install hook files modified

Uh oh!

github-actions Bot commented Mar 31, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: exec() or eval() usage

⚠️ WARNING: Outbound network calls (POST/PUT)

⚠️ WARNING: Install hook files modified

Uh oh!

github-actions Bot commented Mar 31, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: exec() or eval() usage

⚠️ WARNING: Outbound network calls (POST/PUT)

⚠️ WARNING: Install hook files modified

Uh oh!

github-actions Bot commented Mar 31, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: exec() or eval() usage

⚠️ WARNING: Outbound network calls (POST/PUT)

⚠️ WARNING: Install hook files modified

Uh oh!

github-actions Bot commented Mar 31, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: exec() or eval() usage

⚠️ WARNING: Outbound network calls (POST/PUT)

⚠️ WARNING: Install hook files modified

Uh oh!

github-actions Bot commented Mar 31, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: exec() or eval() usage

⚠️ WARNING: Outbound network calls (POST/PUT)

⚠️ WARNING: Install hook files modified

Uh oh!

github-actions Bot commented Mar 31, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: exec() or eval() usage

⚠️ WARNING: Outbound network calls (POST/PUT)

⚠️ WARNING: Install hook files modified

Uh oh!

github-actions Bot commented Mar 31, 2026

⚠️ Supply Chain Risk Detected

⚠️ WARNING: exec() or eval() usage

⚠️ WARNING: Outbound network calls (POST/PUT)

⚠️ WARNING: Install hook files modified

Uh oh!

nicoloboschi left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

teknium1 commented Mar 31, 2026 •

edited

Loading

Core (3 new files in `agent/`)

Plugin Directory (`plugins/memory/<name>/`)

Discovery (`plugins/memory/init.py`)

Integration Points in `run_agent.py` (all additive)

nicoloboschi left a comment •

edited

Loading