Adding Checkpointer and Store Implementation of Amazon Bedrock AgentCore Memory

.changeset/fast-bears-shop.md

@@ -0,0 +1,5 @@
+---
+"@langchain/langgraph-checkpoint-aws-agentcore-memory": minor
+---
+
+Adding support for Amazon Bedrock AgentCore Memory as Checkpointer and Store

.changeset/quick-rabbits-rule.md

@@ -0,0 +1,6 @@
+---
+"@langchain/langgraph-checkpoint-validation": minor
+"@langchain/langgraph-checkpoint-aws-agentcore-memory": patch
+---
+
+Validation tests for AgentCore Memory are added

libs/checkpoint-aws-agentcore-memory/.env.example

@@ -0,0 +1,10 @@
+# ------------------LangSmith tracing------------------
+LANGCHAIN_TRACING_V2=true
+LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
+LANGCHAIN_API_KEY=
+LANGCHAIN_PROJECT=
+# -----------------------------------------------------
+
+# AWS Bedrock AgentCore Memory configuration
+AWS_REGION=<aws-region>
+AGENTCORE_MEMORY_ID="agent_core_memory_id_for_checkpointer_testing-F6suJWCsg"

libs/checkpoint-aws-agentcore-memory/.eslintrc.cjs

@@ -0,0 +1,83 @@
+module.exports = {
+  extends: [
+    "airbnb-base",
+    "eslint:recommended",
+    "prettier",
+    "plugin:@typescript-eslint/recommended",
+  ],
+  parserOptions: {
+    ecmaVersion: 12,
+    parser: "@typescript-eslint/parser",
+    project: "./tsconfig.json",
+    sourceType: "module",
+  },
+  plugins: ["@typescript-eslint", "no-instanceof"],
+  ignorePatterns: [
+    ".eslintrc.cjs",
+    "scripts",
+    "node_modules",
+    "dist",
+    "dist-cjs",
+    "*.js",
+    "*.cjs",
+    "*.d.ts",
+  ],
+  rules: {
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/ban-ts-comment": "error",
+    "no-process-env": 2,
+    "no-instanceof/no-instanceof": "off",
+    "no-param-reassign": "off",
+    "no-plusplus": "off",
+    "no-constant-condition": "off",
+    "no-promise-executor-return": "off",
+    "no-unreachable-loop": "off",
+    "@typescript-eslint/explicit-module-boundary-types": 0,
+    "@typescript-eslint/no-empty-function": 0,
+    "@typescript-eslint/no-shadow": 0,
+    "@typescript-eslint/no-empty-interface": 0,
+    "@typescript-eslint/no-use-before-define": ["error", "nofunc"],
+    "@typescript-eslint/no-unused-vars": ["warn", { args: "none" }],
+    "@typescript-eslint/no-floating-promises": "error",
+    "@typescript-eslint/no-misused-promises": "error",
+    "arrow-body-style": 0,
+    camelcase: 0,
+    "class-methods-use-this": 0,
+    "import/extensions": [2, "ignorePackages"],
+    "import/no-extraneous-dependencies": [
+      "error",
+      { devDependencies: ["**/*.test.ts", "**/*.int.test.ts"] },
+    ],
+    "import/no-unresolved": 0,
+    "import/prefer-default-export": 0,
+    "keyword-spacing": "error",
+    "max-classes-per-file": 0,
+    "max-len": 0,
+    "no-await-in-loop": 0,
+    "no-bitwise": 0,
+    "no-console": 0,
+    "no-empty-function": 0,
+    "no-restricted-syntax": 0,
+    "no-shadow": 0,
+    "no-continue": 0,
+    "no-void": 0,
+    "no-underscore-dangle": 0,
+    "no-use-before-define": 0,
+    "no-useless-constructor": 0,
+    "no-return-await": 0,
+    "consistent-return": 0,
+    "no-else-return": 0,
+    "func-names": 0,
+    "no-lonely-if": 0,
+    "prefer-rest-params": 0,
+    "new-cap": ["error", { properties: false, capIsNew: false }],
+  },
+  overrides: [
+    {
+      files: ["**/*.int.test.ts"],
+      rules: {
+        "no-process-env": "off",
+      },
+    },
+  ],
+};

libs/checkpoint-aws-agentcore-memory/.prettierrc

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "quoteProps": "as-needed",
+  "jsxSingleQuote": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "requirePragma": false,
+  "insertPragma": false,
+  "proseWrap": "preserve",
+  "htmlWhitespaceSensitivity": "css",
+  "vueIndentScriptAndStyle": false,
+  "endOfLine": "lf"
+}

libs/checkpoint-aws-agentcore-memory/README.md

@@ -0,0 +1,140 @@
+# @langchain/langgraph-checkpoint-aws-agentcore-memory
+
+LangGraph checkpointer implementation using AWS Bedrock AgentCore Memory.
+
+## Usage
+
+```typescript
+import {
+  AgentCoreMemorySaver,
+  AgentCoreMemoryStore,
+} from "@langchain/langgraph-checkpoint-aws-agentcore-memory";
+
+// Checkpointer for state persistence
+const checkpointer = new AgentCoreMemorySaver({
+  memoryId: "your-memory-id",
+  region: "us-east-1", // optional, defaults to AWS SDK default
+});
+
+// Store for key-value data persistence
+const store = new AgentCoreMemoryStore({
+  memoryId: "your-memory-id",
+  region: "us-east-1", // optional, defaults to AWS SDK default
+});
+
+// Use with LangGraph
+const graph = builder.compile({ checkpointer, store });
+```
+
+## Configuration
+
+Both `AgentCoreMemorySaver` and `AgentCoreMemoryStore` require:
+
+- `memoryId`: The AWS Bedrock AgentCore Memory ID
+- `region` (optional): AWS region, defaults to SDK default
+
+## Requirements
+
+- AWS credentials configured (via environment variables, IAM roles, or AWS SDK configuration)
+- Access to AWS Bedrock AgentCore Memory service
+- Required IAM permissions for AgentCore Memory operations
+
+## Features
+
+### AgentCoreMemorySaver
+
+- ✅ Extends `BaseCheckpointSaver` from `@langchain/langgraph-checkpoint`
+- ✅ Reuses serialization/deserialization from base library
+- ✅ Supports all standard checkpointer operations (getTuple, list, put, putWrites, deleteThread)
+- ✅ Thread-based state isolation using AgentCore Memory sessions
+- ✅ Automatic retry logic with exponential backoff for AWS API throttling
+- ✅ Rate limiting to stay within AgentCore Memory API limits (20 req/sec)
+- ✅ Unique actor ID generation for test isolation
+
+### AgentCoreMemoryStore
+
+- ✅ Extends `BaseStore` from `@langchain/langgraph-checkpoint`
+- ✅ Supports all standard store operations (get, put, delete, search, batch, listNamespaces)
+- ✅ Hierarchical namespace organization for data isolation
+- ✅ Metadata filtering and pagination for search operations
+- ✅ Complex JSON value support with proper serialization
+- ✅ Rate limiting and retry logic consistent with checkpointer
+- ✅ Unique actor ID generation per store instance
+
+## Architecture
+
+Both implementations map LangGraph concepts to AgentCore Memory:
+
+### Checkpointer Mapping
+
+- `thread_id` → `sessionId` in AgentCore Memory
+- `actor_id` → `actorId` in AgentCore Memory (required for all operations)
+- `checkpoint_ns` → stored in event payload and filtered during retrieval
+
+### Store Mapping
+
+- `namespace[0]` → `sessionId` in AgentCore Memory
+- `namespace[1]` → `actorId` in AgentCore Memory (with fallback to unique default)
+- `namespace` → stored in event payload for hierarchical organization
+- Store items → events with "store_item" type in AgentCore Memory
+
+## Testing
+
+Switch to `langgraphjs/libs/checkpoint-aws-agentcore-memory`:
+
+```bash
+$ cd langgraphjs/libs/checkpoint-aws-agentcore-memory
+```
+
+### Unit Tests
+
+```bash
+pnpm test
+```
+
+### Integration Tests
+
+Integration tests require AWS credentials and a valid AgentCore Memory ID:
+
+1. Copy `.env.example` to `.env`:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Set your AWS configuration:
+
+You will need to create an instance of AgentCore Memory in your AWS account. Make sure that AWS credentials are available for your session in your terminal environment.
+
+```bash
+AWS_REGION=us-east-1
+AGENTCORE_MEMORY_ID=your-actual-memory-id
+```
+
+3. Run integration tests:
+
+   ```bash
+   # Test checkpointer
+   pnmp test:int
+
+   # Test store
+   pnmp test:int:store
+
+   # Test both
+   pnmp test:int && pnmp test:int:store
+   ```
+
+### Validation Tests
+
+Run the comprehensive validation test suite:
+
+```bash
+# Run all validation tests
+./run-validation-tests.sh
+
+# Run specific test suites
+./run-validation-tests.sh getTuple list
+./run-validation-tests.sh deleteThread
+```
+
+Available test suites: `getTuple`, `list`, `put`, `putWrites`, `deleteThread`

libs/checkpoint-aws-agentcore-memory/index.ts

@@ -0,0 +1 @@
+export * from "./src/index.js";

libs/checkpoint-aws-agentcore-memory/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@langchain/langgraph-checkpoint-aws-agentcore-memory",
+  "version": "0.1.0",
+  "description": "LangGraph checkpointer implementation using AWS Bedrock AgentCore Memory",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:langchain-ai/langgraphjs.git"
+  },
+  "scripts": {
+    "build": "pnpm turbo build:internal --filter=@langchain/langgraph-checkpoint-aws-agentcore-memory",
+    "build:internal": "pnpm --filter @langchain/build compile @langchain/langgraph-checkpoint-aws-agentcore-memory",
+    "clean": "rm -rf dist/ dist-cjs/ .turbo/",
+    "prepublish": "pnpm build",
+    "test": "vitest run --exclude='**/*.int.test.ts'",
+    "test:watch": "vitest watch --exclude='**/*.int.test.ts'",
+    "test:int": "vitest run src/tests/checkpoints.int.test.ts",
+    "test:int:store": "vitest run src/tests/store.int.test.ts",
+    "lint:eslint": "NODE_OPTIONS=--max-old-space-size=4096 eslint --cache --ext .ts,.js src/",
+    "lint:dpdm": "dpdm --exit-code circular:1 --no-warning --no-tree src/*.ts src/**/*.ts",
+    "lint": "pnpm lint:eslint && pnpm lint:dpdm",
+    "lint:fix": "pnpm lint:eslint --fix && pnpm lint:dpdm",
+    "format": "prettier --config .prettierrc --write \"src\"",
+    "format:check": "prettier --config .prettierrc --check \"src\""
+  },
+  "author": "Hasnain Virk",
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-bedrock-agentcore": "^3.0.0",
+    "@langchain/core": "^0.3.0",
+    "@langchain/langgraph-checkpoint": "workspace:*",
+    "@smithy/node-http-handler": "^3.0.0",
+    "@smithy/util-retry": "^3.0.0"
+  },
+  "devDependencies": {
+    "@langchain/langgraph-checkpoint-validation": "workspace:*",
+    "@types/uuid": "^9",
+    "@typescript-eslint/eslint-plugin": "^6.12.0",
+    "@typescript-eslint/parser": "^6.12.0",
+    "dotenv": "^16.0.0",
+    "dpdm": "^3.12.0",
+    "eslint": "^8.33.0",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-config-prettier": "^8.6.0",
+    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-no-instanceof": "^1.0.1",
+    "eslint-plugin-prettier": "^4.2.1",
+    "prettier": "^2.8.3",
+    "resolve-tspaths": "^0.8.8",
+    "typescript": "~5.1.6",
+    "uuid": "^9",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./dist-cjs/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "dist-cjs/",
+    "index.cjs",
+    "index.js",
+    "index.d.ts"
+  ]
+}