--- title: "Inspect agent memory" description: "List, inspect, search, close, and delete agent memory sessions for your flows with the axiom memory CLI commands." category: guide surfaces: [cli] related: [concepts/memory, concepts/sandboxing-and-tenancy, getting-started/first-flow, guides/debug-a-flow, reference/sdk/python] last_reviewed: 2026-06-06 --- # Inspect agent memory When a flow's node code uses agent memory (`ax.agent.memory` in the SDK), the platform stores conversation turns and extracted facts per session. The `axiom memory` command group lets you see exactly what a flow has remembered, search it, close sessions to trigger consolidation, and delete data — all from the terminal. ## Prerequisites - The Axiom CLI installed and logged in (`axiom login`) — see [Installation](../getting-started/installation.md). Every `axiom memory` command requires an active login; memory data lives in the Axiom platform, so there is no local state to manage. - A flow whose node code writes agent memory. If you don't have one yet, see [Where agent memory comes from](#where-agent-memory-comes-from) below and the [memory concept page](../concepts/memory.md). You only ever see memory belonging to your own tenant — isolation is enforced by the platform, not by the CLI. ## List flows and sessions that have memory Run `axiom memory ls` with no flags to see every flow that has at least one memory session: ```bash axiom memory ls ``` ```text FLOW ID SESSIONS LAST ACTIVE 01JX4Q4VJ4N4CW9V1T08CYJWWG 2 2026-06-06 14:02:11 UTC ``` The table shows one row per flow with its session count and the most recent activity timestamp (UTC). Sessions written without a flow ID are grouped under `(no flow)`. Add `--flow` to drill into one flow's sessions: ```bash axiom memory ls --flow 01JX4Q4VJ4N4CW9V1T08CYJWWG ``` ```text SESSION ID TURNS LAST ACTIVE support-thread-42 14 2026-06-06 14:02:11 UTC ``` Each row is a session with its conversation turn count. Use the session IDs from this table with `axiom memory show`, `axiom memory end`, and `axiom memory rm`. ## Show a session's conversation and semantic memories Run `axiom memory show ` to print the session's full conversation history followed by its extracted semantic memories: ```bash axiom memory show support-thread-42 ``` ```text • Session support-thread-42 Conversation USER 2026-06-06 14:01:58 UTC What export formats do you support? ASSISTANT 2026-06-06 14:02:11 UTC CSV and JSON are both supported. · 2 turn(s) total Semantic memories TYPE IMPORTANCE CONTENT semantic 0.80 User works with CSV and JSON exports. · 1 entr(ies) found ``` In the conversation section, each turn shows its role (`USER`, `ASSISTANT`, or `TOOL`), a UTC timestamp, and the content. Turns produced by a tool call are prefixed with the tool name in brackets, e.g. `[web-search] ...`. The semantic memories table lists each entry's type (`episodic`, `semantic`, or `procedural`), its importance (a 0–1 weight), and its content (truncated to 80 characters for display). If the section says "No semantic memories yet", the session has history but has not been consolidated — see [Close a session and trigger consolidation](#close-a-session-and-trigger-consolidation). ## Search a flow's memories Run `axiom memory search` with a required `--flow` flag and exactly one query argument (quote multi-word queries): ```bash axiom memory search --flow 01JX4Q4VJ4N4CW9V1T08CYJWWG "preferred output format" ``` ```text CONTENT IMPORTANCE SCORE User works with CSV and JSON exports. 0.80 0.0214 · 1 result(s) — method: hybrid, latency: 42ms ``` The search is hybrid: it combines keyword matching with semantic similarity, so results match on both exact wording and meaning. Each result's `SCORE` combines that query relevance with the entry's importance and recency, so an old low-importance match ranks below a fresh important one. The footer reports the total number of matches, the retrieval method, and the query latency in milliseconds. ## Close a session and trigger consolidation Run `axiom memory end ` when a conversation is complete: ```bash axiom memory end support-thread-42 ``` ```text End session support-thread-42 and trigger consolidation? [y/N] y ✓ Session support-thread-42 ended. Consolidation enqueued. ``` Ending a session enqueues it for consolidation: a background job reads the session's conversation history, extracts durable semantic facts from it, deduplicates them against existing entries, and stores them as flow-scoped semantic memories. Those facts are what `axiom memory show` lists under "Semantic memories" and what `axiom memory search` finds. Two things to know: - **It is non-destructive.** The conversation history remains accessible after the session ends. - **It is asynchronous.** Semantic memories appear once the background job has run, not at the moment the command returns. Pass `--yes` to skip the confirmation prompt (for scripts): ```bash axiom memory end support-thread-42 --yes ``` ## Delete a session or all memory for a flow Run `axiom memory rm ` to permanently delete one session — its conversation history and its memory entries: ```bash axiom memory rm support-thread-42 ``` ```text Permanently delete session support-thread-42? [y/N] y ✓ Deleted session support-thread-42 (14 record(s) removed). ``` To delete every session and memory entry for a flow at once, pass `--flow` together with `--all` (and no session ID): ```bash axiom memory rm --flow 01JX4Q4VJ4N4CW9V1T08CYJWWG --all ``` ```text Permanently delete ALL memory for flow 01JX4Q4VJ4N4CW9V1T08CYJWWG? [y/N] y ✓ Deleted all memory for flow 01JX4Q4VJ4N4CW9V1T08CYJWWG (37 record(s) removed). ``` Deletion is permanent — there is no soft-delete or undo. `--all` requires `--flow`; running `axiom memory rm` with neither a session ID nor `--flow --all` is an error. Both forms ask for confirmation first and report how many records were removed; pass `--yes` to skip the prompt. ## Where agent memory comes from The `axiom memory` commands read data that node code wrote through `AxiomContext`. A node opens a session by ID and appends conversation turns to it — the session ID is whatever string the node chooses, which is why session IDs in `axiom memory ls --flow` output look like your application's identifiers rather than platform-generated ones: ```python # nodes/chat.py — a Python node that writes the memory this guide inspects from gen.messages_pb2 import ChatRequest, ChatReply from gen.axiom_context import AxiomContext async def chat(ax: AxiomContext, input: ChatRequest) -> ChatReply: session = ax.agent.memory.session(input.session_id) await session.history.append(role="user", content=input.text) turns = await session.history.last(20) return ChatReply(reply=f"history has {len(turns)} turn(s)") ``` Beyond `history.append` and `history.last(n)`, node code can store a fact directly with `session.write(content, importance=0.5)`, search with `session.search(query, limit=5)`, and close the session from inside the flow with `session.end()` — the in-code equivalent of `axiom memory end`. See the [Python SDK reference](../reference/sdk/python.md) for the full interface and the [memory concept page](../concepts/memory.md) for how sessions, consolidation, and memory types fit together. By default the CLI sends memory requests to the platform's public API endpoint. Set the `AXIOM_MEMORY_URL` environment variable to point the commands at a different base URL (useful when testing against a local development environment).