> ## Documentation Index
> Fetch the complete documentation index at: https://cache-pot.thatdevguy.in/llms.txt
> Use this file to discover all available pages before exploring further.

# REMEMBER and RECALL commands for agent session memory

> REMEMBER stores a key-value pair scoped to a session. RECALL retrieves one or all values for a session. Backed by Cache-Pot hashes.

The `REMEMBER` and `RECALL` commands give AI agents a simple key-value memory store scoped to a named session. Use them to persist facts, user preferences, conversation state, or any structured context that needs to survive across multiple turns or requests. Memory is stored in a Cache-Pot hash at the key `mem:<session>`, so it inherits all standard hash and TTL behavior. These commands are also exposed as native MCP tools, meaning an agent running against Cache-Pot's MCP endpoint can call them directly without writing any Redis client code.

***

### REMEMBER

Stores a value in a session's memory under a named field. If the field already exists, its value is overwritten.

**Syntax:** `REMEMBER session field value`

<ParamField query="session" type="string" required>
  A unique session identifier — for example, a user ID, conversation ID, or request correlation ID. Cache-Pot namespaces all memory for this session under the hash key `mem:<session>`.
</ParamField>

<ParamField query="field" type="string" required>
  The memory key within this session. Use descriptive names like `name`, `last_topic`, or `turn_count` to keep sessions readable.
</ParamField>

<ParamField query="value" type="string" required>
  The value to store. All values are stored as strings; serialize structured data (JSON, etc.) before storing if needed.
</ParamField>

```redis theme={null}
REMEMBER user-42 name "Alice"
# OK
REMEMBER user-42 last_topic "vector databases"
# OK
REMEMBER user-42 turn_count "5"
# OK
```

**Returns:** `OK`.

<Note>
  `REMEMBER session field value` is exactly equivalent to `HSET mem:session field value`. You can mix `REMEMBER` with direct hash commands on the same `mem:<session>` key — they operate on the same underlying data.
</Note>

***

### RECALL

Retrieves memory for a session. Provide a field name to fetch a single value, or omit it to return the entire session as a flat array of field-value pairs.

**Syntax:** `RECALL session [field]`

<ParamField query="session" type="string" required>
  The session identifier to look up.
</ParamField>

<ParamField query="field" type="string">
  Optional. The specific memory field to retrieve. When omitted, all fields and values for the session are returned.
</ParamField>

```redis theme={null}
# Retrieve a single field
RECALL user-42 name
# "Alice"

RECALL user-42 last_topic
# "vector databases"

# Retrieve all fields for a session
RECALL user-42
# 1) "name"
# 2) "Alice"
# 3) "last_topic"
# 4) "vector databases"
# 5) "turn_count"
# 6) "5"

# Field does not exist
RECALL user-42 email
# (nil)
```

**Returns:** A bulk string (the field value) when a field is specified, or `nil` if the field does not exist. Returns a flat array of alternating field names and values when no field is given — identical to the output of `HGETALL mem:<session>`.

<ResponseField name="field value" type="string">
  The stored value for the requested field, or `nil` if the field is not present.
</ResponseField>

<ResponseField name="all fields (no field argument)" type="array">
  A flat array of `[field, value, field, value, ...]` pairs for the entire session. Returns an empty array if the session does not exist.
</ResponseField>

***

## Setting expiry on session memory

Session memory is stored at the standard Cache-Pot key `mem:<session>`. Use the regular expiry commands to set a time-to-live on an entire session — for example, to auto-expire memory after a period of inactivity.

```redis theme={null}
# Expire the session after 24 hours
EXPIRE mem:user-42 86400
# (integer) 1

# Check remaining TTL
TTL mem:user-42
# (integer) 86391

# Remove the TTL to make memory persistent again
PERSIST mem:user-42
# (integer) 1
```

<Tip>
  Set a TTL immediately after creating a session to prevent unbounded memory growth. A 24-hour TTL is a reasonable default for most conversational applications; increase it for long-running agent workflows.
</Tip>

***

## Using hash commands directly

`REMEMBER` and `RECALL` are thin convenience wrappers over the standard hash commands. You can use any hash command directly on `mem:<session>` for operations that `REMEMBER`/`RECALL` don't cover:

```redis theme={null}
# Check how many fields a session has
HLEN mem:user-42
# (integer) 3

# Delete a single field
HDEL mem:user-42 turn_count
# (integer) 1

# Check whether a field exists
HEXISTS mem:user-42 name
# (integer) 1

# Retrieve multiple fields in one round-trip
HMGET mem:user-42 name last_topic
# 1) "Alice"
# 2) "vector databases"
```

<Note>
  Because `REMEMBER` and `RECALL` are sugar over `HSET`/`HGET`/`HGETALL` on `mem:<session>`, any change made through hash commands is immediately visible through `RECALL`, and vice versa.
</Note>