feat(memory): add Contexto memory provider plugin

[amiller]

Summary

Adds Contexto (the OSS self-hosted memory engine) as a MemoryProvider plugin. Per-turn ingest of (user, assistant) pairs into the cognitive store (episodic / semantic / procedural sectors), semantic recall before each turn, plus a contexto_search tool exposed to the model. Sits alongside the existing mem0, honcho, supermemory, etc. plugins — same lifecycle, same interface contract.

Draft because it depends on two changes still in flight upstream at ekailabs/contexto:

• ekailabs/contexto#143 — Python client at clients/python/ (the pip dependency this plugin imports)
• ekailabs/contexto#145 — extractor user-identity fix (without it, the plugin still works but emits unanchored User subjects in extracted triples)

The pip_dependencies line in plugin.yaml currently points at the contexto fork (amiller/contexto); will switch to ekailabs/contexto:main once #143 lands.

What's in the plugin

File	Purpose
plugins/memory/contexto/__init__.py	ContextoMemoryProvider impl
plugins/memory/contexto/plugin.yaml	name/version/desc + pip dep + activation metadata
plugins/memory/contexto/README.md	install + activation walkthrough
plugins/memory/contexto/tests/test_plugin.py	regression tests (require live selfhost; skip if unreachable)

Behavior

• Targets self-hosted Contexto only (http://localhost:4010 by default, override via CONTEXTO_BASE_URL). Not compatible with the hosted api.getcontexto.com mindmap surface — different endpoints, different abstractions.
• Agent slug = agent_identity (the active hermes profile name, e.g. default, coder). One slug per profile, so all sessions of a profile share recall — same scoping convention as the other memory plugins.
• user_id fallback — when the gateway doesn't supply a platform user_id (CLI sessions), uses agent_identity as the contexto userId. Without this, the contexto extractor produces bare User / I triple subjects instead of resolvable identities.
• Honors agent_context — only the primary agent ingests. Subagents and cron contexts skip writes (their tool-output-heavy turns would corrupt recall semantics and reliably blow extraction timeouts on Gemini Flash). Subagent results still reach memory via on_delegation(task, result) as a single curated parent turn.
• Daemon-thread errors logged, not printed — the plugin runs ingest and prefetch on background threads; failures route through logger.warning (so they land in agent.log) instead of dumping raw tracebacks to stderr (which polluted the chat UI in earlier iterations).
• Tools exposed: one tool, contexto_search, for explicit recall queries from the model.

Testing

tests/test_plugin.py covers:

• Subagent / cron / flush contexts skip ingest, prefetch, and agent registration (no threads spawned, no HTTP)
• Primary context ingests normally
• on_delegation captures (task, result) pairs as a single curated parent turn, recallable via search
• Daemon-thread failures route through the logger, never leak to stderr

All 6 tests pass against a running selfhost (skip if unreachable, so they're CI-safe even without infra).

Activation

# config.yaml
memory:
  provider: contexto

# .env (optional, defaults to localhost:4010)
CONTEXTO_BASE_URL=http://localhost:4010

Or via the wizard: hermes memory setup → pick contexto from the list (auto-detected from plugins/memory/contexto/).

Commit history

• 34d15b1c1 initial plugin
• e0735d2ad honor agent_context + capture subagent results via on_delegation
• 92d8a0712 route ingest/prefetch failures through logger.warning instead of stderr
• c4c7b9288 default user_id to agent_slug when no platform user_id is set

Test plan

• Plugin tests green (6/6)
• Tested live in a real hermes-contexto profile against a self-hosted Contexto stack
• Wait for feat: add Python client at clients/python/ ekailabs/contexto#143 + docs(readme): add troubleshooting section #145 to land, then flip pip dep to upstream
• Mark ready for review

🤖 Generated with Claude Code

[kshitijk4poor]

Thanks for the contribution!

Per the updated CONTRIBUTING.md, new memory providers are no longer accepted as in-tree additions to plugins/memory/:

Memory Providers: CLOSED to new in-tree additions
PRs adding to plugins/memory/ will be closed. Publish as standalone plugin into ~/.hermes/plugins/ or via pip entry point. Must implement MemoryProvider ABC (sync_turn, prefetch, shutdown, optional post_setup).

Closing this in line with that policy. The path forward is to publish it as a standalone plugin so users can install it directly without touching the Hermes source tree. Once it's published, a small docs PR adding it to the Community plugins section of the README is welcome.

Sorry for the bump — appreciate the time you put into this.