npm package: @faveo/langgraph-aws-agent-core-ts
Description: AWS Bedrock Agent Core implementation of Checkpointer and Memory Store for LangGraph in Typescript
Author: Faruk Ada
Latest version: 0.0.8
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# LangGraph AWS Agent Core TypeScript

⚠️ **This is a test project and is currently under development.**

A TypeScript implementation of LangGraph's Checkpointer and MemoryStore using AWS Bedrock Agent Core services. This package enables persistent state management and memory storage for LangGraph applications running on AWS infrastructure.

## Features

- **AWS Bedrock Agent Core Integration**: Leverages AWS Bedrock Agent Core for checkpoint and memory management
- **Checkpointer Implementation**: Full implementation of LangGraph's BaseCheckpointSaver for state persistence
- **Memory Store Implementation**: Complete BaseStore implementation for memory operations
- **TypeScript Support**: Written in TypeScript with full type definitions
- **Thread Management**: Support for conversation threads with branching and namespacing
- **Search Capabilities**: Advanced search with filtering and pagination
- **Namespace Organization**: Hierarchical namespace support for organizing data

## Installation

```bash
npm install @faveo/langgraph-aws-agent-core-ts
```

## Requirements

- Node.js >= 20.0.0
- npm >= 10.0.0
- AWS credentials configured
- Access to AWS Bedrock Agent Core services

## Usage

#### 1. Creating a Memory Resource

You can create a Memory resource using AWS CDK, Terraform, or CloudFormation:

**AWS CDK Example:**

```typescript
import * as bac from 'aws-cdk-lib/aws-bedrockagentcore';

const mem = new bac.CfnMemory(this, 'FaveoMemory', {
    name: 'FaveoMemory',
    description: 'Memory for Faveo LangGraph Agent Core',
    eventExpiryDuration: 7,
    memoryExecutionRoleArn: role.roleArn,
});
```

**Terraform Example:**

```hcl
resource "aws_bedrockagentcore_memory" "app_memory" {
  name                     = "FaveoMemory"
  description              = "Memory for Faveo LangGraph Agent Core"
  event_expiry_duration    = 7
  memory_execution_role_arn = aws_iam_role.memory_role.arn
}
```

**Your AWS credentials must have the following permissions:**

**For Checkpointer:**

- bedrock-agentcore:GetEvent
- bedrock-agentcore:ListEvents
- bedrock-agentcore:CreateEvent
- bedrock-agentcore:DeleteEvent

**For Memory Store:**

- bedrock-agentcore:GetMemoryRecord
- bedrock-agentcore:RetrieveMemoryRecords
- bedrock-agentcore:ListMemoryRecords
- bedrock-agentcore:BatchCreateMemoryRecords

### Checkpointer

The `AwsCheckpointer` provides persistent checkpoint storage for LangGraph workflows:

```typescript
import { AwsCheckpointer } from '@faveo/langgraph-aws-agent-core-ts';

const checkpointer = new AwsCheckpointer({
  memoryId: 'your-memory-id',
  actorId: 'your-actor-id', // optional
  clientConfig: {
    region: 'us-east-1',
    // other AWS SDK config options
  }
});

// Use with LangGraph
const config = {
  configurable: {
    thread_id: 'conversation-123',
    checkpoint_ns: 'main'
  }
};

// Save checkpoint
await checkpointer.put(config, checkpoint, metadata, newVersions);

// Retrieve checkpoint
const tuple = await checkpointer.getTuple(config);

// List checkpoints
for await (const checkpoint of checkpointer.list(config)) {
  console.log(checkpoint);
}

// Delete thread
await checkpointer.deleteThread('conversation-123');
```

### Memory Store

The `AwsMemoryStore` provides key-value storage with search capabilities:

```typescript
import { AwsMemoryStore } from '@faveo/langgraph-aws-agent-core-ts';

const store = new AwsMemoryStore({
  memoryId: 'your-memory-id',
  clientConfig: {
    region: 'us-east-1'
  }
});

// Store data
await store.put(['docs', 'reports'], 'report-1', {
  title: 'Annual Report',
  year: 2024
});

// Retrieve data
const item = await store.get(['docs', 'reports'], 'report-1');

// Search with filters
const results = await store.search(['docs'], {
  query: 'annual report',
  filter: { year: 2024 },
  limit: 10,
  offset: 0
});

// List namespaces
const namespaces = await store.listNamespaces({
  matchConditions: [{ path: ['docs'] }],
  limit: 100
});
```

## Configuration

### Checkpointer Options

```typescript
interface AgentCoreCheckpointerOptions {
  memoryId: string;                           // Required: AWS memory ID
  actorId?: string;                           // Optional: Actor identifier (default: 'agentcore-checkpointer')
  clientConfig?: BedrockAgentCoreClientConfig; // Optional: AWS SDK configuration
}
```

### Memory Store Options

```typescript
interface AgentCoreMemoryStoreOptions {
  memoryId: string;                           // Required: AWS memory ID
  clientConfig?: BedrockAgentCoreClientConfig; // Optional: AWS SDK configuration
}
```

### Config Specs

The checkpointer supports the following configuration parameters:

- `thread_id` (string, required): Unique identifier for the conversation thread
- `checkpoint_ns` (string, optional): Namespace for organizing checkpoints (default: "")
- `checkpoint_id` (string, optional): Specific checkpoint identifier for retrieval

## API Reference

### AwsCheckpointer

#### Methods

- `put(config, checkpoint, metadata, newVersions)`: Save a checkpoint
- `getTuple(config)`: Retrieve a specific checkpoint or the latest checkpoint
- `list(config, options?)`: List checkpoints with optional filtering and pagination
- `putWrites(config, writes, taskId, taskPath?)`: Store pending writes
- `deleteThread(threadId)`: Delete all checkpoints for a thread

### AwsMemoryStore

#### Methods

- `get(namespace, key)`: Retrieve a single item
- `put(namespace, key, value)`: Store an item
- `search(namespacePrefix, options?)`: Search items with query and filters
- `listNamespaces(options?)`: List available namespaces
- `batch(operations)`: Execute multiple operations in batch

## Architecture

### Checkpointer Implementation

The checkpointer uses AWS Bedrock Agent Core events to store checkpoints:

- Each checkpoint is stored as an event with serialized checkpoint data
- Branches are used to organize checkpoints by namespace
- Event timestamps maintain checkpoint ordering
- Supports both specific checkpoint retrieval and listing all checkpoints

### Memory Store Implementation

The memory store leverages AWS Bedrock Agent Core memory records:

- Items are stored as memory records with namespace organization
- Full-text search capabilities with filtering
- Hierarchical namespace structure using "/" as delimiter
- Batch operations for efficient data access

## Development

### Building

```bash
npm run build
```

### Testing

```bash
npm test
```

### Linting

```bash
npm run lint
npm run lint:fix
```

### Formatting

```bash
npm run format
npm run format:check
```

## Testing

The package includes comprehensive test coverage using Jest and AWS SDK mocks:

- Unit tests for all checkpointer operations
- Unit tests for all memory store operations
- Mock implementations for AWS SDK clients
- Fixtures for test data generation

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues, questions, or contributions, please visit the GitHub repository.

## Author

**Faruk Ada** - [info@farukada.com](mailto:info@farukada.com)

## Links

- [Homepage](https://github.com/farukada/langgraph-aws-agent-core-ts)
- [Issues](https://github.com/farukada/langgraph-aws-agent-core-ts/issues)
- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
- [AWS Bedrock Agent Core Documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/agents.html)