Tool Use

Base Tools

Built-in tools for memory management and user communication

Base tools are built-in tools that enable memory management, user communication, and access to conversation history and archival storage.

Available Base Tools

ToolPurpose
memory_insertInsert text into a memory block
memory_replaceReplace specific text in a memory block
memory_rethinkCompletely rewrite a memory block
memory_finish_editsSignal completion of memory editing
conversation_searchSearch prior conversation history
archival_memory_insertAdd content to archival memory
archival_memory_searchSearch archival memory
send_messageSend a message to the user (legacy architectures only)

Memory Block Editing

Memory blocks are editable sections in the agent’s context window. These tools let agents update their own memory.

See the Memory Blocks guide for more about how memory blocks work.

memory_insert

Insert text at a specific line in a memory block.

Parameters:

  • label: Which memory block to edit
  • new_str: Text to insert
  • insert_line: Line number (0 for beginning, -1 for end)

Common uses:

  • Add new information to the end of a block
  • Insert context at the beginning
  • Add items to a list

memory_replace

Replace specific text in a memory block.

Parameters:

  • label: Which memory block to edit
  • old_str: Exact text to find and replace
  • new_str: Replacement text

Common uses:

  • Update outdated information
  • Fix typos or errors
  • Delete text (by replacing with empty string)

Important: The old_str must match exactly, including whitespace. If it appears multiple times, the tool will error.

memory_rethink

Completely rewrite a memory block’s contents.

Parameters:

  • label: Which memory block to rewrite
  • new_memory: Complete new contents

When to use:

  • Condensing cluttered information
  • Major reorganization
  • Combining multiple pieces of information

When not to use:

  • Adding one line (use memory_insert)
  • Changing specific text (use memory_replace)

memory_finish_edits

Signals that memory editing is complete.

Parameters: None

Some agent architectures use this to mark the end of a memory update cycle.

Recall Memory

Search prior conversation history using both text matching and semantic similarity.

Parameters:

  • query: What to search for
  • roles: Optional filter by message role (user, assistant, tool)
  • limit: Maximum number of results
  • start_date, end_date: ISO 8601 date/datetime filters (inclusive)

Returns: Matching messages with role and content, ordered by relevance.

Example queries:

  • “What did the user say about deployment?”
  • “Find previous responses about error handling”
  • “Search tool outputs from last week”

Archival Memory

Archival memory stores information long-term outside the context window. See the Archival Memory documentation for details.

archival_memory_insert

Add content to archival memory for long-term storage.

Parameters:

  • content: Text to store
  • tags: Optional tags for organization

Common uses:

  • Storing reference information for later
  • Saving important context that doesn’t fit in memory blocks
  • Building a knowledge base over time

Search archival memory using semantic (embedding-based) search.

Parameters:

  • query: What to search for semantically
  • tags: Optional tag filters
  • tag_match_mode: “any” or “all” for tag matching
  • top_k: Maximum results
  • start_datetime, end_datetime: ISO 8601 filters (inclusive)

Returns: Matching passages with timestamps and content, ordered by semantic similarity.

Legacy Tools

send_message

Only used by memgpt_v1_agent and memgpt_v2_agent architectures. The newer letta_v1_agent architecture does not use or need this tool.

Sends a message to the user.

Parameters:

  • message: The message text to send

What it does: Displays a message to the user in the conversation.

Deprecated Tools

These tools are still available but deprecated:

ToolUse Instead
core_memory_appendmemory_insert with insert_line=-1
core_memory_replacememory_replace