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. 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 below and the memory concept page.

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:

axiom memory ls

  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:

axiom memory ls --flow 01JX4Q4VJ4N4CW9V1T08CYJWWG

  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 <session-id> to print the session's full conversation history followed by its extracted semantic memories:

axiom memory show support-thread-42

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

Search a flow's memories#

Run axiom memory search with a required --flow flag and exactly one query argument (quote multi-word queries):

axiom memory search --flow 01JX4Q4VJ4N4CW9V1T08CYJWWG "preferred output format"

  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 <session-id> when a conversation is complete:

axiom memory end support-thread-42

  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):

axiom memory end support-thread-42 --yes

Delete a session or all memory for a flow#

Run axiom memory rm <session-id> to permanently delete one session — its conversation history and its memory entries:

axiom memory rm support-thread-42

  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):

axiom memory rm --flow 01JX4Q4VJ4N4CW9V1T08CYJWWG --all

  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:

# 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 for the full interface and the memory concept page 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).