feat: pluggable MemoryProvider interface for persistent memory integrations

[shuruheel]

Summary

Introduces a MemoryProvider abstract interface that standardizes how persistent memory systems hook into the agent lifecycle. This makes it straightforward for third-party memory providers (MindGraph, Mem0, Zep, custom RAG, etc.) to integrate without modifying core agent code.

Interface

The interface has 4 lifecycle hooks:

• on_session_start() — new conversation
• get_session_context() — system prompt enrichment (once, cached)
• get_turn_context() — per-turn semantic retrieval (ephemeral injection)
• on_session_end() — cleanup + transcript ingestion

These hooks mirror the patterns already established by Honcho's integration — the same injection points, the same non-fatal error handling, the same cache-stable ephemeral injection approach.

What's included

New files:

• memory_provider.py — MemoryProvider ABC, MemoryProviderRegistry, create_default_registry(), inject_provider_context()
• providers/mindgraph_provider.py — MindGraph semantic graph memory provider
• providers/honcho_provider.py — Documented stub showing how Honcho maps to this interface (Phase 2 migration path)

Modified:

• run_agent.py — Generic registry hooks added alongside existing Honcho code
• gateway/run.py — Lazy registry with _get_memory_providers() helper + session cleanup hooks
• AGENTS.md — Developer guide: "Adding a Memory Provider"

Tests: 35 new tests (unit + integration), zero regressions

Design decisions

• Tools separate from memory hooks — A memory system registers tools via tools/registry.py (for explicit actions) AND a provider (for invisible lifecycle hooks). Both independently toggleable.
• Per-agent instance — Each AIAgent gets its own registry. No shared state across concurrent gateway conversations.
• Registration order = priority — First registered provider's context appears first.
• Non-fatal — Every provider call is wrapped in try/except. Failing providers never break conversations.
• Honcho untouched — All existing Honcho integration code is unchanged. The HonchoProvider stub documents the Phase 2 migration path.

How to add a provider

from memory_provider import MemoryProvider

class YourProvider(MemoryProvider):
    @property
    def name(self) -> str:
        return "yourprovider"

    def is_available(self) -> bool:
        return bool(os.getenv("YOUR_API_KEY"))

    def get_session_context(self) -> str | None:
        return "## Goals\n- Ship the thing"

    def get_turn_context(self, user_message: str) -> str | None:
        return semantic_search(user_message)

Then register in create_default_registry() in memory_provider.py.

[shuruheel]

Update: Refactored as a native v0.5.0 plugin

After reviewing the v0.5.0 release, the plugin lifecycle hooks (on_session_start, pre_llm_call, post_llm_call, on_session_end) now cover exactly the use case this PR addressed. The hooks support return values for context injection, which is the key capability that get_turn_context() and get_session_context() provided.

Rather than maintaining a parallel MemoryProvider ABC, I've refactored the MindGraph integration as a standard Hermes plugin that uses the native hooks:

• on_session_start → opens MindGraph session, pre-fetches context (goals, decisions, policies, weak claims)
• pre_llm_call → returns {"context": "..."} with session context on first turn + score-gated semantic retrieval every turn
• on_session_end → closes the MindGraph session

Published as pip-installable: hermes-mindgraph-plugin — auto-discovered via the hermes_agent.plugins entry point.

Source: https://github.com/shuruheel/hermes-mindgraph-plugin

This approach has a few advantages over the original PR:

1. Zero core changes — no new ABC, no registry, no modifications to run_agent.py or gateway/run.py
2. Uses the plugin architecture exactly as designed
3. Any memory provider can follow the same pattern (Mem0, Zep, etc.) without core changes
4. Independently versioned and distributed

Happy to close this PR in favor of the plugin approach. The plugin also serves as a reference implementation for anyone building memory integrations on the new hook system.