Bộ nhớ

Cung cấp cho tổng đài viên một sổ ghi chép ổn định để họ có thể cập nhật, tìm kiếm và sử dụng lại trong nhiều lần chạy mà không cần tải mọi tệp được lưu trữ vào mỗi lời nhắc.

Mặc dù Pydantic AI Harness có trên các bản phát hành 0.x nhưng API có thể thay đổi giữa các bản phát hành nhỏ; khi đó, cảnh báo ngừng sử dụng và hướng dẫn di chuyển ghi chú phát hành sẽ cho bạn (hoặc người đại diện của bạn) biết chính xác cách nâng cấp. Xem chính sách phiên bản.

Mẫu máy tính xách tay

Bộ nhớ cung cấp cho mỗi agent một sổ ghi chép gồm các tệp Markdown:

• MEMORY.md là cuốn sổ chính. Theo mặc định, một đoạn trích có giới hạn và tên của các tệp khác sẽ được thêm vào yêu cầu hiện tại dưới dạng bối cảnh vai trò người dùng được phân tách.
• Các tệp khác chứa các ghi chú dài hơn hoặc tập trung hơn. Mô hình đọc chúng theo yêu cầu hoặc tìm thấy chúng bằng tìm kiếm văn bản giới hạn.

Mô hình có bốn công cụ:

from pydantic_ai import Agent
from pydantic_ai_harness import Memory
from pydantic_ai_harness.memory import FileStore

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[Memory(FileStore('.agent-memory'))],
    defer_model_check=True,
)

Không gian tên được giải quyết bằng mã ứng dụng, không được cung cấp cho các công cụ. Do đó, mô hình không thể chọn không gian tên của người dùng khác trong lệnh gọi công cụ.

Chế độ và giới hạn tiêm

Tính năng tiêm tự động được bật theo mặc định. Hướng dẫn sử dụng đáng tin cậy vẫn còn trong hướng dẫn mô hình, trong khi bộ nhớ ghi theo mô hình được đính kèm trong <memory> dấu phân cách trong phần vai trò người dùng đối với yêu cầu hiện tại. Cùng với nhau, hướng dẫn, sổ ghi chép chính và danh sách tệp có chung một phạm vi hữu hạn max_tokens ngân sách, ước tính bốn ký tự cho mỗi token. Mặc định là 2.000 token gần đúng. max_lines là một giới hạn bổ sung trên sổ ghi chép chính. Việc đọc phụ trợ bị giới hạn bởi max_memory_sizevà số lượng đường dẫn được yêu cầu được lấy từ ngân sách kịp thời, do đó, khả năng này không bao giờ yêu cầu tệp hoặc danh sách không giới hạn. Nội dung không phù hợp sẽ bị bỏ qua kèm theo lời nhắc hướng dẫn mô hình sử dụng read_memory hoặc search_memory.

Khi nào heading được thiết lập, giống nhau ## {heading} gắn nhãn cho cả hướng dẫn đáng tin cậy và khối bộ nhớ vai trò người dùng.

from pydantic_ai_harness import Memory
from pydantic_ai_harness.memory import FileStore

memory = Memory(
    FileStore('.agent-memory'),
    max_tokens=2_000,
    max_lines=200,
)

Chỉ yêu cầu hiện tại mới giữ lại phần vai trò của người dùng được chèn vào, do đó các bản sao không tích lũy trong lịch sử tin nhắn. Mỗi yêu cầu mô hình sẽ nhận được ảnh chụp nhanh giới hạn mới nhất, bao gồm cả sau write_memory hoặc một bản cập nhật bên ngoài thay đổi MEMORY.md.

Đặt inject_memory=False để biết các lời nhắc về bộ nhớ đệm ổn định hoặc quy trình làm việc lâu bền. Các công cụ vẫn có sẵn và mô hình chỉ có thể tìm nạp bộ nhớ khi cần:

from pydantic_ai_harness import Memory
from pydantic_ai_harness.memory import FileStore

memory = Memory(FileStore('.agent-memory'), inject_memory=False)

Với injection_errors='ignore' (mặc định), lỗi cửa hàng sẽ bỏ qua việc tiêm tự động và phát ra phép đo từ xa an toàn cho nội dung. Các nhịp ghi lại loại phụ trợ và hàm băm của phạm vi đã giải quyết; số lượng bản ghi tiêm thành công và lỗi ghi lại loại ngoại lệ. Họ không ghi lại nội dung bộ nhớ. Đặt injection_errors='raise' khi một lần chạy phải thất bại thay vì tiếp tục mà không có bộ nhớ được thêm vào. Lỗi không gian tên và trình phân giải cửa hàng luôn lan truyền. Lỗi công cụ vẫn được trả về dưới dạng lỗi công cụ; cài đặt này chỉ kiểm soát việc tiêm tự động.

Kiên trì và đồng thời

Hợp đồng cửa hàng bao gồm các đột biến so sánh và hoán đổi lạc quan và tính bình thường. Việc viết dựa trên bản sửa đổi cũ sẽ không thành công do có xung đột thay vì ghi đè lên bản chỉnh sửa đồng thời. Việc phát lại cùng một lần chạy và lệnh gọi công cụ không áp dụng đột biến của nó hai lần; việc sử dụng lại mã định danh hoạt động đó với các đối số khác nhau sẽ tăng lên MemoryOperationConflictError. Những đảm bảo này thuộc về hoạt động đột biến, vì vậy các cửa hàng tùy chỉnh phải triển khai chúng một cách nguyên tử thay vì soạn các lệnh gọi đọc và ghi riêng biệt.

Mỗi MemoryStore.read cuộc gọi bao gồm một hữu hạn max_chars, và mọi list_paths cuộc gọi bao gồm một hữu hạn limit. Một cửa hàng trả về tiền tố giới hạn cộng MemoryFile.truncated=True khi có nhiều nội dung hơn, trong khi phiên bản của nó vẫn đại diện cho tệp hoàn chỉnh. read_memory đánh dấu kết quả bị chặn là bị cắt ngắn. write_memory từ chối nối thêm hoặc chỉnh sửa tệp được cung cấp bên ngoài có kích thước quá lớn vì làm như vậy sẽ lấy được nội dung mới từ việc đọc một phần; trước tiên hãy khắc phục hoặc thay thế nó thông qua cửa hàng hỗ trợ. một phong tục SearchableMemoryStore.search cũng phải tôn vinh max_file_chars cũng như giới hạn kết quả.

from pydantic_ai_harness import Memory
from pydantic_ai_harness.memory import FileStore, SqliteMemoryStore

local_memory = Memory(FileStore('.agent-memory'))
sqlite_memory = Memory(SqliteMemoryStore(database='.agent-memory.db'))

SqliteMemoryStore thay vào đó có thể sử dụng thuộc sở hữu của người gọi sqlite3.Connection. Vì các thao tác chạy ngoài vòng lặp sự kiện nên hãy tạo kết nối đó bằng check_same_thread=False và quản lý vòng đời của nó trong ứng dụng. Kết nối phải được dành riêng cho cửa hàng và không hoạt động khi bắt đầu mọi hoạt động; một cuộc gọi không thành công thay vì cam kết hoặc khôi phục giao dịch của người gọi đang hoạt động.

FileStore giữ cuốn nhật ký ở .memory-store.sqlite3 bên trong gốc của nó. Giữ nó cùng với các tệp Markdown khi sao chép hoặc sao lưu cửa hàng. Chỉnh sửa tệp Markdown ngoài khả năng sẽ thay đổi phiên bản nội dung của nó và có thể tạo ra xung đột với thao tác đã chuẩn bị; nhật ký khôi phục các hoạt động bị gián đoạn giữa quá trình chuẩn bị giao dịch và thay thế hệ thống tập tin.

PostgresMemoryStore chấp nhận người lái xe trung lập PostgresPool giao thức, do đó việc khai thác không yêu cầu trình điều khiển PostgreSQL cụ thể. Cài đặt và quản lý trình điều khiển trong ứng dụng của bạn (ví dụ: uv add asyncpg):

import asyncpg

from pydantic_ai_harness import Memory
from pydantic_ai_harness.memory import PostgresMemoryStore


async def build_memory() -> tuple[Memory[None], asyncpg.Pool]:
    pool = await asyncpg.create_pool('postgres://localhost/app')
    memory = Memory(PostgresMemoryStore(pool))
    return memory, pool

Gọi build_memory trong khi khởi động ứng dụng và đóng nhóm được trả về trong khi tắt máy. Cửa hàng không quản lý nó.

Không gian tên

Sử dụng trình phân giải không gian tên khi một Agent phục vụ nhiều người dùng. Nó chạy một lần mỗi lần chạy từ các phần phụ thuộc đã nhập của bạn và kết quả của nó bị ẩn khỏi lược đồ công cụ đối mặt với mô hình.

from dataclasses import dataclass

from pydantic_ai import Agent
from pydantic_ai_harness import Memory
from pydantic_ai_harness.memory import FileStore


@dataclass
class AppDeps:
    user_id: str


agent = Agent(
    'anthropic:claude-sonnet-4-6',
    deps_type=AppDeps,
    capabilities=[
        Memory(
            FileStore('/var/lib/myapp/memory'),
            namespace=lambda ctx: ctx.deps.user_id,
        )
    ],
    defer_model_check=True,
)

Các điều khiển cách ly không gian tên ghi lại các địa chỉ khả năng. Nó không phải là một hệ thống ủy quyền cho một cửa hàng hỗ trợ tùy chỉnh hoặc chia sẻ. Xác thực danh tính trong các phần phụ thuộc của ứng dụng, hạn chế thông tin xác thực phụ trợ và đảm bảo các cửa hàng tùy chỉnh không thể thoát khỏi vùng tên đã giải quyết.

Nhiều kỷ niệm trên một agent

Một agent có thể mang theo nhiều Memory các khả năng cùng một lúc, ví dụ như sổ ghi chép cá nhân cộng với sổ ghi chép tổ chức dùng chung. Áp dụng ba ràng buộc:

• Cho mỗi trường hợp một sự khác biệt agent_name hoặc namespace. Các khối được chèn được theo dõi theo phạm vi đã phân giải của chúng, do đó, các phiên bản chỉ khác nhau trong cửa hàng của chúng sẽ phân giải cùng một phạm vi và thay thế phần chèn của nhau.
• Tất cả các phiên bản đều xác định tên công cụ giống nhau, vì vậy hãy gói mọi phiên bản trừ một phiên bản trong prefix_tools để giữ cho các lược đồ công cụ khác biệt.
• Đặt điểm khác biệt heading trên mỗi trường hợp để mô hình xem các khối là các phần riêng biệt. agent_name là khóa lưu trữ và không bao giờ xuất hiện trong lời nhắc nên không thể gắn nhãn cho chúng.

from pydantic_ai import Agent
from pydantic_ai_harness import Memory
from pydantic_ai_harness.memory import FileStore

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[
        Memory(FileStore('/var/lib/myapp/memory'), heading='Your notes'),
        Memory(FileStore('/var/lib/myapp/memory'), agent_name='org', heading='Org notes').prefix_tools('org'),
    ],
    defer_model_check=True,
)

Tìm kiếm

search_memory thực hiện tìm kiếm văn bản theo nghĩa đen và luôn áp dụng ba giới hạn:

• max_search_results giới hạn kết quả trả về, mặc định là 10.
• max_search_result_chars giới hạn tên tệp và đoạn văn bản liên quan đến phạm vi kết hợp, mặc định là 4.000 ký tự.
• max_search_files giới hạn số lượng tệp mà quá trình quét dự phòng có thể kiểm tra, mặc định là 1.000.

Các cửa hàng đi kèm thực hiện SearchableMemoryStore. Đối với một cửa hàng tùy chỉnh chỉ thực hiện MemoryStore, search_memory yêu cầu nhiều nhất max_search_files + 1 đường dẫn, quét nhiều nhất max_search_filesvà thực hiện các lần đọc giới hạn. Tính điểm từ vựng chỉ sử dụng từng tên tệp có liên quan đến phạm vi và nội dung giới hạn của nó; không gian tên đối tượng thuê và tên agent không bao giờ ảnh hưởng đến mức độ liên quan. Triển khai giao thức tìm kiếm tùy chọn cho phần phụ trợ được lập chỉ mục hoặc ngữ nghĩa trong khi vẫn duy trì cùng ranh giới đối tượng thuê và giới hạn kết quả. Xếp hạng ngữ nghĩa không được tích hợp sẵn.

Trước khi gửi phụ trợ, các truy vấn được giới hạn ở 1.000 ký tự và 32 thuật ngữ được phân tách bằng khoảng trắng duy nhất. Các thuật ngữ không phân biệt chữ hoa chữ thường được thu gọn để chúng không thể tăng điểm hoặc quét công việc.

Cấu hình

from pydantic_ai_harness import Memory
from pydantic_ai_harness.memory import FileStore

Memory(
    FileStore('.agent-memory'),
    store_resolver=None,               # optional per-run store resolver
    agent_name='main',                 # storage segment inside the namespace; never shown to the model
    heading='',                        # optional heading on guidance and injected content
    namespace='',                      # string or per-run resolver
    inject_memory=True,                # False keeps prompts cache-stable
    max_tokens=2_000,                  # finite approximate total injection budget
    max_lines=200,                     # additional main-notebook line limit
    max_memory_size=65_536,            # per-file read, search, and write boundary
    max_search_results=10,
    max_search_result_chars=4_000,
    max_search_files=1_000,
    injection_errors='ignore',         # or 'raise'
    guidance=None,                     # None uses the default notebook guidance
)

Thông số agent

Đăng ký Memory dưới dạng loại khả năng tùy chỉnh khi xây dựng một agent từ thông số Python:

from pydantic_ai import Agent
from pydantic_ai_harness import Memory

agent = Agent.from_spec(
    {
        'model': 'anthropic:claude-sonnet-4-6',
        'capabilities': [
            {'Memory': {'backend': 'file', 'directory': '.agent-memory'}},
        ],
    },
    custom_capability_types=[Memory],
    defer_model_check=True,
)

Các chương trình phụ trợ có thể tuần tự hóa là memory, filevà sqlite. Không gian tên có thể gọi được và nhóm PostgreSQL trực tiếp phải được định cấu hình bằng Python.

Khả năng tương thích thực thi bền vững

Phần phụ trợ bộ nhớ và phần phụ trợ trạng thái quy trình công việc là độc lập. Quá trình thực thi bền bỉ không làm cho sổ ghi chép trong bộ nhớ tồn tại lâu dài.

An ninh và xuất xứ

Bộ nhớ là nội dung không đáng tin cậy, được ghi theo mô hình và có thể nhập lại các lời nhắc trong tương lai. Việc giữ nó trong một phần vai trò người dùng được phân tách sẽ làm giảm quyền hạn của nó so với các hướng dẫn mô hình, nhưng đây không phải là ranh giới cứng nhắc về việc tiêm dấu nhắc. sử dụng inject_memory=False khi các agent ít tin cậy hơn có thể ghi vào cửa hàng và chỉ hiển thị bộ nhớ thông qua truy xuất do ứng dụng kiểm soát khi cần cách ly mạnh hơn. Không lưu trữ bí mật trừ khi có chương trình phụ trợ, chính sách lưu giữ và kiểm soát quyền truy cập phù hợp. Dọn dẹp nội dung trước khi hiển thị nội dung đó sang một miền tin cậy khác.

Hồ sơ bộ nhớ không mang theo trích dẫn nguồn hoặc xuất xứ đã được xác minh. Nếu một ứng dụng cần các thông tin có thể kiểm tra được, hãy lưu trữ nguồn gốc trong ghi chú hoặc triển khai một lược đồ và repository tùy chỉnh. Đồng thời lạc quan ngăn chặn các cập nhật bị mất; nó không chứng minh rằng một tuyên bố được ghi nhớ là đúng.

Tham chiếu API

• pydantic_ai_harness.memory nguồn
• Khả năng AI của Pydantic
• Móc AI Pydantic

Xuất khẩu mô-đun công khai Memory, MemoryToolset, các cửa hàng được nhóm, các giao thức lưu trữ, các mô hình kết quả tìm kiếm và đột biến cũng như các ngoại lệ xung đột. Nhập chúng từ pydantic_ai_harness.memory.

::: pydantic_ai_harness.memory.Memory

::: pydantic_ai_harness.memory.MemoryToolset