Skip to content

Add native RetainDB memory integration#2732

Closed
Alinxus wants to merge 2 commits into
NousResearch:mainfrom
Alinxus:feat/retaindb-native-memory
Closed

Add native RetainDB memory integration#2732
Alinxus wants to merge 2 commits into
NousResearch:mainfrom
Alinxus:feat/retaindb-native-memory

Conversation

@Alinxus

@Alinxus Alinxus commented Mar 24, 2026

Copy link
Copy Markdown

Summary

This adds a native RetainDB integration to Hermes as an optional cross-session memory layer.

Hermes keeps its local memory files and session storage, while RetainDB adds:

  • native CLI setup and config
  • cross-session recall
  • durable async write-behind session ingestion
  • explicit RetainDB memory tools
  • gateway/session lifecycle integration

What changed

  • Added hermes retaindb commands:
    • setup
    • status
    • test
    • mode
    • tokens
    • identity
  • Added native RetainDB integration modules:
    • client
    • identity resolution
    • recall overlay building
    • session manager
    • durable write queue
  • Added RetainDB tool handlers:
    • retaindb_profile
    • retaindb_search
    • retaindb_context
    • retaindb_remember
    • retaindb_forget
  • Wired RetainDB into:
    • run_agent.py
    • gateway session lifecycle
    • tool dispatch
    • doctor/config/toolset surfaces
  • Added docs for RetainDB memory
  • Added regression tests for gateway lifecycle and tool behavior

Design

  • Native Hermes integration first, not MCP
  • Hermes local memory and state.db remain intact
  • RetainDB acts as the deeper cross-session memory layer
  • Default mode is hybrid
  • Recall is injected as an ephemeral per-turn overlay
  • Session ingestion uses durable async write-behind
  • Failures fall back to normal Hermes behavior

Verification

Ran:

  • py -3 -m compileall retaindb_integration tools\\retaindb_tools.py hermes_cli\\main.py hermes_cli\\config.py
  • hermes retaindb status
  • hermes retaindb identity

teknium1 added a commit that referenced this pull request Mar 29, 2026
@teknium1
feat(memory): add pluggable memory provider interface
1452c81 
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.
@teknium1 teknium1 mentioned this pull request Mar 29, 2026
Closed
teknium1 added a commit that referenced this pull request Mar 30, 2026
@teknium1
feat(plugins): add OpenViking, RetainDB, and Cognitive memory providers
48364a0 
Adapts three more memory backend PRs to the MemoryProvider interface:

OpenViking (PR #3369 by Mibayy):
- 3 tools: viking_search, viking_read, viking_browse
- Read-only, self-hosted server, no sync/prefetch
- URI-based content with progressive disclosure levels

RetainDB (PR #2732 by Alinxus):
- 5 tools: retaindb_profile, retaindb_search, retaindb_context,
  retaindb_remember, retaindb_forget
- Cloud API with prefetch, sync, and memory bridging
- Durable write-behind queue pattern

Cognitive Memory (PR #727 by 0xbyt4):
- 1 tool with 4 actions: recall, store, forget, status
- Local SQLite with vector embeddings (litellm)
- Auto-classification, importance decay, dedup, forgetting

All gated on credentials/deps via is_available():
- OpenViking: OPENVIKING_ENDPOINT + server health check
- RetainDB: RETAINDB_API_KEY
- Cognitive: litellm importable (uses its env vars for embedding API)
This was referenced Mar 31, 2026
Closed
Merged
@teknium1

teknium1 commented Apr 27, 2026

Copy link
Copy Markdown
Contributor

Thanks for this contribution @Alinxus! The RetainDB integration has been implemented on main — this is an automated hermes-sweeper review.

Your PR was salvaged and merged as part of the pluggable memory provider system:

  • plugins/memory/retaindb/ — full RetainDBMemoryProvider implementation including the durable SQLite write-behind queue, semantic search, dialectic synthesis, agent self-model, and shared file store tools
  • Merged in: 48364a011 (feat(plugins): add OpenViking, RetainDB, and Cognitive memory providers, Mar 29 2026)
  • Your follow-up fixes also landed: 6df486027 (API routes, write queue, dialectic, agent model, file tools) and ea8ec2702 (optional project config)
  • Shipped in: v2026.4.3

Note: the integration was adapted to the shared MemoryProvider plugin interface rather than a top-level retaindb_integration/ module with bespoke CLI commands — this keeps it consistent with how Honcho, Mem0, and other memory backends are integrated.

@teknium1 teknium1 closed this Apr 27, 2026
angelburgosrosado pushed a commit to angelburgosrosado/hermes-agent that referenced this pull request Apr 28, 2026
@teknium1
feat(memory): add pluggable memory provider interface
6b6b469 
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.
angelburgosrosado pushed a commit to angelburgosrosado/hermes-agent that referenced this pull request Apr 28, 2026
@teknium1
feat(plugins): add OpenViking, RetainDB, and Cognitive memory providers
60d46e1 
Adapts three more memory backend PRs to the MemoryProvider interface:

OpenViking (PR NousResearch#3369 by Mibayy):
- 3 tools: viking_search, viking_read, viking_browse
- Read-only, self-hosted server, no sync/prefetch
- URI-based content with progressive disclosure levels

RetainDB (PR NousResearch#2732 by Alinxus):
- 5 tools: retaindb_profile, retaindb_search, retaindb_context,
  retaindb_remember, retaindb_forget
- Cloud API with prefetch, sync, and memory bridging
- Durable write-behind queue pattern

Cognitive Memory (PR NousResearch#727 by 0xbyt4):
- 1 tool with 4 actions: recall, store, forget, status
- Local SQLite with vector embeddings (litellm)
- Auto-classification, importance decay, dedup, forgetting

All gated on credentials/deps via is_available():
- OpenViking: OPENVIKING_ENDPOINT + server health check
- RetainDB: RETAINDB_API_KEY
- Cognitive: litellm importable (uses its env vars for embedding API)
CumulusService pushed a commit to Cumulus-Service-GmbH/hermes-agent that referenced this pull request May 30, 2026
@teknium1
feat(memory): add pluggable memory provider interface
5f5cae2 
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.
CumulusService pushed a commit to Cumulus-Service-GmbH/hermes-agent that referenced this pull request May 30, 2026
@teknium1
feat(plugins): add OpenViking, RetainDB, and Cognitive memory providers
27159e3 
Adapts three more memory backend PRs to the MemoryProvider interface:

OpenViking (PR NousResearch#3369 by Mibayy):
- 3 tools: viking_search, viking_read, viking_browse
- Read-only, self-hosted server, no sync/prefetch
- URI-based content with progressive disclosure levels

RetainDB (PR NousResearch#2732 by Alinxus):
- 5 tools: retaindb_profile, retaindb_search, retaindb_context,
  retaindb_remember, retaindb_forget
- Cloud API with prefetch, sync, and memory bridging
- Durable write-behind queue pattern

Cognitive Memory (PR NousResearch#727 by 0xbyt4):
- 1 tool with 4 actions: recall, store, forget, status
- Local SQLite with vector embeddings (litellm)
- Auto-classification, importance decay, dedup, forgetting

All gated on credentials/deps via is_available():
- OpenViking: OPENVIKING_ENDPOINT + server health check
- RetainDB: RETAINDB_API_KEY
- Cognitive: litellm importable (uses its env vars for embedding API)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Alinxus @teknium1