search_archival_memory
Find relevant information in an agent's stored memories using semantic search. Filter results by tags, date ranges, and other criteria to retrieve contextually similar passages.
Instructions
Search an agent's archival memory using semantic similarity. Returns passages most similar to the query. Use list_passages for text-based search or pagination, create_passage to add memories.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ID of the agent whose archival memory to search | |
| query | Yes | Search query for semantic similarity matching | |
| tags | No | Optional list of tags to filter passages by | |
| tag_match_mode | No | How to match tags: "any" returns passages with at least one matching tag, "all" requires all tags to match | |
| top_k | No | Maximum number of results to return (default varies by server) | |
| start_datetime | No | Filter passages created after this datetime (ISO 8601 format) | |
| end_datetime | No | Filter passages created before this datetime (ISO 8601 format) | |
| include_embeddings | No | Whether to include the full embedding vectors in the response (default: false) |
Implementation Reference
- The main handler function that implements the search_archival_memory tool logic: validates inputs, constructs API parameters, calls the semantic search endpoint on agent's archival memory, processes results (optionally strips embeddings), and returns JSON-formatted passages.export async function handleSearchArchivalMemory(server, args) { if (!args?.agent_id) { throw new Error('Missing required argument: agent_id'); } if (!args?.query) { throw new Error('Missing required argument: query'); } try { const headers = server.getApiHeaders(); const agentId = encodeURIComponent(args.agent_id); // Construct query parameters const params = { query: args.query, }; if (args.tags) params.tags = args.tags; if (args.tag_match_mode) params.tag_match_mode = args.tag_match_mode; if (args.top_k) params.top_k = args.top_k; if (args.start_datetime) params.start_datetime = args.start_datetime; if (args.end_datetime) params.end_datetime = args.end_datetime; // Use the semantic search endpoint const response = await server.api.get(`/agents/${agentId}/archival-memory/search`, { headers, params, }); // Search endpoint returns {results: [], count: N} let passages = response.data.results || []; // Optionally remove embeddings from the response const includeEmbeddings = args?.include_embeddings ?? false; if (!includeEmbeddings) { passages = passages.map((passage) => { // eslint-disable-next-line no-unused-vars const { embedding, ...rest } = passage; return rest; }); } return { content: [ { type: 'text', text: JSON.stringify({ passages: passages, }), }, ], }; } catch (error) { return server.createErrorResponse(error); } }
- The tool definition object including name, description, and detailed inputSchema with properties, types, descriptions, and required fields for the search_archival_memory tool.export const searchArchivalMemoryDefinition = { name: 'search_archival_memory', description: "Search an agent's archival memory using semantic similarity. Returns passages most similar to the query. Use list_passages for text-based search or pagination, create_passage to add memories.", inputSchema: { type: 'object', properties: { agent_id: { type: 'string', description: 'ID of the agent whose archival memory to search', }, query: { type: 'string', description: 'Search query for semantic similarity matching', }, tags: { type: 'array', items: { type: 'string' }, description: 'Optional list of tags to filter passages by', }, tag_match_mode: { type: 'string', enum: ['any', 'all'], description: 'How to match tags: "any" returns passages with at least one matching tag, "all" requires all tags to match', }, top_k: { type: 'integer', description: 'Maximum number of results to return (default varies by server)', }, start_datetime: { type: 'string', format: 'date-time', description: 'Filter passages created after this datetime (ISO 8601 format)', }, end_datetime: { type: 'string', format: 'date-time', description: 'Filter passages created before this datetime (ISO 8601 format)', }, include_embeddings: { type: 'boolean', description: 'Whether to include the full embedding vectors in the response (default: false)', default: false, }, }, required: ['agent_id', 'query'], }, };
- src/tools/index.js:201-202 (registration)The dispatch case in the central MCP tool call handler (registerToolHandlers) that routes 'search_archival_memory' calls to the specific handleSearchArchivalMemory function.case 'search_archival_memory': return handleSearchArchivalMemory(server, request.params.arguments);
- src/tools/index.js:48-50 (registration)The import statement bringing in the handler and definition from the implementation file.handleSearchArchivalMemory, searchArchivalMemoryDefinition, } from './passages/search-archival-memory.js';
- src/tools/index.js:128-128 (registration)Inclusion of the tool definition in the allTools array used for listing available tools.searchArchivalMemoryDefinition,