# AMEM.EPIS.QUERY

> Query an agent's episodic memory by event type and time range.

URL: https://docs.hotkv.com/commands/amem-epis-query/

```
AMEM.EPIS.QUERY agent_id [TYPE event_type] [FROM timestamp] [TO timestamp] [LIMIT n]
```

- Group: Agent memory
- Complexity: O(N) where N is the number of events in the log
- HotKV Cloud: Performance and Scale plans
- On-Premise: requires the agent-memory license feature

Agent memory gives AI agents four kinds of memory. Episodic memory is an append-only log of timestamped events per agent, which you can query by event type and time range. `AMEM.EPIS.QUERY` returns matching events, oldest first.

## Options

| Option | Effect |
| --- | --- |
| `TYPE event_type` | Only events of this type (exact match). |
| `FROM timestamp` | Only events at or after this time, in nanoseconds since the Unix epoch. |
| `TO timestamp` | Only events at or before this time, in nanoseconds since the Unix epoch. |
| `LIMIT n` | Return at most `n` events, the oldest matching ones. Default `100`. |

Options can be combined in any order.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Always | Array of events. Each event is a flat array: `"type"`, the type, `"content"`, the content, `"metadata"`, the metadata (empty if none), `"timestamp"`, the timestamp as an integer. Empty for an unknown agent. | Same |

Errors:

- `ERR invalid FROM`, `ERR invalid TO` or `ERR invalid LIMIT` if the value is not a valid number (`LIMIT` cannot be negative). The query is not run without the filter.
- `ERR unknown option 'name'` for an option other than `TYPE`, `FROM`, `TO` and `LIMIT`, and `ERR syntax error` if an option has no value.
- `ERR wrong number of arguments for 'amem.epis.query' command` if the argument count is wrong.
- `NOLICENSE agent-memory requires a HotKV license. Contact sales@hotkv.com` if your license does not include the `agent-memory` feature.

## Examples

```
127.0.0.1:6379> AMEM.EPIS.QUERY agent-42 TYPE observation LIMIT 10
1) 1) "type"
   2) "observation"
   3) "content"
   4) "72F and sunny"
   5) "metadata"
   6) "{\"source\":\"weather-api\"}"
   7) "timestamp"
   8) (integer) 1790985600123456789
```

## Compatibility

HotKV-only command. Redis and Valkey have no equivalent.

## See also

[AMEM.EPIS.LOG](https://docs.hotkv.com/commands/amem-epis-log/index.md), [AMEM.EPIS.CLEAR](https://docs.hotkv.com/commands/amem-epis-clear/index.md), [AMEM.EPIS.STATS](https://docs.hotkv.com/commands/amem-epis-stats/index.md), [AI features guide](https://docs.hotkv.com/ai-features/index.md)