Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mortemlabs.com/llms.txt

Use this file to discover all available pages before exploring further.

A session represents one complete agent run — one decision cycle, one trade attempt, one strategy evaluation. Every session becomes a trace in the Mortem dashboard with a full chronological replay of everything the agent did. Start a session at the beginning of a run, and close it when the run ends.

​
Start a session

Call mortem.startSession(options) to open a new trace. The method always returns a Session — if session creation fails internally, the SDK returns a no-op session that silently absorbs further calls rather than throwing into your agent code. 
const session = await mortem.startSession({
  inputSummary: "Evaluate whether to swap 1 SOL for JUP at current prices",
  tags: ["swap", "jup", "devnet"],
})

​
SessionOptions

​
inputSummary
string
required
A plain-text description of what the agent is trying to do in this run. This is the first thing visible in the trace list and detail view.
​
tags
string[]
Arbitrary labels attached to the trace. Use these to filter runs by strategy, market, cluster, or any other dimension that matters to your team.
​
traceId
string
Override the auto-generated trace ID. Must be a valid ULID or a string that is unique across your agent’s traces. Useful when you generate correlation IDs upstream and want them to match inside Mortem.
​
agentId
string
Override the client-level agentId for this specific session. Useful when a single process manages multiple logical agents.
​
startedAt
Date
Backfill the session start time. Defaults to new Date() at the moment startSession is called.

​
Wrap agent work with session.run()

Pass your agent’s main logic to session.run(callback). This is the recommended way to structure every run. 
const result = await session.run(async () => {
  // all LLM calls, tool calls, and Solana transactions go here
  return { ok: true }
})
session.run() does three things:
  1. Activates async trace context so that child events from wrapped clients (OpenAI, Solana, etc.) are automatically linked to this session — even across await boundaries.
  2. Calls session.complete() automatically when the callback resolves.
  3. Calls session.fail(error) automatically when the callback throws, then re-throws the error so your own error handling is unaffected.
Without session.run(), you still get a top-level trace, but child events from instrumented wrappers will not be captured. The async context that links LLM calls and tool calls to the active session only exists inside session.run().

​
Close a session manually

If you are not using session.run(), close the session explicitly after the agent’s work is done. Use session.complete() when the run succeeds: 
await session.complete("Swap submitted — signature abc123")
Use session.fail() when the run errors: 
await session.fail(error, "Swap aborted due to slippage check failure")
Use session.end() when you want to set the status explicitly: 
await session.end({
  status: "completed",
  outputSummary: "Position closed at target price",
})

​
Completion methods

​
session.complete
(outputSummary?: string) => Promise<void>
Marks the trace as completed and flushes buffered data. Accepts an optional plain-text description of the outcome.
​
session.fail
(error: unknown, outputSummary?: string) => Promise<void>
Marks the trace as errored, records the error message, and flushes. Accepts any thrown value — Error, string, or unknown.
​
session.end
(options?: SessionEndOptions) => Promise<void>
Generic completion with explicit control over status, outputSummary, and errorMessage. Status defaults to "completed" if not provided.

​
Access the trace ID

Every session exposes its trace ID through session.traceId (an alias for session.id): 
console.log(session.traceId) // "01HZ..."
Use this value to build dashboard URLs, correlate logs, or pass as a traceId override to a downstream session. This is the full pattern from the Mortem README. Use it as your starting point:
agent.ts
import { Mortem } from "@mortemlabs/sdk"

const mortem = new Mortem({
  apiKey: process.env.MORTEM_API_KEY ?? "",
  agentId: process.env.MORTEM_AGENT_ID,
  verifyToken: process.env.MORTEM_VERIFY_TOKEN,
  environment: "devnet",
  ingestUrl: process.env.MORTEM_INGEST_URL,
})

const session = await mortem.startSession({
  inputSummary: "Evaluate a Solana trade setup and optionally submit the swap",
  tags: ["swap", "local-dev"],
})

try {
  const result = await session.run(async () => {
    const planning = session.beginEvent("custom", {
      step: "planning",
    })

    planning.complete({
      payload: {
        step: "planning",
        result: "ready",
      },
    })

    return { ok: true }
  })

  await session.complete("Agent completed successfully")
  console.log(session.traceId, result.ok)
} catch (error) {
  await session.fail(error)
} finally {
  await mortem.close()
}
Session methods — complete, fail, end, and run — are best-effort. Internal failures are swallowed and reported through the optional logger rather than propagating into your agent code. Your bot will not crash because of an SDK error.