Sayou

Sayou is a file-system inspired context store for AI agents that persist reasoning across sessions and expose an MCP server you can connect to with editors, CLIs, or code. It stores content as versioned files with frontmatter, supports powerful search and retrieval, and enables multi-tool workflows that keep knowledge growing over time.

How to use

You connect to the Sayou MCP server from your editor, CLI, or Python client and start performing file operations, key-value storage, and knowledge management. Use the MCP tools to write, read, list, search, and version content in a workspace that maintains a complete history. For agent workflows, you can run a local agent that talks to the MCP server, or use an HTTP endpoint if you enable a remote setup. Expect persistent reasoning artifacts, time-travel reads, and a structured knowledge base you can query across sessions.

Key capabilities you’ll use in day-to-day work include writing versioned files with YAML frontmatter, reading content within a token budget, listing workspace items, performing full-text and frontmatter searches, and inspecting version history or diffs between versions. You can also store small configuration or session data as key-value pairs with optional time-to-live values. All writes create a new version; nothing is overwritten, so you can always reconstruct or compare past states.

How to install

Prerequisites: Python 3.8+ and a functioning Python environment. You may also want a compatible editor that can act as an MCP client or use the CLI. If you plan to run the reference agent server, you will also configure API access for embedding or web search as needed.

Install Sayou from PyPI and optionally add the agent server for a ready-to-use MCP experience.

Basic installation (server + CLI):

pip install sayou

With REST API support (optional):

pip install sayou[api]

With the reference agent server (optional):

pip install sayou[agent]

Start the reference agent server after installation: you run the agent module directly.

python -m sayou.agent

Additional setup for MCP connections

If you want to connect from an editor or editor plugin, set up an MCP configuration that points to the Sayou agent server. The reference agent runs locally and exposes an HTTP interface at the base URL http://localhost:9008 with a streaming endpoint at /chat/stream. Use the provided MCP configuration snippet in your editor to connect and start issuing MCP calls.

Troubleshooting and tips

If you encounter tool-not-found or connection issues, verify your MCP configuration points to the correct base URL and that the agent server is running. Use the status command to confirm you can reach 11 tools and that the workspace path and database location are properly set.

Examples of common workflows

Create a versioned note, read it back, and search by metadata across sessions. Each write generates a new version, so you can compare changes over time and use time-travel reads to inspect past states.

Security considerations

Manage access to the MCP server carefully. Use environment variables for sensitive keys, and restrict HTTP access to trusted clients in production. Use TTLs for short-lived keys in the key-value store if your workflow involves ephemeral credentials.

Notes on local and remote operation

You can run the MCP server locally for development and connect editors or clients to it. For team use, you can expose the server via HTTP and use authentication mechanisms appropriate to your environment. The architecture supports a host of integrations, from file-based workflows to semantic searches over the workspace.

What you can do with the agent server

The reference agent can search, read, and write within your workspace, perform web searching for topics, and store findings with structured frontmatter and source citations. It can also execute code within a sandbox if you enable the optional E2B capabilities.

Quick start for the agent server (optional)

Install the agent dependencies, configure your API keys, and run the agent server. The agent’s server provides an HTTP streaming interface for interactive conversations and tool calls.

pip install sayou[agent]
cp agent/.env.example .env
python -m sayou.agent

Notes about the embedded tools

Sayou exposes 11 MCP tools out of the box for workspace management, file operations, and knowledge querying. These include workspace_write, workspace_read, workspace_list, workspace_search, workspace_delete, workspace_history, workspace_glob, workspace_grep, workspace_kv, workspace_links, workspace_chunks, and an optional workspace_semantic_search when embedding is enabled.

Available tools

workspace_write

Create or update a file in the workspace. Supports text or binary with YAML frontmatter.

workspace_read

Read latest or a specific version, with optional line ranges.

workspace_list

List files and folders with an auto-generated index.

workspace_search

Search by full-text query, frontmatter filters, or chunk-level search.

workspace_delete

Soft-delete a file while preserving its history.

workspace_history

View version history and compute diffs between versions.

workspace_glob

Find files that match a glob pattern.

workspace_grep

Search file contents with context lines.

workspace_kv

Key-value store with get/set/list/delete and optional TTL.

workspace_links

Manage file links and the knowledge graph.

workspace_chunks

Read an outline of chunks or access a specific chunk by index.

workspace_semantic_search

Vector similarity search using SAYOU_EMBEDDING_PROVIDER (if enabled).