sayou

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

Claude Code (recommended)

From within Claude Code:

/plugin install sayou@pixell-global

Or from the terminal:

claude plugin install sayou@pixell-global

One command. This installs the plugin with lifecycle hooks (workspace context on session start, passive activity capture, session summaries) and skills (/ws, /save, /recall). If sayou isn't installed yet, the plugin auto-installs it on first run.

Cloud mode: To sync your workspace via Sayou Drive, run sayou auth after installing and paste your API key from Settings.

pip install

pip install sayou && sayou init --claude

This installs sayou and configures ~/.claude/mcp.json. You get the 11 MCP tools but no hooks or skills. You can also use --cursor or --windsurf, or run sayou init without flags to get the config snippet to paste manually.

To verify either method, 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.

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]*

`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

sayou init --cursor

This adds sayou to .cursor/mcp.json in your current working directory.

Windsurf

sayou init --windsurf

This adds sayou to ~/.codeium/windsurf/mcp_config.json.

Any MCP-compatible client

sayou is a standard MCP server. Run sayou init (no flag) to get the config snippet, then paste it into your editor's MCP config. The entry is always the same — just "command": "sayou".

MCP Tools

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

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

Cloud authentication

sayou auth # Connect to Sayou Drive (interactive) sayou auth status # Show current mode (cloud/local) sayou auth logout # Disconnect from Sayou Drive

Diagnostics

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

Examples

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

Evaluate the agent

# 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)

SAMB: Structured Agent Memory Benchmark

sayou includes SAMB — an open benchmark for evaluating memory systems on real agentic workflows. Existing benchmarks (LOCOMO, LongMemEval, DMR) test conversation recall. SAMB tests what agents actually need: recalling decisions, retrieving artifact contents, and connecting knowledge across sessions.

What SAMB measures

10 scenarios, 62 sessions, 131 QA pairs across 7 question types. Each scenario simulates a multi-session professional project (auth system design, cloud migration, email campaigns, incident response, etc.) with realistic conversations, decisions, and artifacts.

Run the benchmark

# Prerequisites: pip install sayou mem0ai zep-cloud

Requires: OPENAI_API_KEY (for judge/answer models)

ZEP_API_KEY (for zep adapter)

Run all adapters on all scenarios

python -m benchmarks.runner.cli

Specific adapters

python -m benchmarks.runner.cli --adapter sayou mem0

Specific scenarios

python -m benchmarks.runner.cli --adapter sayou --scenario 01 03 08

Verbose output (per-question scores)

python -m benchmarks.runner.cli --verbose

Override judge/answer models

python -m benchmarks.runner.cli --judge-model gpt-4o --answer-model gpt-4o

Results are saved to benchmarks/results/ as JSON with full per-question breakdowns.

Available adapters

Methodology

Each adapter use