sayou-pydantic-ai 0.1.0

Sayou workspace toolset for Pydantic AI agents — persistent memory, file storage, and search

sayou-pydantic-ai

Persistent memory and workspace storage for Pydantic AI agents. Write files, search content, and persist conversation history — all through a single toolset.

Built on sayou, the file-system inspired context store for AI agents.

Install

pip install sayou-pydantic-ai

Quick Start

from pydantic_ai import Agent
from sayou_pydantic_ai import SayouToolset

agent = Agent("openai:gpt-4o", toolsets=[SayouToolset()])
result = await agent.run("Save a note about our meeting decisions")

Zero config. The agent gets 7 workspace tools and a local SQLite store at ~/.sayou/. Files persist across sessions.

Tools

Tool	Description
workspace_write	Create or update files (supports YAML frontmatter)
workspace_read	Read files with token budget control
workspace_list	List files and subfolders
workspace_search	Full-text and metadata search
workspace_grep	Content search with line context
workspace_glob	Pattern matching (**/*.md, docs/**)
workspace_kv	Key-value store for config/state

Optional tools (opt-in)

Tool	Description
workspace_delete	Soft-delete files
workspace_history	Version history
workspace_links	File-to-file links
workspace_chunks	Chunk-based file reading

Enable them with the tools parameter:

from sayou_pydantic_ai.toolset import ALL_TOOLS

SayouToolset(tools=ALL_TOOLS)                          # Everything
SayouToolset(tools={"read", "write", "search", "delete"})  # Pick what you need

Persist Conversation History

from sayou.workspace import Workspace
from sayou_pydantic_ai import SayouToolset, SayouMessageHistory

async with Workspace() as ws:
    history = SayouMessageHistory(ws, conversation_id="project-alpha")
    agent = Agent("openai:gpt-4o", toolsets=[SayouToolset(workspace=ws)])

    # Load previous messages
    messages = await history.load()

    # Run with history
    result = await agent.run("Continue our discussion", message_history=messages)

    # Save for next session
    await history.save(result.all_messages())

Options:

• max_messages=50 — keep only the last N messages
• ttl_seconds=86400 — auto-expire after 24 hours

Choose Your Tools

# Default: 7 core tools
SayouToolset()

# Minimal: just read and write
SayouToolset(tools={"read", "write"})

# Full: all 11 tools including delete
SayouToolset(tools=ALL_TOOLS)

# Custom prefix
SayouToolset(tool_prefix="ws")      # ws_read, ws_write, ...
SayouToolset(tool_prefix="")        # read, write, ... (no prefix)

Dependency Injection

Use from_deps when the workspace comes from your agent's dependency system:

from dataclasses import dataclass
from sayou.workspace import Workspace
from sayou_pydantic_ai import SayouToolset

@dataclass
class MyDeps:
    workspace: Workspace

agent = Agent(
    "openai:gpt-4o",
    deps_type=MyDeps,
    toolsets=[SayouToolset.from_deps(lambda d: d.workspace)],
)

Configuration

Database

By default, sayou uses SQLite at ~/.sayou/sayou.db. For production, point to MySQL or any SQLAlchemy-compatible database:

SayouToolset(database_url="mysql+aiomysql://user:pass@host/db")

Or set the environment variable:

export SAYOU_DATABASE_URL="mysql+aiomysql://user:pass@host/db"

Workspace identity

SayouToolset(
    workspace=Workspace(
        slug="my-project",
        org_id="my-org",
        user_id="agent-1",
    )
)

How It Works

SayouToolset implements Pydantic AI's AbstractToolset interface. When the agent runs:

1. get_tools() returns tool definitions with JSON schemas
2. The LLM sees tools like workspace_write(path, content) and calls them
3. call_tool() dispatches to the corresponding Workspace method
4. Results are returned to the LLM as strings

Files are stored with version history. Every write creates a new version — nothing is lost.

SayouMessageHistory uses sayou's built-in KV store to serialize/deserialize Pydantic AI's ModelMessage objects via TypeAdapter.

Links

• sayou — the workspace engine
• Pydantic AI — the agent framework
• Pydantic AI Toolsets — toolset documentation

License

Apache 2.0