sdk: Rework against compacted memory(action=...) tool surface (#210, #208)

* planning: Add design for SDK rework against compacted tool surface

The memoryhub SDK still calls per-action MCP tools but the deployed
primary server only exposes register_session + memory after #198/#202.
Issue #202 called for keeping per-action tools as deprecation aliases;
that step was skipped. The kagenti-adk integration in kagenti/adk#231
hit this when run against the live server.

Decision recorded: take the SDK forward to the new surface rather
than back-porting server-side aliases. Public method signatures stay
stable; only the wire format changes. Bump SDK 0.6.0 → 0.7.0.

Tracks #210.

Assisted-by: Claude Code (Opus 4.7)
Signed-off-by: rdwj <wjackson@redhat.com>

* sdk: Rework client against compacted memory(action=...) tool surface

Every public MemoryHubClient method now dispatches through the
unified `memory` tool (#198/#202) instead of the legacy per-action
tool names. Public Python API is unchanged — only the wire format
changes. This restores end-to-end behavior against the primary
memory-hub-mcp deployment, which exposes only register_session +
memory after the consolidation.

The cutover replaces the deprecation-alias path that was scoped in
#202 but never shipped.

Signature stability is the load-bearing property here: the
kagenti-adk MemoryStore wrapper (kagenti/adk#231) calls search,
write, read, update, delete, etc. directly — those signatures are
preserved, so consumers only need to bump the dependency pin.

Smoke-tested against the live primary server: search, get_session,
and list_projects all succeed. Note: server-side max_results
behavior on search appears to over-return appendix entries; that's
a separate server bug, not SDK.

Tracks #210.

Assisted-by: Claude Code (Opus 4.7)
Signed-off-by: rdwj <wjackson@redhat.com>

* sdk: Bump to 0.7.0 with BREAKING wire-format note

The 0.6.0 → 0.7.0 cutover swaps every MCP tool call from the legacy
per-action names to memory(action=..., options={...}). Public Python
API is unchanged but the wire format is incompatible with servers
that only expose the per-action surface, and 0.6.0 is incompatible
with the primary memory-hub-mcp deployment.

Tracks #210.

Assisted-by: Claude Code (Opus 4.7)
Signed-off-by: rdwj <wjackson@redhat.com>

* sdk: Add kagenti-adk contract test (#208)

Pins the SDK surface that kagenti-adk's MemoryHubMemoryStoreInstance
depends on: constructor (api_key + OAuth modes), search/write/read/
update/delete signatures, the WriteResult.curation.reason path that
the wrapper raises MemoryRejectionError on, and NotFoundError on
missing-id reads/deletes.

Uses the SDK's existing mocked transport — no live server needed.
A failure here is the cue to coordinate with kagenti-adk maintainers
before shipping the SDK release.

Closes #208.

Assisted-by: Claude Code (Opus 4.7)
Signed-off-by: rdwj <wjackson@redhat.com>

---------

Signed-off-by: rdwj <wjackson@redhat.com>

Author: rdwj

planning/sdk-compacted-tool-rework.md

@@ -0,0 +1,163 @@
+# SDK rework against compacted memory(action=...) tool surface
+
+Status: Proposed — 2026-04-29
+Tracks: (issue to be filed)
+Author: @rdwj (drafted with Claude Code Opus 4.7)
+
+## Why this exists
+
+Issues #198/#201/#202 reduced the MemoryHub MCP server's tool surface from 10
+per-action tools to a single `memory(action=...)` dispatcher (plus
+`register_session`). That work shipped on the `memory-hub-mcp` (primary)
+deployment, which is the only deployment exposing the full operation surface.
+The minimal deployment retains a 4-tool subset for legacy integrations.
+
+Issue #202's scope explicitly called for keeping the per-action tools as
+temporary aliases for a deprecation window. That aliasing step was never
+shipped, and the `memoryhub` Python SDK (currently v0.6.0) still calls the
+old per-action tool names (`search_memory`, `read_memory`, `write_memory`,
+etc.). The result: `MemoryHubClient` cannot talk to the primary deployment
+at all — `register_session` succeeds but every operational method raises
+`ToolError: Unknown tool: '<name>'`.
+
+This was caught when the kagenti-adk integration in
+[kagenti/adk PR #231](https://github.com/kagenti/adk/pull/231) was tested
+against the live primary server. The PR is paused until this is fixed.
+
+## What this rework is
+
+The cutover. We take the SDK forward to the new surface instead of
+back-porting compatibility aliases on the server. Wes confirmed
+2026-04-29: "we did flag the SDK as necessary follow-on work and we
+should have done that very next thing and did not. This is our chance
+to rectify that."
+
+## Scope
+
+1. Rewrite `MemoryHubClient` internals so every method dispatches via
+   `memory(action=..., memory_id=..., query=..., content=..., scope=...,
+   project_id=..., options={...})` instead of calling per-action tool
+   names directly.
+2. Keep all public method signatures stable. The kagenti-adk wrapper
+   already calls `client.search(query, scope=..., project_id=...,
+   max_results=...)`, etc.; that surface must not change. Only the wire
+   format the SDK emits to the MCP server changes.
+3. `register_session` stays a separate tool call — it is unchanged on
+   the server.
+4. Update `sdk/tests/test_client.py` to assert the new payload shape:
+   `call_tool("memory", {"action": "search", ...})` instead of
+   `call_tool("search_memory", ...)`.
+5. Bump SDK version `0.6.0 → 0.7.0`. Update `sdk/CHANGELOG.md` with a
+   "BREAKING (wire format)" entry that links this rework, #198, and
+   #202.
+6. Bump kagenti-adk's `memoryhub>=0.5.0` pin to `memoryhub>=0.7.0` in a
+   coordinated PR-#231 follow-up commit.
+
+## Action mapping
+
+The `memory` tool's accepted actions are documented in
+`memory-hub-mcp/src/tools/memory.py`. The mapping for each public SDK
+method:
+
+| SDK method | action | top-level args | options keys |
+|---|---|---|---|
+| `search` | `search` | `query`, `scope`, `project_id` | `max_results`, `weight_threshold`, `current_only`, `mode`, `max_response_tokens`, `include_branches`, `focus`, `session_focus_weight`, `domains`, `domain_boost_weight`, `raw_results`, `owner_id` |
+| `read` | `read` | `memory_id`, `project_id` | `include_versions`, `history_offset`, `history_max_versions`, `hydrate` |
+| `write` | `write` | `content`, `scope`, `project_id` | `weight`, `parent_id`, `branch_type`, `metadata`, `domains`, `force`, `owner_id` |
+| `update` | `update` | `memory_id`, `content`, `project_id` | `weight`, `metadata`, `domains` |
+| `delete` | `delete` | `memory_id`, `project_id` | (none) |
+| `report_contradiction` | `report` | `memory_id`, `project_id` | `observed_behavior`, `confidence` |
+| `resolve_contradiction` | `resolve` | (none) | `contradiction_id`, `resolution_action`, `resolution_note` |
+| `get_similar` | `similar` | `memory_id`, `project_id` | `threshold`, `max_results`, `offset` |
+| `get_relationships` | `relationships` | `memory_id`, `project_id` | `relationship_type`, `direction`, `include_provenance` |
+| `create_relationship` | `relate` | `project_id` | `source_id`, `target_id`, `relationship_type`, `metadata` |
+| `set_curation_rule` | `set_rule` | (none) | `name`, `tier`, `action_type`, `config`, `scope_filter`, `enabled`, `priority` |
+| `list_projects` | `list_projects` | (none) | `filter` |
+| `create_project` | `create_project` | `project_id` | `project_name`, `description`, `invite_only` |
+| `add_project_member` | `add_member` | `project_id` | `user_id`, `role` |
+| `remove_project_member` | `remove_member` | `project_id` | `user_id` |
+| `get_session` | `status` | (none) | (none) |
+| `set_session_focus` | `set_focus` | `project_id` | `focus` |
+| `get_focus_history` | `focus_history` | `project_id` | `start_date`, `end_date` |
+
+Two server-side normalizations to remember when wiring the dispatch:
+
+- `relationships` action takes `memory_id` at the top level but the
+  server's `manage_graph` tool internally renames it to `node_id`. The
+  SDK should pass `memory_id` per the dispatcher contract; the server
+  handles the rename.
+- `describe_project`, `add_member`, `remove_member`, `create_project`
+  take `project_id` at the top level, not `project_name`. The
+  dispatcher normalizes.
+
+## Implementation shape
+
+Add one private helper:
+
+```
+async def _call_action(
+    self,
+    action: str,
+    *,
+    memory_id: str | None = None,
+    query: str | None = None,
+    content: str | None = None,
+    scope: str | None = None,
+    project_id: str | None = None,
+    options: dict | None = None,
+) -> dict:
+    payload = {"action": action}
+    if memory_id is not None: payload["memory_id"] = memory_id
+    if query is not None: payload["query"] = query
+    if content is not None: payload["content"] = content
+    if scope is not None: payload["scope"] = scope
+    if project_id is not None: payload["project_id"] = project_id
+    if options: payload["options"] = options
+    return await self._call("memory", payload)
+```
+
+Each public method becomes a thin wrapper that builds its own `options`
+dict and calls `_call_action`. The error-classification logic in
+`_call` is unchanged — the server returns the same error envelopes for
+the dispatched action as it did for the per-action tools.
+
+## Backwards compatibility
+
+- Public Python API: **stable**. No method signature changes, no
+  imports moved. Existing callers (kagenti-adk wrapper, internal
+  scripts) continue to compile after a version bump.
+- Wire format: **breaking**. SDK 0.6.0 cannot talk to a server with
+  per-action tools removed. SDK 0.7.0 cannot talk to a server that
+  only exposes per-action tools. We pin kagenti-adk to 0.7.0+; the
+  minimal-tool deployment is for legacy connectors and is not in the
+  SDK's target set.
+
+## Out of scope
+
+- Re-introducing server-side per-action tools as aliases. Decision
+  recorded above.
+- Updating fipsagents/agent-template SDK consumers. Track separately
+  if any are pinned <0.7.0.
+- `manage_curation` / `set_curation_rule` parity with the dispatcher.
+  The server still exposes `manage_curation` independently for tier-2
+  callers; the SDK uses the dispatcher path for `set_rule`, `report`,
+  `resolve`. No behavioral change.
+
+## Open questions
+
+- Do we want a `--use-legacy-tools` flag on the SDK for talking to the
+  minimal deployment? Recommend **no** — minimal is a 4-tool subset
+  used by legacy connectors, not a full target. Document in the README
+  instead.
+- Should the rework also update the SDK's docstrings to describe the
+  dispatcher path? Recommend **yes**, but only on methods where the
+  new wire format affects observable behavior (e.g., error messages
+  reference the action name).
+
+## References
+
+- `planning/mcp-single-tool-schema.md` — the original action-dispatch design.
+- `memory-hub-mcp/src/tools/memory.py` — the dispatcher implementation.
+- `sdk/src/memoryhub/client.py` — the SDK to be reworked.
+- `sdk/tests/test_client.py` — the test suite to update.
+- `kagenti/adk` PR #231 — the integration that surfaced the gap.

sdk/CHANGELOG.md

@@ -2,7 +2,21 @@
 
 All notable changes to the `memoryhub` SDK package.
 
-## [0.6.0] — 2026-04-23
+## [0.7.0] — 2026-04-29
+
+- **BREAKING (wire format)**: `MemoryHubClient` now dispatches every
+  operation through the unified `memory(action=..., options={...})` MCP
+  tool introduced by the server-side consolidation in #198/#202.
+  Per-action tool names (`search_memory`, `read_memory`, `write_memory`,
+  `update_memory`, `delete_memory`, `report_contradiction`,
+  `get_similar_memories`, `get_relationships`, `create_relationship`,
+  `set_curation_rule`, `manage_session`, `manage_project`,
+  `set_session_focus`, `get_focus_history`) are no longer called.
+  This release **cannot** talk to a server that only exposes the legacy
+  per-action tools; older releases (≤ 0.6.0) **cannot** talk to the
+  primary `memory-hub-mcp` deployment. The Python API is unchanged —
+  consumers only need to update the dependency pin. Tracks #210, closes
+  the alias gap left by #202.
 
 - **Stub result compatibility**: Default `content` and `owner_id` fields to
   empty strings in the `Memory` model so cache-optimized search responses

sdk/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memoryhub"
-version = "0.6.0"
+version = "0.7.0"
 description = "Centralized, governed memory for AI agents"
 readme = "README.md"
 license = "Apache-2.0"