external-memory-plugin

External Memory Plugin

Develop external memory adapters against the current Nexent contract and prove them without live-service CI dependencies.

Establish scope

1. Read the repository AGENTS.md and invoke its SPEC workflow for production behavior changes.
2. Inspect, rather than assume, these current contracts:
   • sdk/nexent/memory/providers/base.py
   • sdk/nexent/memory/models.py
   • backend/services/memory_provider_plugin_loader.py
   • backend/services/memory_external_provider_service.py
3. Read references/plugin-contract.md before creating or reviewing a manifest or provider.
4. Read references/mem0-example.md when implementing HTTP transport, error mapping, or tests.
5. Preserve tenant, user, Agent, and conversation scope. Never print or persist credentials.

Implement the adapter

1. Create <plugin-dir>/<name>/plugin.yaml and provider.py.
2. Declare only implemented capabilities in implements.
3. Make protocol methods asynchronous and return the exact Nexent models.
4. Honor provider-level timeout_seconds and result limits.
5. Map remote failures to ProviderError and the retry exception matching recovery semantics.
6. Keep OTel attributes low-cardinality and free of queries, memory content, user identifiers, tenant identifiers, and secrets. Rely on the orchestration service's standard instrumentation unless provider-specific spans add actionable detail.
7. Treat the deployment search/ingest switches as kill switches and the provider enabled field as the instance switch; do not bypass them in normal runtime paths.

Test without external dependencies

1. Test manifest discovery and protocol validation with a temporary plugin directory.
2. Mock the network at the HTTP client transport boundary; for httpx, use MockTransport.
3. Cover successful, empty, partial, malformed, unauthorized, forbidden, rate-limited, timeout, connection, and server-error responses as applicable.
4. Assert request scope and authentication shape without using real credentials.
5. Assert every ingest unit receives a result and retry classification is correct.
6. Run the narrow plugin and loader suites first, then affected service and integration suites.
7. Reach at least 90% coverage for each new or modified module.