MCP Memento

Instructions

Implementation Reference

• src/memento/tools/search_tools.py:210-280 (handler)

  The handler function for the `contextual_memento_search` tool, which performs a two-phase scoped search.

  async def handle_contextual_memento_search(
      memory_db: SQLiteMemoryDatabase, arguments: Dict[str, Any]
  ) -> CallToolResult:
      """Handle contextual_search tool call.
  
      Search only within the context of a given memory by first finding
      all related memories, then searching only within that related set.
      This provides semantic scoping without embeddings.
  
      Args:
          memory_db: Database instance for memory operations
          arguments: Tool arguments from MCP call containing:
              - memory_id: ID of memory to use as context root (required)
              - query: Text search query (required)
              - max_depth: Maximum relationship traversal depth (default: 2)
  
      Returns:
          CallToolResult with scoped search results or error message
      """
      # Validate input arguments
      validate_search_input(arguments)
  
      # Validate required parameters
      if "memory_id" not in arguments:
          return CallToolResult(
              content=[
                  TextContent(
                      type="text", text="Error: 'memory_id' parameter is required"
                  )
              ],
              isError=True,
          )
  
      if "query" not in arguments:
          return CallToolResult(
              content=[
                  TextContent(type="text", text="Error: 'query' parameter is required")
              ],
              isError=True,
          )
  
      memory_id: str = arguments["memory_id"]
      query: str = arguments["query"]
      max_depth: int = arguments.get("max_depth", 2)
  
      # Phase 1: Find all memories related to the context memory
      related = await memory_db.get_related_memories(
          memory_id=memory_id,
          relationship_types=None,  # All relationship types
          max_depth=max_depth,
      )
  
      if not related:
          return CallToolResult(
              content=[
                  TextContent(
                      type="text",
                      text=f"No related memories found for context: {memory_id}",
                  )
              ]
          )
  
      # Extract IDs of related memories to scope the search
      related_ids: Set[str] = {mem.id for mem, _ in related}
  
      # Phase 2: Search only within the related memories
      # Get all memories from search, then filter by related IDs
      search_query: SearchQuery = SearchQuery(
          query=query,
          limit=100,  # Get more results to filter
          search_tolerance="normal",

• src/memento/tools/definitions.py:350-375 (schema)

  MCP Tool definition/schema for `contextual_memento_search`.

          Tool(
              name="contextual_memento_search",
              description="""Search only within the context of a given memento (scoped search).
  
  Two-phase process: (1) Find related memories, (2) Search only within that set.
  Provides semantic scoping without embeddings.
  
  WHEN TO USE:
  - Searching within a specific problem context
  - Finding solutions in related knowledge
  - Scoped discovery
  
  HOW TO USE:
  - Specify memory_id (context root)
  - Provide query (search term)
  - Optional: max_depth (default: 2)
  
  RETURNS:
  - Matches found only within related memories
  - Context information
  - No leakage outside context""",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "memory_id": {
                          "type": "string",

• src/memento/tools/registry.py:62-62 (registration)

  Registration of the handler in the tool registry.

  "contextual_memento_search": handle_contextual_memento_search,