feat: Add MemoryStore protocol for cross-session agent memory

[rdwj]

Summary

Adds a MemoryStore protocol and a MemoryHub-backed implementation for governed, cross-session agent memory. This is the ADK component of the integration proposal in kagenti/kagenti#1334.

MemoryStore complements ContextStore: where ContextStore replays the current conversation, MemoryStore provides durable knowledge that persists across sessions — preferences, decisions, and project context that agents should remember regardless of which conversation is active.

What's included:

• MemoryStore protocol and MemoryStoreInstance Protocol in kagenti_adk.server.store — follows the same Protocol + ABC + create(context_id) factory pattern as ContextStore
• MemoryHubMemoryStore implementation wrapping the memoryhub Python SDK (optional dependency via pip install kagenti-adk[memoryhub])
• create_memory_dependency() helper for the ADK Depends DI pattern — includes a lazy proxy workaround for Depends does not await async dependency callables #229
• 42 unit tests covering all methods, edge cases, DI lifecycle, and curation-gated writes
• Developer documentation in docs/development/sdk/memory.mdx

Validated in PoC (2026-04-23): Memory write, semantic search recall, and pod restart survival confirmed end-to-end on a fresh RHPDS cluster with Kagenti + MemoryHub + test agent. Details in kagenti/kagenti#1334.

Linked Issues

Relates to kagenti/kagenti#1334 (integration proposal)
Workaround for #229 (Depends doesn't await async callables)

Documentation

Documentation is included: docs/development/sdk/memory.mdx, registered in docs.json under the "Using the SDK" group (development version).

/cc @Ladas

[JanPokorny]

Hi, thank you for the PR. I added some feedback to help align with the current ADK patterns. Ping back if something does not make sense to you.

[rdwj]

@JanPokorny

Thanks for the careful review. I've pushed a rework on feat/memory-store-protocol. Here's the comment-by-commit map:

1. Depends doesn't await async callables → a327e12e moves resolution into the lifespan() body and awaits any awaitable; the proxy workaround is gone in commit 5.
2. MemoryStoreInstance.write should be create → 1e36b232 renames at the protocol level and propagates.
3. Protocol leaks MemoryHub vocabulary (scope/weight/tags/project_id) → 5c0336ab keeps the fields but documents them as backend-defined with MemoryHub mapped as a worked example. The "tenancy boundary" wording you flagged on project_id is corrected — tenancy comes from the backend's auth credentials.
4. No A2A extension for MemoryHub; from_env is a magic factory → 898a500f adds the extension shape line-for-line on services/llm.py. Env vars are kept only as the server-side fallback inside _memoryhub_fulfillment_from_env() (mirrors _llm_fulfillment_from_env).
5. MemoryHubMemoryStore / _MemoryProxy / create_memory_dependency are awkward → 6158798a deletes them. MemoryHubExtensionServer now owns the client lifecycle via its A2A lifespan() and exposes store(context_id) -> MemoryHubMemoryStoreInstance.
6. Re-exports in server/store/__init__.py → d6ba004e removes them; every consumer in the repo already imports from the concrete module.
7. No working example → 23622531 adds examples/agent-integration/memoryhub/memoryhub-recall plus the matching E2E test. It skips cleanly when MEMORYHUB_E2E_* repo secrets aren't set; please add them when you're ready.
8. memory.mdx still describes the old from_env/proxy flow → dbef463b rewrites it for the extension flow, switches install to uv add, and embeds the new example via embedme.
9. Module-top imports for memoryhub → rolled into 6158798a; memoryhub is the optional extra, so the imports live at module top now.

A trailing 5d8dbcd4 cleans up three ruff findings the rework introduced. Local: 123 unit tests pass, ruff check clean.

[JanPokorny]

I don't like using empty string as an error state, too easy to forget to handle it. Throw an exception or return None. Also, what does "curation gated the create" mean exactly?

[rdwj]

Thanks — agreed, returning an empty string was too easy to miss. Fixed in 481a68f with a follow-up clarifying comment in a853d7a.

The implementation now raises MemoryRejectionError (in kagenti_adk.server.store.exceptions), which subclasses RuntimeError and carries the backend's reason on .reason. That matches the existing ToolCallRejectionError / ApprovalRejectionError pattern, and the exception's own docstring spells out what the various rejection sources are so callers don't have to read MemoryHub's internals.

To answer "what does curation gated the create mean exactly": MemoryHub runs every write through a pre-storage pipeline that can refuse to record the memory — typically because it's a duplicate of an existing memory, contradicts an existing memory, or trips a policy/curator rule, such as PII or secrets filtering. The reason string on the exception is the backend's explanation. The old logger.warning is gone; the exception itself is the signal, matching how the other *RejectionErrors in the SDK are raised without a sibling log line.

I also added a short inline comment at the SDK boundary (a853d7a) noting that memoryhub.WriteResult.memory is None is the rejection signal — the contract is invisible at the call site otherwise.

Docs and the rejection test were updated accordingly. Unit suite stays at 123 passing, ruff clean.

[rdwj]

Pausing this PR — found that the upstream memoryhub Python SDK is wholesale broken against the compacted-tool memory-hub server (issue redhat-ai-americas/memory-hub#198 dropped per-action MCP tools in favor of a single memory(action="...") dispatcher; the SDK still calls search_memory / read_memory / etc.). Will rework the SDK against the new surface and then ping for the next review pass.

[rdwj]

Unpausing — fixed the underlying issue and pushed 79ad3d28 bumping the pin to memoryhub>=0.7.0.

Background. The memoryhub SDK was wholesale broken against the deployed primary memory-hub-mcp server. Upstream had consolidated 10 per-action MCP tools into a single memory(action=...) dispatcher (redhat-ai-americas/memory-hub#198, #202) but the SDK still called the legacy tool names — every operational method raised Unknown tool end-to-end, including the search/write/read/update/delete path your MemoryHubMemoryStoreInstance wrapper exercises. The kagenti-ci HTTP-200 smoke test against the route only confirmed the route was alive, not that any memory operation worked.

Upstream fix. redhat-ai-americas/memory-hub#211 — reworks MemoryHubClient to dispatch every operation through the unified tool, keeping all public Python signatures stable. Released as memoryhub==0.7.0 (https://pypi.org/project/memoryhub/0.7.0/). The wrapper code in this PR did not need to change; just the dependency pin.

New SDK contract test. redhat-ai-americas/memory-hub#208 / sdk/tests/test_sdk_kagenti_contract.py was added in the same upstream PR. It pins exactly the surface this wrapper depends on: constructor (api_key + OAuth modes), search/write/read/update/delete, the WriteResult.curation.reason path that MemoryRejectionError raises on, and NotFoundError on missing-id reads/deletes. A failure there in the future is the cue to coordinate with you before shipping.

Verification done locally. All 24 tests/unit/server/store/test_memory_store.py cases pass against memoryhub==0.7.0 with no source changes. Ruff is clean. Live smoke against the primary server (write → read → update → delete → re-delete-NotFoundError) all succeed via the wrapper.

One snag for your CI / re-test. This repo's [tool.uv] exclude-newer = "3 days" filters out 0.7.0 (uploaded today). Two options:

1. Wait until ~2026-05-02 and the lock will pick up 0.7.0 naturally; OR
2. Run UV_EXCLUDE_NEWER="0 days" uv lock --upgrade-package memoryhub to refresh apps/adk-py/uv.lock now (this writes exclude-newer-span = "PT0S" into the lock options, which I deliberately did not commit since it relaxes the project's policy).

I left the lock alone so you can choose. Happy to push the lock update as a follow-up commit if you'd prefer option 2.