ReasoningMemory API Reference

API for reasoning trace and tool call storage.

Overview

ReasoningMemory records how agents solve problems: reasoning steps, tool calls, and outcomes.

async with MemoryClient(settings) as client:
    # Access via client
    reasoning = client.reasoning

    # Start a reasoning trace
    trace = await reasoning.start_trace(
        session_id="user-123",
        task="Find restaurant recommendations"
    )

Trace Operations

start_trace

Start a new reasoning trace.

trace = await reasoning.start_trace(
    session_id: str,
    task: str,
    triggered_by_message_id: str | None = None,
    metadata: dict[str, Any] | None = None,
)

Parameters

Parameter Type Default Description

session_id

str

required

Session identifier

task

str

required

Task description

triggered_by_message_id

str

None

Message that triggered this trace

metadata

dict

None

Additional metadata

Returns

ReasoningTrace object with generated id.

complete_trace

Complete a reasoning trace with outcome.

trace = await reasoning.complete_trace(
    trace_id: str,
    outcome: str,
    success: bool = True,
)

get_trace

Get a trace by ID.

trace = await reasoning.get_trace(trace_id: str)

get_traces

Get traces for a session.

traces = await reasoning.get_traces(
    session_id: str | None = None,
    limit: int = 50,
)

delete_trace

Delete a trace and its steps.

await reasoning.delete_trace(trace_id: str)

Step Operations

add_step

Add a reasoning step to a trace.

step = await reasoning.add_step(
    trace_id: str,
    thought: str,
    action: str | None = None,
    observation: str | None = None,
)

Parameters

Parameter Type Default Description

trace_id

str

required

Parent trace ID

thought

str

required

Agent’s reasoning/thought

action

str

None

Action taken

observation

str

None

Result observed

get_steps

Get steps for a trace.

steps = await reasoning.get_steps(trace_id: str)

Tool Call Operations

record_tool_call

Record a tool call within a step.

tool_call = await reasoning.record_tool_call(
    step_id: str,
    tool_name: str,
    arguments: dict[str, Any],
    result: Any,
    duration_ms: float | None = None,
    success: bool = True,
    error: str | None = None,
    message_id: str | None = None,
)

Parameters

Parameter Type Default Description

step_id

str

required

Parent step ID

tool_name

str

required

Name of the tool called

arguments

dict

required

Tool arguments

result

Any

required

Tool result

duration_ms

float

None

Execution time in milliseconds

success

bool

True

Whether the call succeeded

error

str

None

Error message if failed

message_id

str

None

Message that triggered the call

get_tool_calls

Get tool calls for a step.

tool_calls = await reasoning.get_tool_calls(step_id: str)

Search Operations

search_traces

Semantic search for similar reasoning traces.

results = await reasoning.search_traces(
    query: str,
    session_id: str | None = None,
    limit: int = 10,
    min_score: float = 0.0,
)

Returns

List of (ReasoningTrace, score) tuples.

find_similar_traces

Find traces similar to a given trace.

similar = await reasoning.find_similar_traces(
    trace_id: str,
    limit: int = 5,
)

Statistics

get_tool_stats

Get tool usage statistics.

stats = await reasoning.get_tool_stats(
    session_id: str | None = None,
)

Returns

{
    "search_api": {"calls": 42, "successes": 40, "failures": 2, "avg_duration_ms": 150.5},
    "weather_tool": {"calls": 10, "successes": 10, "failures": 0, "avg_duration_ms": 80.2},
    ...
}

Message Linking

link_trace_to_message

Link an existing trace to a message.

await reasoning.link_trace_to_message(
    trace_id: str,
    message_id: str,
)

Creates an INITIATED_BY relationship:

(ReasoningTrace) -[:INITIATED_BY]-> (Message)

Models

ReasoningTrace

@dataclass
class ReasoningTrace:
    id: str
    session_id: str
    task: str
    outcome: str | None
    success: bool | None
    started_at: datetime
    completed_at: datetime | None
    metadata: dict[str, Any]
    embedding: list[float] | None

ReasoningStep

@dataclass
class ReasoningStep:
    id: str
    trace_id: str
    thought: str
    action: str | None
    observation: str | None
    sequence: int
    timestamp: datetime

ToolCall

@dataclass
class ToolCall:
    id: str
    step_id: str
    tool_name: str
    arguments: dict[str, Any]
    result: Any
    duration_ms: float | None
    success: bool
    error: str | None
    timestamp: datetime

Example

async with MemoryClient(settings) as client:
    # Start reasoning trace linked to user message
    trace = await client.reasoning.start_trace(
        session_id="user-123",
        task="Find Italian restaurants nearby",
        triggered_by_message_id=message.id,
    )

    # Add reasoning step
    step = await client.reasoning.add_step(
        trace.id,
        thought="User wants Italian food. I should search for nearby restaurants.",
        action="search_restaurants",
    )

    # Record tool call
    await client.reasoning.record_tool_call(
        step.id,
        tool_name="search_api",
        arguments={"cuisine": "Italian", "location": "nearby"},
        result=[{"name": "La Trattoria", "rating": 4.5}],
        duration_ms=234.5,
    )

    # Complete trace
    await client.reasoning.complete_trace(
        trace.id,
        outcome="Recommended La Trattoria based on high rating",
        success=True,
    )

    # Later: find similar past reasoning
    similar = await client.reasoning.search_traces("restaurant recommendations")
    for trace, score in similar:
        print(f"[{score:.2f}] {trace.task}: {trace.outcome}")

See Also