LocalFilesystemMemoryTool Class — anthropic-sdk-python Architecture

Architecture documentation for the LocalFilesystemMemoryTool class in basic.py from the anthropic-sdk-python codebase.

Class python

Entity Profile

Dependency Diagram

graph TD
  c2730250_7059_6f44_aa62_71ce88c5a804["LocalFilesystemMemoryTool"]
  d2acad16_3d69_9ffc_b385_3f353b4288f2["BetaAbstractMemoryTool"]
  c2730250_7059_6f44_aa62_71ce88c5a804 -->|extends| d2acad16_3d69_9ffc_b385_3f353b4288f2
  ffd4efa5_68eb_4c4c_51fe_26bc27478a2b["basic.py"]
  c2730250_7059_6f44_aa62_71ce88c5a804 -->|defined in| ffd4efa5_68eb_4c4c_51fe_26bc27478a2b
  e8068c69_82bb_21bc_01f1_c74143fbab89["__init__()"]
  c2730250_7059_6f44_aa62_71ce88c5a804 -->|method| e8068c69_82bb_21bc_01f1_c74143fbab89
  42a84966_de9f_298e_a98d_c527baf8aa0e["_validate_path()"]
  c2730250_7059_6f44_aa62_71ce88c5a804 -->|method| 42a84966_de9f_298e_a98d_c527baf8aa0e
  460f1285_af24_2579_35b7_ffa668dec7e8["view()"]
  c2730250_7059_6f44_aa62_71ce88c5a804 -->|method| 460f1285_af24_2579_35b7_ffa668dec7e8
  13e9cc96_46e7_62d7_b163_144f30ec7903["create()"]
  c2730250_7059_6f44_aa62_71ce88c5a804 -->|method| 13e9cc96_46e7_62d7_b163_144f30ec7903
  d99fe51f_04cf_c035_7ebe_a5ab0468d24f["str_replace()"]
  c2730250_7059_6f44_aa62_71ce88c5a804 -->|method| d99fe51f_04cf_c035_7ebe_a5ab0468d24f
  78edd0c5_3b20_e27e_ccfe_28854eba9ca6["insert()"]
  c2730250_7059_6f44_aa62_71ce88c5a804 -->|method| 78edd0c5_3b20_e27e_ccfe_28854eba9ca6
  9953ad4e_3ee1_dc26_47f7_ab01c3e451fc["delete()"]
  c2730250_7059_6f44_aa62_71ce88c5a804 -->|method| 9953ad4e_3ee1_dc26_47f7_ab01c3e451fc
  844c0a45_b4be_4cdf_b586_46d2b9a05aeb["rename()"]
  c2730250_7059_6f44_aa62_71ce88c5a804 -->|method| 844c0a45_b4be_4cdf_b586_46d2b9a05aeb
  35d60adf_2ecd_644b_1c44_7b4b135ea856["clear_all_memory()"]
  c2730250_7059_6f44_aa62_71ce88c5a804 -->|method| 35d60adf_2ecd_644b_1c44_7b4b135ea856

Relationship Graph

Source Code

examples/memory/basic.py lines 53–190

class LocalFilesystemMemoryTool(BetaAbstractMemoryTool):
    """File-based memory storage implementation for Claude conversations"""

    def __init__(self, base_path: str = "./memory"):
        super().__init__()
        self.base_path = Path(base_path)
        self.memory_root = self.base_path / "memories"
        self.memory_root.mkdir(parents=True, exist_ok=True)

    def _validate_path(self, path: str) -> Path:
        """Validate and resolve memory paths"""
        if not path.startswith("/memories"):
            raise ValueError(f"Path must start with /memories, got: {path}")

        relative_path = path[len("/memories") :].lstrip("/")
        full_path = self.memory_root / relative_path if relative_path else self.memory_root

        try:
            full_path.resolve().relative_to(self.memory_root.resolve())
        except ValueError as e:
            raise ValueError(f"Path {path} would escape /memories directory") from e

        return full_path

    @override
    def view(self, command: BetaMemoryTool20250818ViewCommand) -> str:
        full_path = self._validate_path(command.path)

        if full_path.is_dir():
            items: List[str] = []
            try:
                for item in sorted(full_path.iterdir()):
                    if item.name.startswith("."):
                        continue
                    items.append(f"{item.name}/" if item.is_dir() else item.name)
                return f"Directory: {command.path}" + "\n".join([f"- {item}" for item in items])
            except Exception as e:
                raise RuntimeError(f"Cannot read directory {command.path}: {e}") from e

        elif full_path.is_file():
            try:
                content = full_path.read_text(encoding="utf-8")
                lines = content.splitlines()
                view_range = command.view_range
                if view_range:
                    start_line = max(1, view_range[0]) - 1
                    end_line = len(lines) if view_range[1] == -1 else view_range[1]
                    lines = lines[start_line:end_line]
                    start_num = start_line + 1
                else:
                    start_num = 1

                numbered_lines = [f"{i + start_num:4d}: {line}" for i, line in enumerate(lines)]
                return "\n".join(numbered_lines)
            except Exception as e:
                raise RuntimeError(f"Cannot read file {command.path}: {e}") from e
        else:
            raise RuntimeError(f"Path not found: {command.path}")

    @override
    def create(self, command: BetaMemoryTool20250818CreateCommand) -> str:
        full_path = self._validate_path(command.path)
        full_path.parent.mkdir(parents=True, exist_ok=True)
        full_path.write_text(command.file_text, encoding="utf-8")
        return f"File created successfully at {command.path}"

    @override
    def str_replace(self, command: BetaMemoryTool20250818StrReplaceCommand) -> str:
        full_path = self._validate_path(command.path)

        if not full_path.is_file():
            raise FileNotFoundError(f"File not found: {command.path}")

        content = full_path.read_text(encoding="utf-8")
        count = content.count(command.old_str)
        if count == 0:
            raise ValueError(f"Text not found in {command.path}")
        elif count > 1:
            raise ValueError(f"Text appears {count} times in {command.path}. Must be unique.")

        new_content = content.replace(command.old_str, command.new_str)