Base Tools
Base tools are built-in tools that enable memory management, user communication, and access to conversation history and archival storage.
Available Base Tools
Section titled “Available Base Tools”| Tool | Purpose |
|---|---|
memory_insert | Insert text into a memory block |
memory_replace | Replace specific text in a memory block |
memory_rethink | Completely rewrite a memory block |
memory_finish_edits | Signal completion of memory editing |
conversation_search | Search prior conversation history |
archival_memory_insert | Add content to archival memory |
archival_memory_search | Search archival memory |
send_message | Send a message to the user (legacy architectures only) |
Memory Block Editing
Section titled “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
Section titled “memory_insert”Insert text at a specific line in a memory block.
Parameters:
label: Which memory block to editnew_str: Text to insertinsert_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
Section titled “memory_replace”Replace specific text in a memory block.
Parameters:
label: Which memory block to editold_str: Exact text to find and replacenew_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
Section titled “memory_rethink”Completely rewrite a memory block’s contents.
Parameters:
label: Which memory block to rewritenew_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
Section titled “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
Section titled “Recall Memory”conversation_search
Section titled “conversation_search”Search prior conversation history using both text matching and semantic similarity.
Parameters:
query: What to search forroles: Optional filter by message role (user, assistant, tool)limit: Maximum number of resultsstart_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
Section titled “Archival Memory”Archival memory stores information long-term outside the context window. See the Archival Memory documentation for details.
archival_memory_insert
Section titled “archival_memory_insert”Add content to archival memory for long-term storage.
Parameters:
content: Text to storetags: 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
archival_memory_search
Section titled “archival_memory_search”Search archival memory using semantic (embedding-based) search.
Parameters:
query: What to search for semanticallytags: Optional tag filterstag_match_mode: “any” or “all” for tag matchingtop_k: Maximum resultsstart_datetime,end_datetime: ISO 8601 filters (inclusive)
Returns: Matching passages with timestamps and content, ordered by semantic similarity.
Deprecated Tools
Section titled “Deprecated Tools”These tools are still available but deprecated:
| Tool | Use Instead |
|---|---|
send_message | Agent responses (no tool needed). See legacy architectures |
core_memory_append | memory_insert with insert_line=-1 |
core_memory_replace | memory_replace |