basic-memory

Instructions

Implementation Reference

• src/basic_memory/mcp/tools/read_content.py:151-272 (handler)

  The main execution handler for the 'read_content' MCP tool. Reads file content from project paths or memory URLs, supports text, optimized images, and small binaries. Returns structured data based on content type.
  @mcp.tool(description="Read a file's raw content by path or permalink") async def read_content( path: str, project: Optional[str] = None, context: Context | None = None ) -> dict: """Read a file's raw content by path or permalink. This tool provides direct access to file content in the knowledge base, handling different file types appropriately. Uses stateless architecture - project parameter optional with server resolution. Supported file types: - Text files (markdown, code, etc.) are returned as plain text - Images are automatically resized/optimized for display - Other binary files are returned as base64 if below size limits Args: path: The path or permalink to the file. Can be: - A regular file path (docs/example.md) - A memory URL (memory://docs/example) - A permalink (docs/example) project: Project name to read 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: A dictionary with the file content and metadata: - For text: {"type": "text", "text": "content", "content_type": "text/markdown", "encoding": "utf-8"} - For images: {"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": "base64_data"}} - For other files: {"type": "document", "source": {"type": "base64", "media_type": "content_type", "data": "base64_data"}} - For errors: {"type": "error", "error": "error message"} Examples: # Read a markdown file result = await read_content("docs/project-specs.md") # Read an image image_data = await read_content("assets/diagram.png") # Read using memory URL content = await read_content("memory://docs/architecture") # Read configuration file config = await read_content("config/settings.json") # Explicit project specification result = await read_content("docs/project-specs.md", project="my-project") Raises: HTTPError: If project doesn't exist or is inaccessible SecurityError: If path attempts path traversal """ logger.info("Reading file", path=path, project=project) async with get_client() as client: active_project = await get_active_project(client, project, context) project_url = active_project.project_url url = memory_url_path(path) # Validate path to prevent path traversal attacks project_path = active_project.home if not validate_project_path(url, project_path): logger.warning( "Attempted path traversal attack blocked", path=path, url=url, project=active_project.name, ) return { "type": "error", "error": f"Path '{path}' is not allowed - paths must stay within project boundaries", } response = await call_get(client, f"{project_url}/resource/{url}") content_type = response.headers.get("content-type", "application/octet-stream") content_length = int(response.headers.get("content-length", 0)) logger.debug("Resource metadata", content_type=content_type, size=content_length, path=path) # Handle text or json if content_type.startswith("text/") or content_type == "application/json": logger.debug("Processing text resource") return { "type": "text", "text": response.text, "content_type": content_type, "encoding": "utf-8", } # Handle images elif content_type.startswith("image/"): logger.debug("Processing image") img = PILImage.open(io.BytesIO(response.content)) img_bytes = optimize_image(img, content_length) return { "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": base64.b64encode(img_bytes).decode("utf-8"), }, } # Handle other file types else: logger.debug(f"Processing binary resource content_type {content_type}") if content_length > 350000: # pragma: no cover logger.warning("Document too large for response", size=content_length) return { "type": "error", "error": f"Document size {content_length} bytes exceeds maximum allowed size", } return { "type": "document", "source": { "type": "base64", "media_type": content_type, "data": base64.b64encode(response.content).decode("utf-8"), }, }
• src/basic_memory/mcp/tools/__init__.py:10-10 (registration)

  Import statement in tools __init__ that loads and registers the read_content tool via its @mcp.tool decorator.
  from basic_memory.mcp.tools.read_content import read_content