basic-memory

Instructions

Implementation Reference

• src/basic_memory/mcp/tools/list_directory.py:15-169 (handler)

  The primary handler for the 'list_directory' MCP tool. This async function, decorated with @mcp.tool(), handles the tool execution: resolves the project context, calls the /directory/list API endpoint with parameters, processes the response nodes, and formats a user-friendly directory listing grouped by directories and files with metadata.

  @mcp.tool(
      description="List directory contents with filtering and depth control.",
  )
  async def list_directory(
      dir_name: str = "/",
      depth: int = 1,
      file_name_glob: Optional[str] = None,
      project: Optional[str] = None,
      context: Context | None = None,
  ) -> str:
      """List directory contents from the knowledge base with optional filtering.
  
      This tool provides 'ls' functionality for browsing the knowledge base directory structure.
      It can list immediate children or recursively explore subdirectories with depth control,
      and supports glob pattern filtering for finding specific files.
  
      Args:
          dir_name: Directory path to list (default: root "/")
                   Examples: "/", "/projects", "/research/ml"
          depth: Recursion depth (1-10, default: 1 for immediate children only)
                 Higher values show subdirectory contents recursively
          file_name_glob: Optional glob pattern for filtering file names
                         Examples: "*.md", "*meeting*", "project_*"
          project: Project name to list directory from. Optional - server will resolve using hierarchy.
                  If unknown, use list_memory_projects() to discover available projects.
          context: Optional FastMCP context for performance caching.
  
      Returns:
          Formatted listing of directory contents with file metadata
  
      Examples:
          # List root directory contents
          list_directory()
  
          # List specific folder
          list_directory(dir_name="/projects")
  
          # Find all markdown files
          list_directory(file_name_glob="*.md")
  
          # Deep exploration of research folder
          list_directory(dir_name="/research", depth=3)
  
          # Find meeting notes in projects folder
          list_directory(dir_name="/projects", file_name_glob="*meeting*")
  
          # Explicit project specification
          list_directory(project="work-docs", dir_name="/projects")
  
      Raises:
          ToolError: If project doesn't exist or directory path is invalid
      """
      track_mcp_tool("list_directory")
      async with get_client() as client:
          active_project = await get_active_project(client, project, context)
  
          # Prepare query parameters
          params = {
              "dir_name": dir_name,
              "depth": str(depth),
          }
          if file_name_glob:
              params["file_name_glob"] = file_name_glob
  
          logger.debug(
              f"Listing directory '{dir_name}' in project {project} with depth={depth}, glob='{file_name_glob}'"
          )
  
          # Call the API endpoint
          response = await call_get(
              client,
              f"/v2/projects/{active_project.external_id}/directory/list",
              params=params,
          )
  
          nodes = response.json()
  
          if not nodes:
              filter_desc = ""
              if file_name_glob:
                  filter_desc = f" matching '{file_name_glob}'"
              return f"No files found in directory '{dir_name}'{filter_desc}"
  
          # Format the results
          output_lines = []
          if file_name_glob:
              output_lines.append(
                  f"Files in '{dir_name}' matching '{file_name_glob}' (depth {depth}):"
              )
          else:
              output_lines.append(f"Contents of '{dir_name}' (depth {depth}):")
          output_lines.append("")
  
          # Group by type and sort
          directories = [n for n in nodes if n["type"] == "directory"]
          files = [n for n in nodes if n["type"] == "file"]
  
          # Sort by name
          directories.sort(key=lambda x: x["name"])
          files.sort(key=lambda x: x["name"])
  
          # Display directories first
          for node in directories:
              path_display = node["directory_path"]
              output_lines.append(f"📁 {node['name']:<30} {path_display}")
  
          # Add separator if we have both directories and files
          if directories and files:
              output_lines.append("")
  
          # Display files with metadata
          for node in files:
              path_display = node["directory_path"]
              title = node.get("title", "")
              updated = node.get("updated_at", "")
  
              # Remove leading slash if present, requesting the file via read_note does not use the beginning slash'
              if path_display.startswith("/"):
                  path_display = path_display[1:]
  
              # Format date if available
              date_str = ""
              if updated:
                  try:
                      from datetime import datetime
  
                      dt = datetime.fromisoformat(updated.replace("Z", "+00:00"))
                      date_str = dt.strftime("%Y-%m-%d")
                  except Exception:  # pragma: no cover
                      date_str = updated[:10] if len(updated) >= 10 else ""
  
              # Create formatted line
              file_line = f"📄 {node['name']:<30} {path_display}"
              if title and title != node["name"]:
                  file_line += f" | {title}"
              if date_str:
                  file_line += f" | {date_str}"
  
              output_lines.append(file_line)
  
          # Add summary
          output_lines.append("")
          total_count = len(directories) + len(files)
          summary_parts = []
          if directories:
              summary_parts.append(
                  f"{len(directories)} director{'y' if len(directories) == 1 else 'ies'}"
              )
          if files:
              summary_parts.append(f"{len(files)} file{'s' if len(files) != 1 else ''}")
  
          output_lines.append(f"Total: {total_count} items ({', '.join(summary_parts)})")
  
          return "\n".join(output_lines)

• src/basic_memory/mcp/tools/__init__.py:18-18 (registration)

  The import statement in the tools package __init__.py that loads the list_directory.py module. This executes the module's code, including the @mcp.tool() decorator on the handler function, thereby registering the 'list_directory' tool with the global MCP server instance.

  from basic_memory.mcp.tools.list_directory import list_directory