> ## 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.

# Agent memory: persistent key-value state for AI sessions

> REMEMBER and RECALL give AI agents a simple key-value memory scoped to a session, backed by Cache-Pot's hash store with optional TTL.

AI agents need a place to store what they've learned during a conversation — the user's name, their preferences, the last topic discussed — and retrieve it on the next turn without passing the entire history through the context window. Cache-Pot's `REMEMBER` and `RECALL` commands provide session-scoped key-value memory built directly into the store. Because it's backed by Cache-Pot's native hash type, you get persistence across restarts, optional TTL-based expiry, and direct hash access — all without any extra infrastructure.

***

## How agent memory works

<Steps>
  <Step title="Store a fact">
    Call `REMEMBER` with a session identifier, a field name, and the value. Cache-Pot writes the field into a hash at the key `mem:<session>`.

    ```bash theme={null}
    REMEMBER user-123 name "Alice"
    REMEMBER user-123 last_topic "vector databases"
    ```
  </Step>

  <Step title="Retrieve a specific field">
    Call `RECALL` with the session and field name to get a single value.

    ```bash theme={null}
    RECALL user-123 name         # "Alice"
    RECALL user-123 last_topic   # "vector databases"
    ```
  </Step>

  <Step title="Retrieve the whole session">
    Omit the field argument to get all stored fields and values for the session.

    ```bash theme={null}
    RECALL user-123
    # 1) "name" 2) "Alice" 3) "last_topic" 4) "vector databases"
    ```
  </Step>
</Steps>

<Info>
  `REMEMBER session field value` is equivalent to `HSET mem:session field value`, and `RECALL session` is equivalent to `HGETALL mem:session`. You can use hash commands directly on `mem:<session>` if you need finer control.
</Info>

***

## Basic example

```bash theme={null}
REMEMBER user-123 name "Alice"
REMEMBER user-123 last_topic "vector databases"
REMEMBER user-123 language "English"

RECALL user-123 name           # "Alice"
RECALL user-123 last_topic     # "vector databases"
RECALL user-123                # all fields: name, last_topic, language
```

***

## Setting TTL on agent memory

Sessions are persistent by default. Use `EXPIRE` on the underlying `mem:<session>` key to make a session expire automatically:

```bash theme={null}
REMEMBER user-123 name "Alice"
EXPIRE mem:user-123 3600       # entire session expires in 1 hour

TTL mem:user-123               # seconds remaining
PERSIST mem:user-123           # remove the TTL if you change your mind
```

<Tip>
  Use `EXPIRE` on a session after every interaction to implement a sliding inactivity timeout — each new `REMEMBER` call refreshes the window.
</Tip>

***

## Multi-agent example

The snippet below shows an agent storing context during one turn and reading it back on a subsequent turn, using the standard `redis-py` client.

<CodeGroup>
  ```python Python (redis-py) theme={null}
  import redis

  r = redis.Redis(host='localhost', port=6379)

  session = 'agent-session-abc'

  # Turn 1: store what the agent learned
  r.execute_command('REMEMBER', session, 'user_preference', 'concise answers')
  r.execute_command('REMEMBER', session, 'last_query', 'explain transformers')

  # Set a 2-hour inactivity TTL
  r.expire(f'mem:{session}', 7200)

  # Turn 2 (same or different process): recall context
  pref = r.execute_command('RECALL', session, 'user_preference')
  print(pref)   # b'concise answers'

  last_q = r.execute_command('RECALL', session, 'last_query')
  print(last_q) # b'explain transformers'

  # Recall everything the agent knows about this session
  all_mem = r.execute_command('RECALL', session)
  print(all_mem)
  # [b'user_preference', b'concise answers', b'last_query', b'explain transformers']
  ```

  ```python Python — update a field theme={null}
  import redis

  r = redis.Redis(host='localhost', port=6379)
  session = 'agent-session-abc'

  # Overwrite an existing field
  r.execute_command('REMEMBER', session, 'last_query', 'how does HNSW work?')

  # Confirm the update
  print(r.execute_command('RECALL', session, 'last_query'))
  # b'how does HNSW work?'
  ```
</CodeGroup>

***

## Using via MCP

Agent memory is also accessible from Cache-Pot's built-in MCP server. AI frameworks that support the Model Context Protocol can call the `remember` and `recall` tools directly — no Redis client required.

| MCP Tool   | Maps to                      | Description                               |
| ---------- | ---------------------------- | ----------------------------------------- |
| `remember` | `REMEMBER session key value` | Store a fact in the session namespace.    |
| `recall`   | `RECALL session [key]`       | Retrieve one field or the entire session. |

See the MCP integration guide for setup instructions and a full list of available tools.

<Tip>
  Use descriptive, collision-resistant session names such as `user-<uuid>` or `conversation-<uuid>`. Because all session hashes share the same keyspace under the `mem:` prefix, a predictable naming scheme prevents one session from accidentally overwriting another.
</Tip>