---
title: "How to Encrypt LangGraph Checkpoints With MongoDB CSFLE"
description: "LangGraph checkpoints persist agent state, including user messages and tool results, as plaintext BSON in MongoDB by default, leaving sensitive data accessible to anyone who can read the database. MongoDB Client-Side Field Level Encryption (CSFLE) encrypts data on the client before transmission, ensuring the database engine never sees plaintext values and protecting against privileged database users or data breaches. This post demonstrates implementing a custom CipherProtocol for LangGraph’s EncryptedSerializer that uses explicit CSFLE with randomized encryption, configured with AWS KMS and a data encryption key stored in a key vault collection for envelope encryption. The encrypted payload replaces the default Base64 encoding, while only thread IDs, checkpoint IDs, and namespaces remain unencrypted to support runtime lookups without exposing sensitive content. This approach aligns with enterprise security and compliance requirements for customer-facing AI agents, preserving resumable sessions and human-in-the-loop workflows while preventing database administrators or attackers from reading the state."
---

# How to Encrypt LangGraph Checkpoints With MongoDB CSFLE

[MongoDB](https://yomu.fyi/company/mongodb) · Oct 14, 2026

**Type:** Tutorial

## Summary

LangGraph checkpoints persist agent state, including user messages and tool results, as plaintext BSON in MongoDB by default, leaving sensitive data accessible to anyone who can read the database. MongoDB Client-Side Field Level Encryption (CSFLE) encrypts data on the client before transmission, ensuring the database engine never sees plaintext values and protecting against privileged database users or data breaches. This post demonstrates implementing a custom CipherProtocol for LangGraph’s EncryptedSerializer that uses explicit CSFLE with randomized encryption, configured with AWS KMS and a data encryption key stored in a key vault collection for envelope encryption. The encrypted payload replaces the default Base64 encoding, while only thread IDs, checkpoint IDs, and namespaces remain unencrypted to support runtime lookups without exposing sensitive content. This approach aligns with enterprise security and compliance requirements for customer-facing AI agents, preserving resumable sessions and human-in-the-loop workflows while preventing database administrators or attackers from reading the state.

## Context

LangGraph checkpoints persist agent state at each step, enabling resumption and human-in-the-loop workflows. These checkpoints can contain sensitive user messages, tool results, and other confidential details. The default MongoDBSaver stores checkpoints as Base64-encoded BSON, which is not encrypted and can be decoded by anyone with database access. MongoDB CSFLE encrypts data client-side before transmission, so encrypted fields are never visible to the database engine, protecting against privileged database users and breaches.

## Approach / What changed

Implement a custom CipherProtocol that uses MongoDB’s explicit CSFLE client to encrypt serialized checkpoint data with randomized encryption before storage via MongoDBSaver, and decrypt it on retrieval. The handler reads connection string, key vault namespace, and data encryption key alternate name from environment variables. It initializes a ClientEncryption object configured with AWS KMS for key management. The CipherProtocol adapter receives serialized bytes from LangGraph’s EncryptedSerializer and returns ciphertext, or vice versa. The example uses explicit CSFLE, allowing adaptation to other KMS providers.

## Takeaways

- LangGraph checkpoints contain sensitive agent state including user messages and tool results; storing them as Base64 BSON leaves them unprotected against database readers with access to the storage.
- MongoDB CSFLE encrypts data on the client before transmission, so encrypted field values are never visible to the database engine, even to privileged users or during a breach.
- LangGraph’s EncryptedSerializer supports a custom CipherProtocol, allowing integration with CSFLE for production-ready checkpoint encryption with KMS-backed key management.

## FAQ

### What encryption algorithms does CSFLE support for checkpoint payloads?

CSFLE supports deterministic and randomized encryption. Since the serialized checkpoint is an opaque value not used for query filtering, the post uses randomized encryption for stronger confidentiality. Deterministic encryption would support equality queries but could reveal frequency patterns.

### Does encrypting checkpoint payloads affect how I query threads?

Yes, the encrypted payload becomes ciphertext and cannot be used as a query filter. Thread IDs, checkpoint IDs, and namespaces remain visible and queryable, so you must avoid embedding PII in the thread\_id field.

### Can I use a key provider other than AWS KMS?

Yes. The example uses AWS KMS, but the post notes you can adapt the configuration for Azure Key Vault, Google Cloud KMS, or KMIP by following the provider-specific PyMongo configuration.

**Tags:** [AI Agents](https://yomu.fyi/topic/ai-agents), [Encryption](https://yomu.fyi/topic/encryption), [LangGraph](https://yomu.fyi/topic/langgraph), [MongoDB](https://yomu.fyi/topic/mongodb), [Security](https://yomu.fyi/topic/security)

- Source: [MongoDB](https://www.mongodb.com/company/blog/technical/how-to-encrypt-langgraph-checkpoints-csfle)
- Source URL: https://www.mongodb.com/company/blog/technical/how-to-encrypt-langgraph-checkpoints-csfle
- Ingested by Yomu: 2026-10-15T15:00:20.487Z

[Read original post](https://www.mongodb.com/company/blog/technical/how-to-encrypt-langgraph-checkpoints-csfle)