{
  "schema_version": 2,
  "id": "develop/ai/context-engine/agent-memory/developer-guide",
  "title": "Redis Agent Memory developer guide",
  "url": "https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/developer-guide/",
  "summary": "Connect an application to Redis Agent Memory and work with session memory and long-term memory through Python, TypeScript, or REST.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-09-11T15:54:40+01:00",
  "page_type": "content",
  "content_hash": "6c0879524e7878c9cd42469ad442fbca457f1d4b14234dcfea21cb6b3425f068",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "Use the Python SDK, TypeScript SDK, or REST API to add session events, retrieve conversation context, create long-term memories, and search for relevant information."
    },
    {
      "id": "integration-workflow",
      "title": "Integration workflow",
      "role": "content",
      "text": "1. Connect to a Redis Agent Memory service with its endpoint, Store ID, and API key.\n1. Add conversation events to session memory.\n1. Retrieve session memory before an agent turn to reconstruct the conversation context.\n1. Search long-term memory for information relevant to the current interaction.\n\nRedis Agent Memory can automatically summarize older session events and extract long-term memories in the background. Applications can also create long-term memories directly."
    },
    {
      "id": "choose-a-client",
      "title": "Choose a client",
      "role": "content",
      "text": "| Client | Use it when | Package and quickstart |\n|:-------|:------------|:-----------------------|\n| Python SDK | Your application or agent uses Python. | Install [`redis-agent-memory`](https://pypi.org/project/redis-agent-memory/) and follow the [Python SDK quickstart](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/python-sdk-quickstart). |\n| TypeScript SDK | Your application or agent uses JavaScript or TypeScript. | Install [`@redis-iris/agent-memory`](https://www.npmjs.com/package/@redis-iris/agent-memory) and follow the [TypeScript SDK quickstart](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/typescript-sdk-quickstart). |\n| REST API | You need language-independent HTTP access or don't want an SDK dependency. | No package required. Follow the [REST API quickstart](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/rest-api-quickstart). |"
    },
    {
      "id": "connect-to-a-redis-agent-memory-service",
      "title": "Connect to a Redis Agent Memory service",
      "role": "content",
      "text": "Every client requires:\n\n* The Redis Agent Memory endpoint.\n* The Store ID.\n* A Redis Agent Memory API key.\n\nThe Python and TypeScript SDKs accept the endpoint, Store ID, and API key when you create the client. When you use the REST API, send the API key as a bearer token and include the Store ID in request paths.\n\nFollow the [Redis Cloud setup guide](https://redis.io/docs/latest/operate/iris/agent-memory/create-service) if you don't have a service. After you create one, copy its endpoint and Store ID from the **Configuration** tab and save the API key securely."
    },
    {
      "id": "identify-users-and-conversations",
      "title": "Identify users and conversations",
      "role": "content",
      "text": "| Identifier | Purpose |\n|:-----------|:--------|\n| `sessionId` | Identifies a conversation or interaction session. |\n| `actorId` | Identifies the actor that produced a session event. |\n| `ownerId` | Identifies the user or entity associated with a long-term memory. |\n| Memory ID | Uniquely identifies a long-term memory within the store. |\n\nAn application can use the same user identifier for `actorId` and `ownerId`, but the fields describe different relationships."
    },
    {
      "id": "work-with-session-memory",
      "title": "Work with session memory",
      "role": "content",
      "text": "Use a stable `sessionId` to store a conversation as an ordered sequence of events. Add an event for each user, assistant, or system message that your application needs to retain.\n\nEach stored event can include:\n\n| Field | Purpose |\n|:------|:--------|\n| `eventId` | Server-generated identifier for the event. |\n| `sessionId` | Session that contains the event. |\n| `actorId` | User, agent, or other actor that produced the event. |\n| `role` | Role of the message in the conversation. |\n| `content` | Message content, including its text. |\n| `createdAt` | Time the event occurred in the application. |\n| `systemTimestamp` | Time Redis Agent Memory stored the event. |\n| `metadata` | Optional application-specific information associated with the event. |\n\nBefore an agent turn, retrieve the session by `sessionId` and provide the relevant events to the agent. This lets the application reconstruct the conversation without maintaining a separate conversation store."
    },
    {
      "id": "session-retention",
      "title": "Session retention",
      "role": "content",
      "text": "The session-memory TTL controls how long sessions remain available. Configure it according to the retention requirements of your application. When a session expires, its events are no longer available through session-memory retrieval.\n\nSee [memory configuration](https://redis.io/docs/latest/operate/iris/agent-memory/create-service#memory-configuration) to configure the session-memory TTL in Redis Cloud."
    },
    {
      "id": "automatic-session-summarization",
      "title": "Automatic session summarization",
      "role": "content",
      "text": "Automatic summarization limits the amount of conversation history that must be added to a model's context window. Configure:\n\n* **Summarize after:** The number of messages a session can contain before older messages are summarized.\n* **Keep most recent:** The number of recent messages that remain available in full.\n\nFor example, with **Summarize after** set to 20 and **Keep most recent** set to 10, Redis Agent Memory summarizes the older 10 messages when the session reaches 20 messages and retains the 10 most recent messages in full.\n\nSee [automatic summarization](https://redis.io/docs/latest/operate/iris/agent-memory/create-service#automatic-summarization) to enable summarization and configure both thresholds in Redis Cloud.\n\nFollow any of the client quickstarts to add and retrieve a session event. For complete schemas, see the [session-memory API reference](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/api-reference#tag/session-memory)."
    },
    {
      "id": "work-with-long-term-memory",
      "title": "Work with long-term memory",
      "role": "content",
      "text": "Long-term memory stores information that remains useful beyond one conversation. A long-term memory record includes content and fields that let applications classify, scope, and retrieve it:\n\n| Field | Purpose |\n|:------|:--------|\n| `id` | Unique identifier for the memory. |\n| `text` | Memory content used for retrieval. |\n| `memoryType` | Built-in or custom memory type. |\n| `sessionId` | Session associated with the memory. |\n| `ownerId` | User or entity associated with the memory. |\n| `namespace` | Logical grouping for the memory. |\n| `topics` | Topic tags used to categorize the memory. |\n| `createdAt` | Time the memory was created. |\n| `updatedAt` | Time the memory was last updated. |"
    },
    {
      "id": "create-long-term-memories",
      "title": "Create long-term memories",
      "role": "content",
      "text": "Redis Agent Memory provides two creation paths:\n\n* **Automatic extraction:** Redis Agent Memory processes session events asynchronously and creates durable memories from relevant information. Configure the extraction cadence to control how often session events are processed.\n* **Direct creation:** Your application creates one or more long-term memories through the API or an SDK. Use direct creation when importing existing information or when your application determines exactly what to store.\n\nConfigure the long-term-memory TTL separately from the session-memory TTL.\n\nSee [memory configuration](https://redis.io/docs/latest/operate/iris/agent-memory/create-service#memory-configuration) to configure the extraction cadence and long-term-memory TTL in Redis Cloud."
    },
    {
      "id": "exclude-sensitive-data-from-automatic-extraction",
      "title": "Exclude sensitive data from automatic extraction",
      "role": "content",
      "text": "Sensitive-data exclusions keep specified information out of long-term memory during automatic extraction. A store's exclusions policy combines three mechanisms that you enable independently:\n\n* **Built-in detectors:** Validated patterns for common identifiers, such as payment card numbers, email addresses, phone numbers, IP addresses, and US Social Security numbers. Select the ones a store should apply.\n* **Custom detectors:** Regular expressions you write yourself, for identifiers specific to your domain such as tenant IDs or internal reference numbers.\n* **Semantic exclusions:** A plain-language exclusion prompt describing what must not be kept, such as passwords, access tokens, recovery codes, payment card information, or booking confirmation codes. Use it for concepts a pattern cannot express.\n\nEvery detector chooses what happens to a memory it matches: redact the matched text and keep the rest, or drop the memory. When a memory matches several detectors that choose different actions, the memory is dropped.\n\nExclusions apply to automatic extraction from session events. They do not apply when an application creates long-term memories directly, and session memory itself is never altered.\n\n> [!WARNING]\n> Detector matches are deterministic, but semantic exclusions are advisory and do not guarantee exclusion. Sensitive session content still reaches the extraction model provider. Use appropriate controls before sending sensitive information to Redis Agent Memory or the model provider.\n\nSee [sensitive-data exclusions](https://redis.io/docs/latest/operate/iris/agent-memory/create-service#sensitive-data-exclusions) to configure the feature in Redis Cloud."
    },
    {
      "id": "search-long-term-memory",
      "title": "Search long-term memory",
      "role": "content",
      "text": "Search long-term memory using semantic, keyword, or hybrid retrieval. Scope results with filters for owners, sessions, namespaces, topics, and memory types.\n\nUse `ownerId` to restrict recall to the relevant user or entity. Add narrower filters when the application needs memories from a particular session, namespace, topic, or memory type.\n\nFor request fields, filter operators, and response schemas, see [`SearchLongTermMemory`](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/api-reference#tag/long-term-memory/operation/SearchLongTermMemory)."
    },
    {
      "id": "define-custom-memory-types",
      "title": "Define custom memory types",
      "role": "content",
      "text": "Custom memory types capture structured information specific to your business domain. Define them in the Redis Agent Memory service configuration with:\n\n| Setting | Purpose |\n|:--------|:--------|\n| **Name** | Unique name used as the memory's `memoryType`. |\n| **Description** | Description of the information represented by the type. |\n| **Extraction prompt** | Instructions that tell Redis Agent Memory when and how to extract the custom memory from session events. |\n| **Enabled** | Controls whether Redis Agent Memory extracts new memories for the type. |\n| **Custom fields** | Structured fields added to memories of this type. |\n\nCustom fields support `str`, `int`, `float`, `bool`, `list[str]`, `list[float]`, and `object`. Each field has a name and description that explain what it captures. Every custom memory also includes the built-in long-term memory fields listed above.\n\nFor example, a travel application could define a `trip_preference` type with these fields:\n\n| Field | Type | Captures |\n|:------|:-----|:---------|\n| `destination` | `str` | City or country the user plans to visit. |\n| `travel_period` | `str` | Dates or period of the trip. |\n| `dietary_requirements` | `list[str]` | Dietary requirements that affect recommendations. |\n\nWhen this type is enabled, Redis Agent Memory can extract a structured `trip_preference` memory from relevant session events. Each enabled custom type processes session events independently.\n\nSee [custom memory types](https://redis.io/docs/latest/operate/iris/agent-memory/create-service#custom-memory-types) for configuration requirements and limits.\n\nFollow any of the client quickstarts to create and search long-term memory. For complete schemas, see the [long-term-memory API reference](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/api-reference#tag/long-term-memory)."
    },
    {
      "id": "references",
      "title": "References",
      "role": "related",
      "text": "* [Python SDK quickstart](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/python-sdk-quickstart)\n* [TypeScript SDK quickstart](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/typescript-sdk-quickstart)\n* [Python SDK reference](https://pypi.org/project/redis-agent-memory/)\n* [TypeScript SDK reference](https://www.npmjs.com/package/@redis-iris/agent-memory)\n* [REST API quickstart](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/rest-api-quickstart)\n* [Redis Agent Memory API reference](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/api-reference)"
    }
  ],
  "examples": []
}