feat(sdk-python): accept scope kwargs on memory set/get/delete and reconcile memory.search

[santoshkumarradha]

Fixes #712

Motivation

During tutorial writing, four independent LLM writers all guessed the same non-existent API:

app.memory.set(key, data, scope="global")

That signature does not exist. The Python MemoryInterface only exposed scoped access through accessors (app.memory.global_scope.set(...), app.memory.session(id).set(...), etc.), while the TypeScript SDK already accepts scope (and scopeId) positionally on set/get/delete. When four writers and four models independently reach for the same shape, the API should match the guess. This PR makes the Python API match both the natural guess and the TS SDK.

What changed

Three changes, nothing else.

1. Scope kwargs on MemoryInterface.set / get / delete

• set, get, and delete now accept optional scope and scope_id keyword arguments.
• scope=None (default) keeps today's behavior exactly: set uses automatic context scoping, get performs hierarchical lookup (workflow -> session -> actor -> global), delete uses the current scope. Zero behavior change for existing code.
• scope="global" delegates to global_scope; scope="session"|"actor"|"workflow" delegates to the corresponding accessor and requires scope_id.
• Invalid scope values raise ValueError listing the valid scopes. A non-global scope without a scope_id derives the id from the current execution context headers (same as the accessor path when called mid-execution).
• The accessor API is untouched and remains primary in the docstrings. The kwargs are a thin convenience layer that reuses the same scoped clients (GlobalMemoryClient / ScopedMemoryClient) via a single private dispatch helper, so there is one code path.

2. Reconcile memory.search

The README advertised app.memory.search(...), which does not exist. Corrected to the real method and fixed the scope names.

What was verified against the control plane

• Memory routes: control-plane/internal/server/routes_memory.go:31-41 registers /memory/set, /memory/get, /memory/delete, /memory/list, and vector routes. The only search endpoint is POST /memory/vector/search (routes_memory.go:40). There is no general /memory/search.
• API catalog confirms the same surface: control-plane/internal/server/apicatalog/catalog_entries.go:96-107 lists set/get/delete/list plus vector/search ("Similarity search over vectors"), and no plain memory search.
• Canonical scope names are workflow, session, actor, global — control-plane/internal/handlers/memory.go:273 (scopes := []string{"workflow", "session", "actor", "global"}) and the getScopeID switch at control-plane/internal/handlers/memory.go:422-433. There is no agent or run scope. The server derives scope_id from the X-Workflow-ID / X-Session-ID / X-Actor-ID headers (resolveScope, memory.go:402-418), which the Python MemoryClient._build_headers already sets from scope_id.
• TS parity: sdk/typescript/src/memory/MemoryInterface.ts:41-117 — set/get/delete/exists/listKeys all take scope and scopeId positionally, and MemoryScope is 'workflow' | 'session' | 'actor' | 'global' (sdk/typescript/src/types/agent.ts:72).

Change 2 outcome: the server endpoint does NOT exist. Per scope, I did not invent a search method. Instead I fixed the README:

• app.memory.set() / .get() / .search() -> .similarity_search() (the real method on MemoryInterface).
• Vector-search table row app.memory.search(embedding, top_k=5) -> app.memory.similarity_search(embedding, top_k=5).
• Four-scopes row Global, agent, session, run -> Global, actor, session, workflow (the actual scope names).

The low-level Python MemoryClient already implements similarity_search against /memory/vector/search, so no new SDK method was needed.

3. Scope kwargs on MemoryInterface.similarity_search

To finish the reconciliation, the developer-facing similarity_search accepts the same optional scope/scope_id kwargs as set/get/delete, dispatched through the same _resolve_scope_target helper. This matches the TypeScript SDK's searchVector, which already takes scope/scopeId options, and the low-level Python MemoryClient.similarity_search, which already supported them. scope=None keeps today's behavior exactly.

Test plan

New file sdk/python/tests/test_memory_scope_kwargs.py (all @pytest.mark.unit, mocking the low-level client the same way neighboring memory tests do):

• scope=None default behavior unchanged for set/get/delete
• scope="global" delegation for set/get/delete (and scope_id ignored for global)
• scope="session"|"actor"|"workflow" delegation with explicit scope_id for set/get/delete
• non-global scopes without scope_id delegate through the current execution context
• invalid scope raises ValueError listing valid scopes (on set/get/delete)
• scope=None default behavior unchanged for similarity_search
• scope kwarg delegation for similarity_search (global, session/actor/workflow with and without scope_id, invalid scope)

Results (run in sdk/python):

pytest tests/test_memory_scope_kwargs.py tests/test_memory_client_core.py tests/test_memory_invariants.py
49 passed

ruff check and ruff format pass on the touched files.

Follow-ups filed separately

Out of scope for this PR, noted for later:

• Go harness Result cost field parity
• Go memory on_change parity
• ExecutionFilter version field

Cross-SDK memory check

• TypeScript scalar memory set/get/delete already derived scoped headers from metadata when scopeId was omitted.
• Go scoped memory helpers already derive workflow/session/actor IDs from ExecutionContext, and the control-plane backend intentionally omits empty scope headers without client-side failure.
• Found and fixed one adjacent TypeScript gap in MemoryEventClient.history: event history filtering now derives scope_id from metadata when scopeId is omitted, matching the scalar memory client behavior and the control-plane history query contract.

Additional verification:

cd sdk/typescript && npm test -- --run tests/memory_client_scopes.test.ts tests/memory_client.test.ts tests/memory_interface.test.ts tests/memory_event_client.test.ts
cd sdk/typescript && npm run build
cd sdk/python && /tmp/agentfield-pr707-venv/bin/pytest tests/test_memory_scope_kwargs.py tests/test_memory_client_core.py tests/test_memory_invariants.py

[github-actions]

Performance

SDK	Memory	Δ	Latency	Δ	Tests	Status
Python	9.5 KB	+6%	0.32 µs	-9%	✓	✓
TS	511 B	+46%	1.60 µs	-20%	✓	✗

⚠ Regression detected:

• TypeScript memory: 350 B → 511 B (+46%)

[github-actions]

📊 Coverage gate

Thresholds from .coverage-gate.toml: per-surface ≥ 84%, aggregate ≥ 85%, max per-surface regression ≤ 1.0 pp, max aggregate regression ≤ 0.50 pp.

Surface	Current	Baseline	Δ
control-plane	86.90%	87.40%	↓ -0.50 pp	🟡
sdk-go	92.50%	92.00%	↑ +0.50 pp	🟢
sdk-python	93.82%	93.73%	↑ +0.09 pp	🟢
sdk-typescript	90.42%	90.42%	→ +0.00 pp	🟢
web-ui	84.76%	84.79%	↓ -0.03 pp	🟡
aggregate	85.55%	85.75%	↓ -0.20 pp	🟡

✅ Gate passed

No surface regressed past the allowed threshold and the aggregate stayed above the floor.

[github-actions]

📐 Patch coverage gate

Threshold: 80% on lines this PR touches vs origin/main (from .coverage-gate.toml:thresholds.min_patch).

Surface	Touched lines	Patch coverage	Status
control-plane	0	—	➖ no changes
sdk-go	0	—	➖ no changes
sdk-python	28	100.00%	✅
sdk-typescript	3	100.00%	✅
web-ui	0	—	➖ no changes

✅ Patch gate passed

Every surface whose lines were touched by this PR has patch coverage at or above the threshold.

[AbirAbbas]

Taking this over to land it.

• Merged latest main into the branch (clean merge, no conflicts; no memory-module drift on main).
• Completed the "reconcile memory.search" half at the developer-facing layer: MemoryInterface.similarity_search now accepts the same scope/scope_id kwargs as set/get/delete, through the same _resolve_scope_target dispatch (parity with TS searchVector, which already takes scope/scopeId). scope=None unchanged.
• Fixed stale scope_id: str type hints on ScopedMemoryClient/ScopedMemoryEventClient to Optional[str] (the context-derived explicit-scope path passes None by design), and updated the PR body where it still described the old raise-on-missing-scope_id behavior.
• Added unit tests for the similarity_search scope kwargs (default unchanged, global, session/actor/workflow with and without scope_id, invalid scope).

Testing: all memory tests pass (test_memory_scope_kwargs.py now 37 tests, plus core/invariants/events files — 75 passed). Full sdk/python suite: 1706 collected, 1691 passed, 4 skipped, 11 failed — the same 11 failures reproduce on a clean origin/main checkout in my Windows environment (run_cli/tool-calling/async-execution, unrelated to memory), so they're pre-existing and environment-specific. ruff check and ruff format --check clean on touched files.

Also verified end-to-end against a live local control plane: app.memory.set/get/delete(key, ..., scope=...) across global/session/workflow, context-derived scope ids, hierarchical get, accessor-style reads of kwarg-written values, similarity_search(embedding, scope="global") finding a stored vector, and ValueError on invalid scopes — 14/14 checks passed.

[AbirAbbas]

recheck