feat: add Mem0 memory integration CLI commands and client support by kartik-mem0 · Pull Request #2933 · NousResearch/hermes-agent

kartik-mem0 · 2026-03-25T08:29:36Z

What does this PR do?

Adds Mem0 Platform integration to Hermes, enabling persistent cross-session memory. The agent extracts facts from conversations, stores them via Mem0's API, and recalls relevant context in future
sessions through semantic search and system prompt injection.

All search and retrieval uses the Mem0 v2 filter API with proper entity scoping. Memories stored with a run_id (from session strategies) are correctly retrieved using OR filters that combine bare
user_id matching with a run_id: "*" wildcard branch — without this, session-scoped memories are invisible to search. The rerank and keyword_search config settings are respected across all search
paths (manager, prefetch, tools, CLI). Mem0 is a fully independent plugin with its own turn context injection (_inject_mem0_turn_context), separate from Honcho.

Related Issue

Fixes #2942

Type of Change

🐛 Bug fix (non-breaking change that fixes an issue)
✨ New feature (non-breaking change that adds functionality)
🔒 Security fix
📝 Documentation update
✅ Tests (adding or improving test coverage)
♻️ Refactor (no behavior change)
🎯 New skill (bundled or hub)

Changes Made

mem0_integration/client.py — Config dataclass (Mem0ClientConfig) with resolution from $HERMES_HOME/mem0.json → ~/.hermes/mem0.json → env vars. Singleton MemoryClient factory.
mem0_integration/manager.py — Mem0MemoryManager with add(), search(), get_profile(), store_fact(), and background prefetch() for system prompt injection.
mem0_integration/cli.py — hermes mem0 {setup|status|search|memories|clear} subcommands for interactive setup, connection health check, and memory management from the terminal.
tools/mem0_tools.py — Four agent tools: mem0_search, mem0_context, mem0_profile, mem0_conclude. Visible only when Mem0 is enabled.
run_agent.py — Mem0 lifecycle hooks: config loading, prefetch on session start, memory ingestion on conversation end, tool registration.
hermes_cli/main.py — Registered mem0 subcommand in the CLI argument parser.
hermes_cli/doctor.py — Added Mem0 connection health check to hermes doctor.
pyproject.toml — Added mem0ai as optional dependency.
tests/mem0_integration/test_client.py — 13 tests for config resolution, env fallback, singleton behavior.
tests/mem0_integration/test_cli.py — 5 tests for CLI status/search/memories commands.
tests/mem0_integration/test_manager.py — 14 tests for add, search, get_profile, store_fact, prefetch, shutdown.
tests/tools/test_mem0_tools.py — 15 tests for tool availability, search, context, profile, conclude handlers.

How to Test

Install dependency: uv pip install mem0ai
Run setup wizard: hermes mem0 setup — enter API key from app.mem0.ai
Verify connection: hermes mem0 status
Start a conversation with hermes, mention some personal facts, then end the session
Start a new session — the agent should recall facts from the previous session via prefetch
Search from CLI: hermes mem0 search "programming languages"
List all stored memories: hermes mem0 memories
Run unit tests: pytest tests/mem0_integration/ tests/tools/test_mem0_tools.py -v (47 tests, all passing)

Checklist

Code

I've read the Contributing Guide
My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
I searched for existing PRs to make sure this isn't a duplicate
My PR contains only changes related to this fix/feature (no unrelated commits)
I've run pytest tests/ -q and all tests pass
I've added tests for my changes (47 tests across 4 test files)
I've tested on my platform: macOS 15 (Apple Silicon)

Documentation & Housekeeping

I've updated relevant documentation (README, docs/, docstrings) — or N/A
I've updated cli-config.yaml.example if I added/changed config keys — or N/A
I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
I've considered cross-platform impact (Windows, macOS) per the compatibility guide —
or N/A
I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Adds comprehensive user-facing docs for the Mem0 integration, following the same structure as the Honcho Memory docs. Covers setup, configuration, tools, CLI commands, troubleshooting, warnings, and a Mem0 vs Honcho comparison table. Adds mem0 to the sidebar under Integrations. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…earch logic

…n context injection

Introduces MemoryProvider ABC, MemoryManager orchestrator, and BuiltinMemoryProvider for the existing MEMORY.md/USER.md system. Key design decisions: - Built-in memory is ALWAYS active, never disabled by external providers - Multiple providers can be active simultaneously - Prefetch results from all providers are merged per-turn - Sync fans out to all providers after each turn - Each provider can expose its own tools Three registration paths: 1. Built-in (BuiltinMemoryProvider) — always first, not removable 2. First-party (Honcho stays as-is for now, migration in follow-up) 3. Plugin — ctx.register_memory_provider() in plugin system Files: - agent/memory_provider.py — ABC with core + optional lifecycle hooks - agent/memory_manager.py — orchestrator, single integration point - agent/builtin_memory_provider.py — wraps existing MemoryStore - hermes_cli/plugins.py — register_memory_provider() + accessor - run_agent.py — MemoryManager wired alongside existing Honcho code - tests/agent/test_memory_provider.py — 37 tests This establishes the interface for all pending memory backend PRs (#1811 Hindsight, #2732 RetainDB, #2933 Mem0, #3499 Byterover, #3369 OpenViking, #2351 Holographic, #727 Cognitive) to implement as plugins rather than one-off integrations.

Adapts PR #1811 (Hindsight by benfrank241) and PR #2933 (Mem0 by kartik-mem0) to the MemoryProvider interface as drop-in plugins. Hindsight plugin (plugins/hindsight-memory/): - 3 tools: hindsight_retain, hindsight_recall, hindsight_reflect - Cloud (API key) or local (embedded PostgreSQL) modes - Background prefetch with thread isolation for aiohttp - Auto-sync turns to knowledge graph Mem0 plugin (plugins/mem0-memory/): - 4 tools: mem0_profile, mem0_search, mem0_context, mem0_conclude - Server-side LLM fact extraction and deduplication - Semantic search with optional reranking - Verbatim fact storage via conclude (infer=False) Both require API keys (HINDSIGHT_API_KEY / MEM0_API_KEY) and the respective SDK packages (hindsight-client / mem0ai). is_available() gates on credentials so installing the plugin without a key is safe.

teknium1 · 2026-04-06T05:29:25Z

Closing as superseded — your Mem0 integration has been reimplemented as a native MemoryProvider plugin at plugins/memory/mem0/. The plugin's docstring credits your original work: "Original PR #2933 by kartik-mem0, adapted to MemoryProvider ABC."

Your contribution established the foundation for Mem0 support in Hermes. Thank you for the work on this!

Introduces MemoryProvider ABC, MemoryManager orchestrator, and BuiltinMemoryProvider for the existing MEMORY.md/USER.md system. Key design decisions: - Built-in memory is ALWAYS active, never disabled by external providers - Multiple providers can be active simultaneously - Prefetch results from all providers are merged per-turn - Sync fans out to all providers after each turn - Each provider can expose its own tools Three registration paths: 1. Built-in (BuiltinMemoryProvider) — always first, not removable 2. First-party (Honcho stays as-is for now, migration in follow-up) 3. Plugin — ctx.register_memory_provider() in plugin system Files: - agent/memory_provider.py — ABC with core + optional lifecycle hooks - agent/memory_manager.py — orchestrator, single integration point - agent/builtin_memory_provider.py — wraps existing MemoryStore - hermes_cli/plugins.py — register_memory_provider() + accessor - run_agent.py — MemoryManager wired alongside existing Honcho code - tests/agent/test_memory_provider.py — 37 tests This establishes the interface for all pending memory backend PRs (NousResearch#1811 Hindsight, NousResearch#2732 RetainDB, NousResearch#2933 Mem0, NousResearch#3499 Byterover, NousResearch#3369 OpenViking, NousResearch#2351 Holographic, NousResearch#727 Cognitive) to implement as plugins rather than one-off integrations.

Adapts PR NousResearch#1811 (Hindsight by benfrank241) and PR NousResearch#2933 (Mem0 by kartik-mem0) to the MemoryProvider interface as drop-in plugins. Hindsight plugin (plugins/hindsight-memory/): - 3 tools: hindsight_retain, hindsight_recall, hindsight_reflect - Cloud (API key) or local (embedded PostgreSQL) modes - Background prefetch with thread isolation for aiohttp - Auto-sync turns to knowledge graph Mem0 plugin (plugins/mem0-memory/): - 4 tools: mem0_profile, mem0_search, mem0_context, mem0_conclude - Server-side LLM fact extraction and deduplication - Semantic search with optional reranking - Verbatim fact storage via conclude (infer=False) Both require API keys (HINDSIGHT_API_KEY / MEM0_API_KEY) and the respective SDK packages (hindsight-client / mem0ai). is_available() gates on credentials so installing the plugin without a key is safe.

Introduces MemoryProvider ABC, MemoryManager orchestrator, and BuiltinMemoryProvider for the existing MEMORY.md/USER.md system. Key design decisions: - Built-in memory is ALWAYS active, never disabled by external providers - Multiple providers can be active simultaneously - Prefetch results from all providers are merged per-turn - Sync fans out to all providers after each turn - Each provider can expose its own tools Three registration paths: 1. Built-in (BuiltinMemoryProvider) — always first, not removable 2. First-party (Honcho stays as-is for now, migration in follow-up) 3. Plugin — ctx.register_memory_provider() in plugin system Files: - agent/memory_provider.py — ABC with core + optional lifecycle hooks - agent/memory_manager.py — orchestrator, single integration point - agent/builtin_memory_provider.py — wraps existing MemoryStore - hermes_cli/plugins.py — register_memory_provider() + accessor - run_agent.py — MemoryManager wired alongside existing Honcho code - tests/agent/test_memory_provider.py — 37 tests This establishes the interface for all pending memory backend PRs (NousResearch#1811 Hindsight, NousResearch#2732 RetainDB, NousResearch#2933 Mem0, NousResearch#3499 Byterover, NousResearch#3369 OpenViking, NousResearch#2351 Holographic, NousResearch#727 Cognitive) to implement as plugins rather than one-off integrations.

Adapts PR NousResearch#1811 (Hindsight by benfrank241) and PR NousResearch#2933 (Mem0 by kartik-mem0) to the MemoryProvider interface as drop-in plugins. Hindsight plugin (plugins/hindsight-memory/): - 3 tools: hindsight_retain, hindsight_recall, hindsight_reflect - Cloud (API key) or local (embedded PostgreSQL) modes - Background prefetch with thread isolation for aiohttp - Auto-sync turns to knowledge graph Mem0 plugin (plugins/mem0-memory/): - 4 tools: mem0_profile, mem0_search, mem0_context, mem0_conclude - Server-side LLM fact extraction and deduplication - Semantic search with optional reranking - Verbatim fact storage via conclude (infer=False) Both require API keys (HINDSIGHT_API_KEY / MEM0_API_KEY) and the respective SDK packages (hindsight-client / mem0ai). is_available() gates on credentials so installing the plugin without a key is safe.

feat: add Mem0 memory integration CLI commands and client support

c839b49

kartik-mem0 marked this pull request as draft March 25, 2026 08:30

merge: integrate main into feat/mem0-integration

97fd9cc

kartik-mem0 marked this pull request as ready for review March 25, 2026 08:35

kartik-mem0 marked this pull request as draft March 25, 2026 08:35

kartik-mem0 and others added 4 commits March 25, 2026 14:05

chore: add mem0 optional dependency to pyproject.toml

aa63014

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor: update Mem0 integration to use v2 API filters and improve s…

54f83bc

…earch logic

refactor: expose v2 filter builder, update rerank logic, add Mem0 tur…

b394d8b

…n context injection

kartik-mem0 marked this pull request as ready for review March 25, 2026 10:36

teknium1 mentioned this pull request Mar 29, 2026

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

Closed

This was referenced Mar 31, 2026

feat(memory): pluggable memory provider interface with profile isolation #4154

Closed

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

Merged

teknium1 closed this Apr 6, 2026

teknium1 mentioned this pull request Apr 27, 2026

[Feature]: Mem0 Platform integration — persistent cross-session memory #2942

Closed

1 task

kartik-mem0 deleted the feat/mem0-integration branch April 27, 2026 05:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add Mem0 memory integration CLI commands and client support#2933

feat: add Mem0 memory integration CLI commands and client support#2933
kartik-mem0 wants to merge 6 commits into
NousResearch:mainfrom
kartik-mem0:feat/mem0-integration

kartik-mem0 commented Mar 25, 2026 •

edited

Loading

Uh oh!

teknium1 commented Apr 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

kartik-mem0 commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Related Issue

Type of Change

Changes Made

How to Test

Checklist

Code

Documentation & Housekeeping

Screenshots / Logs

Uh oh!

teknium1 commented Apr 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kartik-mem0 commented Mar 25, 2026 •

edited

Loading