Skip to content

feat: add MemoryClient for control plane + data plane passthrough#108

Open
Hweinstock wants to merge 1 commit intoaws:mainfrom
Hweinstock:feat/memory-client
Open

feat: add MemoryClient for control plane + data plane passthrough#108
Hweinstock wants to merge 1 commit intoaws:mainfrom
Hweinstock:feat/memory-client

Conversation

@Hweinstock
Copy link
Copy Markdown
Contributor

@Hweinstock Hweinstock commented Mar 16, 2026 •
edited
Loading

Description

Add MemoryClient for Bedrock AgentCore Memory, covering both control plane and data plane operations.

Uses a Proxy with declaration merging to expose a curated set of AWS SDK methods as direct passthroughs on the client.

.memory(memoryId) returns a scoped ScopedMemory that auto-injects the memoryId into every call, reducing repetition when operating on a single memory.

Convenience methods for common workflows:

  • createOrGetMemory — idempotent create (falls back to get on conflict)
  • createMemoryAndWait / deleteMemoryAndWait — polling wrappers
  • waitForMemories — polls until LTM extraction produces records
  • getLastKTurns — retrieves the last K conversation turns grouped by USER boundaries
  • listBranches — aggregates branch info from events

Core design decisions vs Python SDK:

  • Single class instead of Python's 3 (MemoryClient, MemoryControlPlaneClient, MemorySessionManager)
  • No strategy helpers — SDK's UpdateMemoryCommand already has full typed configs
  • No response normalization or wrapper models — TS SDK types are canonical
  • Strands integration will not live here and will be decoupled from core memory functionality

NOTE: Not yet published into the vended SDK, no entry in the package.json exports map. Will be added once integration tests are in place.

Testing

Unit tests use dependency injection (injectable SDK clients via MemoryClientConfig) with simple fakes to avoid mocks. Tests verify:

  • Passthrough routing: every data plane and control plane method is exposed as a function on the real client
  • ScopedMemory: scoped methods are callable
  • Convenience methods: createOrGetMemory conflict handling, deleteMemoryAndWait polling, getLastKTurns turn boundary parsing, listBranches aggregation

Type of Change

New feature

Checklist

  • I have read the CONTRIBUTING document
  • I have added any necessary tests that prove my fix is effective or my feature works
  • I have updated the documentation accordingly
  • I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
  • My changes generate no new warnings
  • Any dependent changes have been merged and published

#125
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

jariy17
jariy17 reviewed Mar 19, 2026
View reviewed changes
Comment thread src/memory/client.ts
return Array.from(branches.values())
}

memory(memoryId: string): ScopedMemory {
Copy link
Copy Markdown
Contributor

@jariy17 jariy17 Mar 19, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this design, but I dont understand the benefits of having a ScopeMemory. Could you explain why a customer just provide the memoryId themselves each time they call createEvent and similar functions?

Copy link
Copy Markdown
Contributor Author

@Hweinstock Hweinstock Apr 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mostly verbosity, there is no reason they can't manually provide an ID each time. I saw it as concise way to combine a memory-scoped client, and a raw SDK client into a single interface. The same functionality is split between clients in the existing python implementation.

Happy to leave it out, if we think its awkward/wont be used.

Copy link
Copy Markdown
Contributor

@jariy17 jariy17 Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lets leave it out for now

@Hweinstock Hweinstock force-pushed the feat/memory-client branch from 71ebaf4 to 680233d Compare April 7, 2026 20:01
@Hweinstock Hweinstock force-pushed the feat/memory-client branch from 680233d to c28b662 Compare April 7, 2026 20:28
@Hweinstock Hweinstock force-pushed the feat/memory-client branch from c28b662 to 18dd5ee Compare April 7, 2026 20:31
@Hweinstock Hweinstock changed the title feat: add MemoryClient for control plane + data plane with session sc… feat: add MemoryClient for control plane + data plane passthrough Apr 7, 2026
@Hweinstock Hweinstock marked this pull request as ready for review April 7, 2026 20:41
@Hweinstock Hweinstock requested a review from a team April 7, 2026 20:41
jesseturner21
jesseturner21 reviewed Apr 16, 2026
View reviewed changes
Comment thread src/_utils/polling.ts
* @returns `true` if the condition was met, `false` if timed out (only when `timeoutErrorMessage` is not set)
* @throws Error with `timeoutErrorMessage` if provided and timeout expires
*/
export async function pollUntil(
Copy link
Copy Markdown

@jesseturner21 jesseturner21 Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice!

Comment thread src/memory/__tests__/client.test.ts
Comment on lines +7 to +17
function fakeControlPlane(overrides: Record<string, (input: unknown) => unknown>): Record<string, unknown> {
return new Proxy({} as Record<string, unknown>, {
get: (_, method) => overrides[method as string] ?? (() => Promise.resolve({})),
})
}

function fakeDataPlane(overrides: Record<string, (input: unknown) => unknown>): Record<string, unknown> {
return new Proxy({} as Record<string, unknown>, {
get: (_, method) => overrides[method as string] ?? (() => Promise.resolve({})),
})
}
Copy link
Copy Markdown

@jesseturner21 jesseturner21 Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SUPER NIT: is there any reason these are diff, they are both the same implementation just diff names.

It could be something like fakeClient(....)

jesseturner21 added a commit that referenced this pull request Apr 16, 2026
@jesseturner21
Merge PR #108: feat: add MemoryClient for control plane + data plane …
fa282f1 
…passthrough
@jesseturner21 jesseturner21 mentioned this pull request Apr 16, 2026
Merged
5 tasks
jesseturner21 added a commit that referenced this pull request Apr 16, 2026
@jesseturner21
refactor(memory): remove ScopedMemory in favor of explicit memoryId
0091488 
Per review feedback on PR #108: drop the memory-scoped interface since
customers can pass memoryId directly to each MemoryClient method without
meaningful verbosity savings.

Removes:
- MemoryClient.memory(memoryId) factory
- ScopedMemory interface and export
- Scoping-focused tests

Tests now call getLastKTurns and listBranches directly with memoryId.
Also applies prettier formatting to PR #108 files that were flagged by
the format:check hook.

Confidence: high
Scope-risk: narrow
jesseturner21 added a commit that referenced this pull request Apr 17, 2026
@jesseturner21
Merge pull request #139 from aws/feat/merge-memory-client
8e5c5cd 
chore: merge PR #108 MemoryClient into feat/agentcore-memory
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jesseturner21 jesseturner21 jesseturner21 left review comments

@jariy17 jariy17 jariy17 left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

type: test

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@Hweinstock @jesseturner21 @jariy17