sayou 0.2.1

A file-system inspired context store for AI agents

sayou

A file-system inspired context store for AI agents.

Built to replace the databases of the web era. Open source. File-first. SQL-compatible.

Databases were designed for transactions — they reduce nuance to fit a schema. Agents think deeply, then forget everything when the session ends. sayou is where reasoning persists, context accumulates, and knowledge compounds over time.

• Files that hold what databases can't — Frontmatter for structure. Markdown for context. Versioned. Auditable.
• One read. Full context. — Every read accepts a token_budget. Returns summaries with section pointers when content exceeds the budget.
• Knowledge that compounds — Append-only version history. Every change is a new version. Full audit trail and time-travel reads.
• Any agent can connect — MCP server, Python library, or CLI. Optional REST API with pip install sayou[api].

Quick Start

1. Install

pip install sayou

2. Initialize

sayou init

3. Connect to Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "sayou": { "command": "sayou" }
  }
}

4. Verify

Restart Claude Code (so it picks up the new MCP config), then run:

sayou status

You should see your workspace path, database location, and 11 tools registered. If you see errors, jump to Troubleshooting.

Try It

Open Claude Code and paste any of these prompts. Each one triggers a different MCP tool — no setup beyond the Quick Start above.

Prompt	What happens	Tool
"Save a note about our Q1 goals with status: draft"	Creates a versioned file with YAML frontmatter	workspace_write
"What files are in my workspace?"	Lists all files and subfolders	workspace_list
"Search for anything tagged status: draft"	Filters files by frontmatter metadata	workspace_search
"Read the Q1 goals note"	Retrieves file content with token-budget awareness	workspace_read
"Update the status to reviewed"	Writes a new version (old version preserved)	workspace_write
"Show me the diff between versions"	Compares two versions with unified diff	workspace_history
"Store a setting: theme = dark"	Saves a key-value pair (with optional TTL)	workspace_kv
"Find all markdown files in research/"	Matches files by glob pattern	workspace_glob
"Search file contents for the word 'budget'"	Grep-style content search with context	workspace_grep

Every write creates a new version. Nothing is overwritten. You can always go back.

What It Looks Like

A short conversation showing sayou in action across sessions:

---

You: Research competitor pricing for our enterprise tier and save your findings.

Claude Code: I'll research this and save my findings to the workspace.

[Uses workspace_write to create research/competitor-pricing.md]

Saved to research/competitor-pricing.md with frontmatter: status: draft, topic: competitor-pricing

---

You (next day, new session): What did we learn about competitor pricing?

Claude Code: Let me check our workspace.

[Uses workspace_search with query "competitor pricing"]

Found research/competitor-pricing.md (saved yesterday):

• Competitor A: $99/seat/month
• Competitor B: $149/seat/month (includes support)
• Competitor C: $79/seat/month (limited features)

---

You: Update the status to "reviewed" and show me the diff.

Claude Code: [Uses workspace_write to create version 2, then workspace_history to diff]

- status: draft
+ status: reviewed
+ reviewer_notes: |
+   Competitor B is closest to our positioning.

---

The key insight: Claude Code remembered the research across sessions because sayou persisted it as a versioned file — not a chat message that disappears.

Setup for Other Editors

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "sayou": { "command": "sayou" }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sayou": { "command": "sayou" }
  }
}

Any MCP-compatible client

sayou is a standard MCP server. The config is always the same — just "command": "sayou". Check your editor's docs for where it reads MCP server configuration.

MCP Tools

The agent gets 11 tools (12 with embeddings enabled):

Tool	Description
workspace_write	Write or update a file (text or binary with YAML frontmatter)
workspace_read	Read latest or specific version, with optional line range
workspace_list	List files and subfolders with auto-generated index
workspace_search	Search by full-text query, frontmatter filters, or chunk-level
workspace_delete	Soft-delete a file (history preserved)
workspace_history	Version history with timestamps, or diff between two versions
workspace_glob	Find files matching a glob pattern
workspace_grep	Search file contents with context lines
workspace_kv	Key-value store (get/set/list/delete with optional TTL)
workspace_links	File links and knowledge graph (get or add links)
workspace_chunks	Chunk outline or read a specific chunk by index
workspace_semantic_search	Vector similarity search (requires SAYOU_EMBEDDING_PROVIDER)

Python API

import asyncio
from sayou import Workspace

async def main():
    async with Workspace() as ws:
        # Write a file with YAML frontmatter
        await ws.write("notes/hello.md", """\
---
status: active
tags: [demo, quickstart]
---
# Hello from sayou
This file is versioned and searchable.
""")

        # Read it back
        doc = await ws.read("notes/hello.md")
        print(doc["content"])

        # Search by frontmatter
        results = await ws.search(filters={"status": "active"})
        print(f"Found {results['total']} active files")

asyncio.run(main())

See examples/quickstart.py for a runnable version.

CLI

# File operations
sayou file read notes/hello.md
sayou file write notes/hello.md "# Hello World"
sayou file list /
sayou file search --query "hello" --filter status=active

# KV store
sayou kv set config.theme '"dark"'
sayou kv get config.theme

# Diagnostics
sayou init      # Initialize local setup
sayou status    # Show diagnostic info

Examples

Example	What it shows
quickstart.py	Hello World — write, read, search, list in 30 lines
kv_config.py	KV store for config, feature flags, caching with TTL
version_control.py	Version history, diff, time-travel reads
file_operations.py	Move, copy, binary files, glob patterns
multi_agent.py	Multi-agent collaboration with shared workspace
research_agent.py	All methods exercised — the comprehensive reference

Reference Agent

sayou ships with a reference agent server — a multi-turn assistant that can search, read, write, and research using your workspace. It's a complete working example of building an agent on sayou.

Quick start

# Install with agent dependencies
pip install sayou[agent]

# Configure (copy and fill in your OpenAI key)
cp agent/.env.example .env

# Run the agent server
python -m sayou.agent

The agent runs on http://localhost:9008 with a streaming SSE endpoint at POST /chat/stream.

What the agent can do

Capability	How it works
Answer questions	Searches workspace first, falls back to web search
Research topics	Multiple web searches, extracts facts, saves structured findings
Store knowledge	Writes files with YAML frontmatter, section headings, source citations
Execute code	Optional E2B sandbox for Python and bash (set SAYOU_AGENT_E2B_API_KEY)

Run benchmarks

# Start agent in one terminal
python -m sayou.agent

# Quick pass/fail eval
python -m sayou.agent.benchmarks.eval

# Detailed scoring (0-10 per capability)
python -m sayou.agent.benchmarks.eval_full

Architecture

Client → FastAPI (port 9008)
         ↓
      Orchestrator
         ├─ LLMProvider (OpenAI streaming + tool calls)
         ├─ ToolFactory
         │  ├─ workspace_search/read/list/write (→ sayou SDK)
         │  ├─ web_search (→ Tavily API, optional)
         │  └─ execute_bash/python (→ E2B sandbox, optional)
         └─ SandboxManager (per-session isolation, auto-cleanup)

Installation Options

# Basic (MCP server + CLI + SQLite)
pip install sayou

# With REST API support
pip install sayou[api]

# With S3 storage
pip install sayou[s3]

# With reference agent server
pip install sayou[agent]

# Full installation (all features)
pip install sayou[all]

Production Deployment

For team/production use with MySQL + S3:

{
  "mcpServers": {
    "sayou": {
      "command": "sayou",
      "env": {
        "SAYOU_ORG_ID": "my-org",
        "SAYOU_USER_ID": "alice",
        "SAYOU_DATABASE_URL": "mysql+aiomysql://user:pass@host/sayou",
        "SAYOU_S3_BUCKET_NAME": "my-bucket",
        "SAYOU_S3_ACCESS_KEY_ID": "...",
        "SAYOU_S3_SECRET_ACCESS_KEY": "..."
      }
    }
  }
}

Install with all backends: pip install sayou[all]

Storage Backends

Backend	Config	Use case
SQLite + local disk (default)	No config needed	Local dev, single-machine agents, MCP server
MySQL + S3	Set database_url, S3 credentials	Production, multi-agent, shared workspaces

Troubleshooting

Verify your setup

sayou status

This shows your workspace path, database location, storage backend, and tool count. If everything is working, you'll see 11 tools registered.

Common issues

Problem	Cause	Fix
Claude Code doesn't see sayou tools	MCP config not loaded	Restart Claude Code after editing ~/.claude/mcp.json
sayou: command not found	Not on PATH	Run pip install sayou again, or use full path in MCP config: "command": "/path/to/sayou"
sayou status shows 0 tools	Server didn't initialize	Run sayou init first, then check for errors in output
Files not persisting	Wrong workspace path	Check sayou status for the workspace path — default is ~/.sayou/
Import errors on startup	Missing optional dependency	Install the extra you need: pip install sayou[api], sayou[s3], or sayou[all]

Get help

• GitHub Issues — bug reports and feature requests
• CONTRIBUTING.md — development setup and contribution guide

What sayou is NOT

• Not a vector database. Pinecone, Weaviate, and Chroma store embeddings for similarity search. sayou stores structured files that agents read, write, and reason over.
• Not a memory layer. Mem0 and similar tools store conversation snippets. sayou stores work product — research, client records, project documentation — that compounds over time.
• Not a sandbox. E2B provides ephemeral execution environments. sayou provides persistent storage that outlives any single execution.
• Not a filesystem. AgentFS intercepts syscalls to virtualize file operations. A knowledge workspace with versioning and indexing.

Philosophy

Read PHILOSOPHY.md for the founding vision and design principles.

Contributing

See CONTRIBUTING.md.

License

Apache 2.0 — See LICENSE