{
  "markdown": "# sayou\n\n**A file-system inspired context store for AI agents.**\n\nBuilt to replace the databases of the web era. Open source. File-first. SQL-compatible.\n\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org)\n\nDatabases 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.\n\n- **Files that hold what databases can't** — Frontmatter for structure. Markdown for context. Versioned. Auditable.\n- **One read. Full context.** — Every read accepts a `token_budget`. Returns summaries with section pointers when content exceeds the budget.\n- **Knowledge that compounds** — Append-only version history. Every change is a new version. Full audit trail and time-travel reads.\n- **Any agent can connect** — MCP server, Python library, or CLI. Optional REST API with `pip install sayou[api]`.\n\n## Quick Start\n\n### Claude Code (recommended)\n\nFrom within Claude Code:\n\n```\n/plugin install sayou@pixell-global\n```\n\nOr from the terminal:\n\n```bash\nclaude plugin install sayou@pixell-global\n```\n\nOne 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.\n\n> **Cloud mode**: To sync your workspace via [Sayou Drive](https://drive.sayou.dev), run `sayou auth` after installing and paste your API key from [Settings](https://drive.sayou.dev/settings).\n\n### pip install\n\n```bash\npip install sayou && sayou init --claude\n```\n\nThis 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.\n\nTo 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](#troubleshooting).\n\n## Try It\n\nOpen Claude Code and paste any of these prompts. Each one triggers a different MCP tool — no setup beyond the Quick Start above.\n\n| Prompt | What happens | Tool |\n|--------|-------------|------|\n| \"Save a note about our Q1 goals with status: draft\" | Creates a versioned file with YAML frontmatter | `workspace_write` |\n| \"What files are in my workspace?\" | Lists all files and subfolders | `workspace_list` |\n| \"Search for anything tagged status: draft\" | Filters files by frontmatter metadata | `workspace_search` |\n| \"Read the Q1 goals note\" | Retrieves file content with token-budget awareness | `workspace_read` |\n| \"Update the status to reviewed\" | Writes a new version (old version preserved) | `workspace_write` |\n| \"Show me the diff between versions\" | Compares two versions with unified diff | `workspace_history` |\n| \"Store a setting: theme = dark\" | Saves a key-value pair (with optional TTL) | `workspace_kv` |\n| \"Find all markdown files in research/\" | Matches files by glob pattern | `workspace_glob` |\n| \"Search file contents for the word 'budget'\" | Grep-style content search with context | `workspace_grep` |\n\nEvery write creates a new version. Nothing is overwritten. You can always go back.\n\n## What It Looks Like\n\nA short conversation showing sayou in action across sessions:\n\n---\n\n**You:** Research competitor pricing for our enterprise tier and save your findings.\n\n**Claude Code:** I'll research this and save my findings to the workspace.\n\n*[Uses `workspace_write` to create `research/competitor-pricing.md`]*\n\n> Saved to `research/competitor-pricing.md` with frontmatter:\n> status: draft, topic: competitor-pricing\n\n---\n\n**You** *(next day, new session):* What did we learn about competitor pricing?\n\n**Claude Code:** Let me check our workspace.\n\n*[Uses `workspace_search` with query \"competitor pricing\"]*\n\n> Found `research/competitor-pricing.md` (saved yesterday):\n> - Competitor A: $99/seat/month\n> - Competitor B: $149/seat/month (includes support)\n> - Competitor C: $79/seat/month (limited features)\n\n---\n\n**You:** Update the status to \"reviewed\" and show me the diff.\n\n**Claude Code:** *[Uses `workspace_write` to create version 2, then `workspace_history` to diff]*\n\n> ```diff\n> - status: draft\n> + status: reviewed\n> + reviewer_notes: |\n> +   Competitor B is closest to our positioning.\n> ```\n\n---\n\nThe key insight: Claude Code remembered the research **across sessions** because sayou persisted it as a versioned file — not a chat message that disappears.\n\n## Setup for Other Editors\n\n### Cursor\n\n```bash\nsayou init --cursor\n```\n\nThis adds sayou to `.cursor/mcp.json` in your current working directory.\n\n### Windsurf\n\n```bash\nsayou init --windsurf\n```\n\nThis adds sayou to `~/.codeium/windsurf/mcp_config.json`.\n\n### Any MCP-compatible client\n\nsayou 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\"`.\n\n## MCP Tools\n\nThe agent gets 11 tools (12 with embeddings enabled):\n\n| Tool | Description |\n|------|-------------|\n| `workspace_write` | Write or update a file (text or binary with YAML frontmatter) |\n| `workspace_read` | Read latest or specific version, with optional line range |\n| `workspace_list` | List files and subfolders with auto-generated index |\n| `workspace_search` | Search by full-text query, frontmatter filters, or chunk-level |\n| `workspace_delete` | Soft-delete a file (history preserved) |\n| `workspace_history` | Version history with timestamps, or diff between two versions |\n| `workspace_glob` | Find files matching a glob pattern |\n| `workspace_grep` | Search file contents with context lines |\n| `workspace_kv` | Key-value store (get/set/list/delete with optional TTL) |\n| `workspace_links` | File links and knowledge graph (get or add links) |\n| `workspace_chunks` | Chunk outline or read a specific chunk by index |\n| `workspace_semantic_search` | Vector similarity search (requires `SAYOU_EMBEDDING_PROVIDER`) |\n\n## Python API\n\n```python\nimport asyncio\nfrom sayou import Workspace\n\nasync def main():\n    async with Workspace() as ws:\n        # Write a file with YAML frontmatter\n        await ws.write(\"notes/hello.md\", \"\"\"\\\n---\nstatus: active\ntags: [demo, quickstart]\n---\n# Hello from sayou\nThis file is versioned and searchable.\n\"\"\")\n\n        # Read it back\n        doc = await ws.read(\"notes/hello.md\")\n        print(doc[\"content\"])\n\n        # Search by frontmatter\n        results = await ws.search(filters={\"status\": \"active\"})\n        print(f\"Found {results['total']} active files\")\n\nasyncio.run(main())\n```\n\nSee [`examples/quickstart.py`](examples/quickstart.py) for a runnable version.\n\n## CLI\n\n```bash\n# File operations\nsayou file read notes/hello.md\nsayou file write notes/hello.md \"# Hello World\"\nsayou file list /\nsayou file search --query \"hello\" --filter status=active\n\n# KV store\nsayou kv set config.theme '\"dark\"'\nsayou kv get config.theme\n\n# Cloud authentication\nsayou auth            # Connect to Sayou Drive (interactive)\nsayou auth status     # Show current mode (cloud/local)\nsayou auth logout     # Disconnect from Sayou Drive\n\n# Diagnostics\nsayou init      # Initialize local setup\nsayou status    # Show diagnostic info\n```\n\n## Examples\n\n| Example | What it shows |\n|---------|---------------|\n| [`quickstart.py`](examples/quickstart.py) | Hello World — write, read, search, list in 30 lines |\n| [`kv_config.py`](examples/kv_config.py) | KV store for config, feature flags, caching with TTL |\n| [`version_control.py`](examples/version_control.py) | Version history, diff, time-travel reads |\n| [`file_operations.py`](examples/file_operations.py) | Move, copy, binary files, glob patterns |\n| [`multi_agent.py`](examples/multi_agent.py) | Multi-agent collaboration with shared workspace |\n| [`research_agent.py`](examples/research_agent.py) | All methods exercised — the comprehensive reference |\n\n## Reference Agent\n\nsayou 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.\n\n### Quick start\n\n```bash\n# Install with agent dependencies\npip install sayou[agent]\n\n# Configure (copy and fill in your OpenAI key)\ncp agent/.env.example .env\n\n# Run the agent server\npython -m sayou.agent\n```\n\nThe agent runs on `http://localhost:9008` with a streaming SSE endpoint at `POST /chat/stream`.\n\n### What the agent can do\n\n| Capability | How it works |\n|------------|-------------|\n| **Answer questions** | Searches workspace first, falls back to web search |\n| **Research topics** | Multiple web searches, extracts facts, saves structured findings |\n| **Store knowledge** | Writes files with YAML frontmatter, section headings, source citations |\n| **Execute code** | Optional E2B sandbox for Python and bash (set `SAYOU_AGENT_E2B_API_KEY`) |\n\n### Evaluate the agent\n\n```bash\n# Start agent in one terminal\npython -m sayou.agent\n\n# Quick pass/fail eval\npython -m sayou.agent.benchmarks.eval\n\n# Detailed scoring (0-10 per capability)\npython -m sayou.agent.benchmarks.eval_full\n```\n\n### Architecture\n\n```\nClient → FastAPI (port 9008)\n         ↓\n      Orchestrator\n         ├─ LLMProvider (OpenAI streaming + tool calls)\n         ├─ ToolFactory\n         │  ├─ workspace_search/read/list/write (→ sayou SDK)\n         │  ├─ web_search (→ Tavily API, optional)\n         │  └─ execute_bash/python (→ E2B sandbox, optional)\n         └─ SandboxManager (per-session isolation, auto-cleanup)\n```\n\n## SAMB: Structured Agent Memory Benchmark\n\nsayou 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.\n\n### What SAMB measures\n\n| Dimension | What it tests |\n|-----------|---------------|\n| **Decision reasoning** | \"Why was bcrypt chosen over Argon2?\" |\n| **Artifact content** | \"What endpoints are in the API docs?\" |\n| **Cross-session** | \"How does session 3's auth decision affect session 5's implementation?\" |\n| **Fact recall** | \"What was the monthly GCP cost estimate?\" |\n| **Temporal** | \"What changed between the first and second architecture review?\" |\n\n10 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.\n\n### Run the benchmark\n\n```bash\n# Prerequisites: pip install sayou mem0ai zep-cloud\n# Requires: OPENAI_API_KEY (for judge/answer models)\n#           ZEP_API_KEY (for zep adapter)\n\n# Run all adapters on all scenarios\npython -m benchmarks.runner.cli\n\n# Specific adapters\npython -m benchmarks.runner.cli --adapter sayou mem0\n\n# Specific scenarios\npython -m benchmarks.runner.cli --adapter sayou --scenario 01 03 08\n\n# Verbose output (per-question scores)\npython -m benchmarks.runner.cli --verbose\n\n# Override judge/answer models\npython -m benchmarks.runner.cli --judge-model gpt-4o --answer-model gpt-4o\n```\n\nResults are saved to `benchmarks/results/` as JSON with full per-question breakdowns.\n\n### Available adapters\n\n| Adapter | System | Retrieval approach |\n|---------|--------|-------------------|\n| `sayou` | sayou workspace | FTS5 + grep + file read (agentic, multi-tool) |\n| `mem0` | mem0 | LLM fact extraction + embedding search (agentic) |\n| `zep` | Zep Cloud | Knowledge graph + temporal edges (agentic) |\n| `oracle` | Baseline | Direct access to source sessions (upper bound) |\n| `no_memory` | Baseline | No retrieval (lower bound) |\n\n### Methodology\n\nEach 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.\n\nScoring: 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.\n\nFull methodology: [`benchmarks/dataset/METHODOLOGY.md`](benchmarks/dataset/METHODOLOGY.md)\nDataset card: [`benchmarks/dataset/DATASET_CARD.md`](benchmarks/dataset/DATASET_CARD.md)\n\n## Installation Options\n\n```bash\n# Basic (MCP server + CLI + SQLite)\npip install sayou\n\n# With REST API support\npip install sayou[api]\n\n# With S3 storage\npip install sayou[s3]\n\n# With reference agent server\npip install sayou[agent]\n\n# Full installation (all features)\npip install sayou[all]\n```\n\n## Production Deployment\n\nFor team/production use with MySQL + S3:\n\n```json\n{\n  \"mcpServers\": {\n    \"sayou\": {\n      \"command\": \"sayou\",\n      \"env\": {\n        \"SAYOU_ORG_ID\": \"my-org\",\n        \"SAYOU_USER_ID\": \"alice\",\n        \"SAYOU_DATABASE_URL\": \"mysql+aiomysql://user:pass@host/sayou\",\n        \"SAYOU_S3_BUCKET_NAME\": \"my-bucket\",\n        \"SAYOU_S3_ACCESS_KEY_ID\": \"...\",\n        \"SAYOU_S3_SECRET_ACCESS_KEY\": \"...\"\n      }\n    }\n  }\n}\n```\n\nInstall with all backends: `pip install sayou[all]`\n\n## Storage Backends\n\n| Backend | Config | Use case |\n|---------|--------|----------|\n| **SQLite + local disk** (default) | No config needed | Local dev, single-machine agents, MCP server |\n| **MySQL + S3** | Set `database_url`, S3 credentials | Production, multi-agent, shared workspaces |\n\n## Troubleshooting\n\n### Verify your setup\n\n```bash\nsayou status\n```\n\nThis shows your workspace path, database location, storage backend, and tool count. If everything is working, you'll see `11 tools registered`.\n\n### Common issues\n\n| Problem | Cause | Fix |\n|---------|-------|-----|\n| Claude Code doesn't see sayou tools | MCP config not loaded | Restart Claude Code after editing `~/.claude/mcp.json` |\n| `sayou: command not found` | Not on PATH | Run `pip install sayou` again, or use full path in MCP config: `\"command\": \"/path/to/sayou\"` |\n| `sayou status` shows 0 tools | Server didn't initialize | Run `sayou init` first, then check for errors in output |\n| Files not persisting | Wrong workspace path | Check `sayou status` for the workspace path — default is `~/.sayou/` |\n| Import errors on startup | Missing optional dependency | Install the extra you need: `pip install sayou[api]`, `sayou[s3]`, or `sayou[all]` |\n\n### Get help\n\n- [GitHub Issues](https://github.com/pixell-global/sayou/issues) — bug reports and feature requests\n- [CONTRIBUTING.md](./CONTRIBUTING.md) — development setup and contribution guide\n\n## What sayou is NOT\n\n- **Not a vector database.** Pinecone, Weaviate, and Chroma store embeddings for similarity search. sayou stores structured files that agents read, write, and reason over.\n- **Not a memory layer.** Mem0 and similar tools store conversation snippets. sayou stores work product — research, client records, project documentation — that compounds over time.\n- **Not a sandbox.** E2B provides ephemeral execution environments. sayou provides persistent storage that outlives any single execution.\n- **Not a filesystem.** AgentFS intercepts syscalls to virtualize file operations. A knowledge workspace with versioning and indexing.\n\n## Philosophy\n\nRead [PHILOSOPHY.md](./PHILOSOPHY.md) for the founding vision and design principles.\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## License\n\nApache 2.0 — See [LICENSE](./LICENSE)\n\n<!-- mcp-name: io.github.pixell-global/sayou -->\n",
  "bytes": 15732,
  "sha": "c7df5befc808644e553f2c28d6197b621ffd61d8ec841e231cea762123d523e8",
  "repo_slug": "pixell-global/sayou",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pixell_global_sayou_1a661782/readme"
}