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.
| 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
This adds sayou to .cursor/mcp.json in your current working directory.
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".
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:
await ws.write("notes/hello.md", """\
---
status: active
tags: [demo, quickstart]
---
# Hello from sayou
This file is versioned and searchable.
""")
doc = await ws.read("notes/hello.md")
print(doc["content"])
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
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
sayou kv set config.theme '"dark"'
sayou kv get config.theme
sayou auth
sayou auth status
sayou auth logout
sayou init
sayou status
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
pip install sayou[agent]
cp agent/.env.example .env
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) |
Evaluate the agent
python -m sayou.agent
python -m sayou.agent.benchmarks.eval
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
| Dimension | What it tests |
|---|
| Decision reasoning | "Why was bcrypt chosen over Argon2?" |
| Artifact content | "What endpoints are in the API docs?" |
| Cross-session | "How does session 3's auth decision affect session 5's implementation?" |
| Fact recall | "What was the monthly GCP cost estimate?" |
| Temporal | "What changed between the first and second architecture review?" |
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
python -m benchmarks.runner.cli
python -m benchmarks.runner.cli --adapter sayou mem0
python -m benchmarks.runner.cli --adapter sayou --scenario 01 03 08
python -m benchmarks.runner.cli --verbose
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
| Adapter | System | Retrieval approach |
|---|
sayou | sayou workspace | FTS5 + grep + file read (agentic, multi-tool) |
mem0 | mem0 | LLM fact extraction + embedding search (agentic) |
zep | Zep Cloud | Knowledge graph + temporal edges (agentic) |
oracle | Baseline | Direct access to source sessions (upper bound) |
no_memory | Baseline | No retrieval (lower bound) |
Methodology
Each adapter uses agentic retrieval — an LLM generates multiple search queries rather than a single-shot lookup. This gives every system a fair chance at finding relevant information.
Scoring: LLM-judged (gpt-4o-mini) on a 0–3 scale, normalized to percentage. Task-type questions add holistic scoring (1–5) and evidence coverage (per-item FOUND/MISSING). Statistical significance via bootstrap confidence intervals with Bonferroni correction.
Full methodology: benchmarks/dataset/METHODOLOGY.md
Dataset card: benchmarks/dataset/DATASET_CARD.md
Installation Options
pip install sayou
pip install sayou[api]
pip install sayou[s3]
pip install sayou[agent]
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
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
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