Skip to content

ant_ai.memory.backends.file

FileMemory pydantic-model

Bases: Memory

Long-term memory kept in one Markdown file, which the agent reads and writes whole.

Unlike Mem0Memory it needs no service: the file can be read and edited by hand, kept in git, and used offline and in tests.

Example
from ant_ai.agent import Agent
from ant_ai.memory.backends.file import FileMemory

agent = Agent(memory=FileMemory(path="./agent_state/MEMORY.md"), ...)

The agent can now call:

- FileMemory_read()
- FileMemory_write(content="# Memory\n\n- The user prefers short answers\n")
Notes

A write replaces the whole memory, so it is refused unless the conversation has read the memory as it is now: a model cannot erase what it has not seen, or undo a change made since it read, by another conversation or by hand. A write longer than max_chars is refused too, asking the model to shorten the memory. The file and its parent directories are created on the first write, and each write replaces the file at once, so a crash never leaves half of it. One file is shared by every conversation and user of the memory, whatever ctx says: give each user their own agent and path when their memories must stay apart. Writes take turns across threads and, on POSIX, processes, by locking the file's directory; an edit by hand during a write is not stopped. Failures raise ToolError, which ToolStep turns into a recoverable ERROR: ... message for the agent.

Show JSON schema:
{
  "description": "Long-term memory kept in one Markdown file, which the agent reads and writes whole.\n\nUnlike `Mem0Memory` it needs no service: the file can be read and edited by\nhand, kept in git, and used offline and in tests.\n\nExample:\n    ```python\n    from ant_ai.agent import Agent\n    from ant_ai.memory.backends.file import FileMemory\n\n    agent = Agent(memory=FileMemory(path=\"./agent_state/MEMORY.md\"), ...)\n    ```\n\n    The agent can now call:\n\n        - FileMemory_read()\n        - FileMemory_write(content=\"# Memory\\n\\n- The user prefers short answers\\n\")\n\nNotes:\n    A write replaces the whole memory, so it is refused unless the\n    conversation has read the memory as it is now: a model cannot erase what\n    it has not seen, or undo a change made since it read, by another\n    conversation or by hand. A write longer than `max_chars` is refused too,\n    asking the model to shorten the memory.\n    The file and its parent directories are created on the first write, and\n    each write replaces the file at once, so a crash never leaves half of it.\n    One file is shared by every conversation and user of the memory, whatever\n    `ctx` says: give each user their own agent and path when their memories\n    must stay apart.\n    Writes take turns across threads and, on POSIX, processes, by locking\n    the file's directory; an edit by hand during a write is not stopped.\n    Failures raise `ToolError`, which `ToolStep` turns into a recoverable\n    `ERROR: ...` message for the agent.",
  "properties": {
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Tool name.",
      "title": "Name"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Tool description. Is used by the LLM to decide whether to call or not the specific tool.",
      "title": "Description"
    },
    "parameters": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The parameters needed by the tool. This is a self-constructed field.",
      "title": "Parameters"
    },
    "path": {
      "description": "The memory file, e.g. `./MEMORY.md`.",
      "format": "path",
      "title": "Path",
      "type": "string"
    },
    "max_chars": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": 10000,
      "description": "Longest memory `write` accepts, or None for no limit.",
      "title": "Max Chars"
    }
  },
  "required": [
    "path"
  ],
  "title": "FileMemory",
  "type": "object"
}

Fields:

Validators:

  • _set_defaults
Source code in src/ant_ai/memory/backends/file.py
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
class FileMemory(Memory):
    """
    Long-term memory kept in one Markdown file, which the agent reads and writes whole.

    Unlike `Mem0Memory` it needs no service: the file can be read and edited by
    hand, kept in git, and used offline and in tests.

    Example:
        ```python
        from ant_ai.agent import Agent
        from ant_ai.memory.backends.file import FileMemory

        agent = Agent(memory=FileMemory(path="./agent_state/MEMORY.md"), ...)
        ```

        The agent can now call:

            - FileMemory_read()
            - FileMemory_write(content="# Memory\\n\\n- The user prefers short answers\\n")

    Notes:
        A write replaces the whole memory, so it is refused unless the
        conversation has read the memory as it is now: a model cannot erase what
        it has not seen, or undo a change made since it read, by another
        conversation or by hand. A write longer than `max_chars` is refused too,
        asking the model to shorten the memory.
        The file and its parent directories are created on the first write, and
        each write replaces the file at once, so a crash never leaves half of it.
        One file is shared by every conversation and user of the memory, whatever
        `ctx` says: give each user their own agent and path when their memories
        must stay apart.
        Writes take turns across threads and, on POSIX, processes, by locking
        the file's directory; an edit by hand during a write is not stopped.
        Failures raise `ToolError`, which `ToolStep` turns into a recoverable
        `ERROR: ...` message for the agent.
    """

    path: Path = Field(description="The memory file, e.g. `./MEMORY.md`.")
    max_chars: int | None = Field(
        default=10_000,
        ge=1,
        description="Longest memory `write` accepts, or None for no limit.",
    )
    # Per conversation, the digest of the memory as it last read or wrote it.
    _seen: dict[tuple[str | None, str], str] = PrivateAttr(default_factory=dict)

    def read(self, ctx: InvocationContext | None = None) -> str:
        """Read your long-term memory: what was saved in earlier conversations. Call it at the start of a conversation, and before answering anything that may depend on what you already know about the user or the task."""
        text: str = self._read() or ""
        self._remember(ctx, text)
        return text if text.strip() else _EMPTY

    def write(self, content: str, ctx: InvocationContext | None = None) -> str:
        """Replace your whole long-term memory with `content` (Markdown); read it first. To save a new fact, write the memory with the fact added; to forget one, write it without. Save durable facts (preferences, decisions, explicit "remember this" requests) as soon as you learn them, and keep the memory short."""
        if self.max_chars is not None and len(content) > self.max_chars:
            raise ToolError(
                f"memory is {len(content)} characters, over the limit of {self.max_chars}: "
                "shorten it, merging or dropping the least useful entries, and write it again"
            )
        try:
            with lock_dir(self.path):
                current: str | None = self._read()
                seen: str | None = self._seen.get(_conversation(ctx))
                # Only a first write, to a memory nobody has read, needs no read;
                # a missing file counts as empty, so a deleted memory is not restored.
                if (current is not None or seen is not None) and seen != _digest(
                    current or ""
                ):
                    raise ToolError(
                        "the memory has changed since you last read it: read it, then write it again with your changes"
                    )
                self._write(content)
                self._remember(ctx, content)
        except OSError as e:
            raise ToolError(f"{e.strerror or e}: {self.path}") from e
        return "Memory saved." if content.strip() else "Memory cleared."

    def _remember(self, ctx: InvocationContext | None, text: str) -> None:
        """Note that this conversation has seen `text`, forgetting the oldest one over the limit."""
        conversation: tuple[str | None, str] = _conversation(ctx)
        self._seen.pop(conversation, None)
        self._seen[conversation] = _digest(text)
        if len(self._seen) > _MAX_SESSIONS:
            del self._seen[next(iter(self._seen))]

    def _read(self) -> str | None:
        """The memory file as text, or None if there is none yet."""
        try:
            return self.path.read_text(encoding="utf-8")
        except FileNotFoundError:
            return None
        except UnicodeDecodeError as e:
            raise ToolError(f"memory file is not UTF-8 text: {self.path}") from e
        except OSError as e:
            raise ToolError(f"{e.strerror or e}: {self.path}") from e

    def _write(self, text: str) -> None:
        """Replace the memory file with `text`, raising `ToolError` on failure."""
        try:
            write_atomic(self.path, text)
        except OSError as e:
            raise ToolError(f"{e.strerror or e}: {self.path}") from e

path pydantic-field

path: Path

The memory file, e.g. ./MEMORY.md.

max_chars pydantic-field

max_chars: int | None = 10000

Longest memory write accepts, or None for no limit.

read

read(ctx: InvocationContext | None = None) -> str

Read your long-term memory: what was saved in earlier conversations. Call it at the start of a conversation, and before answering anything that may depend on what you already know about the user or the task.

Source code in src/ant_ai/memory/backends/file.py
73
74
75
76
77
def read(self, ctx: InvocationContext | None = None) -> str:
    """Read your long-term memory: what was saved in earlier conversations. Call it at the start of a conversation, and before answering anything that may depend on what you already know about the user or the task."""
    text: str = self._read() or ""
    self._remember(ctx, text)
    return text if text.strip() else _EMPTY

write

write(
    content: str, ctx: InvocationContext | None = None
) -> str

Replace your whole long-term memory with content (Markdown); read it first. To save a new fact, write the memory with the fact added; to forget one, write it without. Save durable facts (preferences, decisions, explicit "remember this" requests) as soon as you learn them, and keep the memory short.

Source code in src/ant_ai/memory/backends/file.py
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def write(self, content: str, ctx: InvocationContext | None = None) -> str:
    """Replace your whole long-term memory with `content` (Markdown); read it first. To save a new fact, write the memory with the fact added; to forget one, write it without. Save durable facts (preferences, decisions, explicit "remember this" requests) as soon as you learn them, and keep the memory short."""
    if self.max_chars is not None and len(content) > self.max_chars:
        raise ToolError(
            f"memory is {len(content)} characters, over the limit of {self.max_chars}: "
            "shorten it, merging or dropping the least useful entries, and write it again"
        )
    try:
        with lock_dir(self.path):
            current: str | None = self._read()
            seen: str | None = self._seen.get(_conversation(ctx))
            # Only a first write, to a memory nobody has read, needs no read;
            # a missing file counts as empty, so a deleted memory is not restored.
            if (current is not None or seen is not None) and seen != _digest(
                current or ""
            ):
                raise ToolError(
                    "the memory has changed since you last read it: read it, then write it again with your changes"
                )
            self._write(content)
            self._remember(ctx, content)
    except OSError as e:
        raise ToolError(f"{e.strerror or e}: {self.path}") from e
    return "Memory saved." if content.strip() else "Memory cleared."