sayou

sayou

一款受文件系统启发、专为 AI Agent 打造的上下文存储库。

旨在取代 Web 时代的数据库。开源。文件优先。兼容 SQL。

数据库是为事务设计的——它们将细微差异压缩进模式中。Agent 会深入思考，却在会话结束时忘记一切。sayou 让推理得以留存、上下文不断积累、知识随时间持续增益。

• 数据库无法承载的内容，由文件承载 — 通过 Frontmatter 定义结构，通过 Markdown 保存上下文。支持版本管理，可审计。
• 一次读取，获取完整上下文。 — 每次读取都接受 token_budget。当内容超出预算时，返回摘要以及各章节的指针。
• 知识持续增益 — 版本历史仅追加。每次更改都会生成一个新版本。提供完整审计轨迹，并支持读取历史时点的数据。
• 任何 Agent 都能连接 — MCP 服务、Python 库或 CLI。可选 REST API，可通过 pip install sayou[api] 安装。

快速开始

Claude Code（推荐）

在 Claude Code 中：

/plugin install sayou@pixell-global

或在终端中：

claude plugin install sayou@pixell-global

只需一条命令。此命令会安装带有生命周期钩子的插件（会话开始时加载工作区上下文、被动捕获活动、生成会话摘要）以及技能（/ws、/save、/recall）。如果尚未安装 sayou，插件会在首次运行时自动安装。

云模式：若要通过 Sayou Drive 同步工作区，请在安装后运行 sayou auth，并粘贴从 Settings 获取的 API 密钥。

pip install

pip install sayou && sayou init --claude

此命令会安装 sayou 并配置 ~/.claude/mcp.json。你将获得 11 个 MCP 工具，但不包含钩子或技能。你也可以使用 --cursor 或 --windsurf，或者不带标志运行 sayou init，获取可手动粘贴的配置片段。

无论使用哪种方式，都可以运行 sayou status 进行验证——你应该能看到工作区路径、数据库位置以及 11 tools registered。如果遇到错误，请参阅故障排除。

试试看

打开 Claude Code，粘贴以下任意提示词。每条提示词都会触发不同的 MCP 工具——除了上述快速开始步骤外，无需其他设置。

提示词	执行结果	工具
“保存一条关于我们第一季度目标的笔记，状态为：草稿”	创建包含 YAML Frontmatter 的版本化文件	workspace_write
“我的工作区里有哪些文件？”	列出所有文件和子文件夹	workspace_list
“搜索所有带有状态：草稿标签的内容”	根据 Frontmatter 元数据筛选文件	workspace_search
“读取第一季度目标笔记”	获取文件内容，并根据 token 预算进行处理	workspace_read
“将状态更新为已审核”	写入一个新版本（保留旧版本）	workspace_write
“显示不同版本之间的差异”	使用统一 diff 格式比较两个版本	workspace_history
“存储一个设置：theme = dark”	保存一个键值对（可选 TTL）	workspace_kv
“查找 research/ 中的所有 Markdown 文件”	按 glob 模式匹配文件	workspace_glob
“搜索文件内容中包含单词 ‘budget’ 的位置”	以 grep 方式搜索内容并显示上下文	workspace_grep

每次写入都会创建一个新版本，不会覆盖任何内容。你随时都可以回退。

效果展示

简短对话，展示 sayou 如何跨会话工作：

---

你： 调研企业版竞争对手的定价，并保存调研结果。

Claude Code： 我来调研并将结果保存到工作区。

[使用 workspace_write 创建 research/competitor-pricing.md]

已保存到 research/competitor-pricing.md，包含以下 frontmatter： status: draft, topic: competitor-pricing

---

你（第二天，新会话）：竞争对手的定价调研有什么发现？

Claude Code： 我来查看工作区。

[使用 workspace_search，查询内容为 "competitor pricing"]

找到 research/competitor-pricing.md（昨天保存）：

• 竞争对手 A：每席位每月 $99
• 竞争对手 B：每席位每月 $149（包含支持服务）
• 竞争对手 C：每席位每月 $79（功能有限）

---

你： 将状态更新为 "reviewed"，并向我展示差异。

Claude Code： [使用 workspace_write 创建版本 2，然后使用 workspace_history 生成差异]

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

---

关键在于：Claude Code 能够跨会话记住这项调研，是因为 sayou 将其持久化为带版本的文件，而不是会消失的聊天消息。

为其他编辑器进行设置

Cursor

sayou init --cursor

这会将 sayou 添加到当前工作目录中的 .cursor/mcp.json。

Windsurf

sayou init --windsurf

这会将 sayou 添加到 ~/.codeium/windsurf/mcp_config.json。

任何兼容 MCP 的客户端

sayou 是标准 MCP 服务。运行 sayou init（不带标志）以获取配置片段，然后将其粘贴到编辑器的 MCP 配置中。配置项始终相同，即 "command": "sayou"。

MCP 工具

Agent 可使用 11 个工具（启用 embeddings 后为 12 个）：

工具	描述
workspace_write	写入或更新文件（支持带 YAML frontmatter 的文本或二进制文件）
workspace_read	读取最新版本或指定版本，可选择行范围
workspace_list	列出文件和子文件夹，并自动生成索引
workspace_search	按全文查询、frontmatter 筛选条件或分块级别进行搜索
workspace_delete	软删除文件（保留历史记录）
workspace_history	查看带时间戳的版本历史，或比较两个版本
workspace_glob	查找符合 glob 模式的文件
workspace_grep	搜索文件内容并显示上下文行
workspace_kv	键值存储（支持 get/set/list/delete，可选 TTL）
workspace_links	文件链接和知识图谱（获取或添加链接）
workspace_chunks	查看分块大纲，或按索引读取指定分块
workspace_semantic_search	向量相似度搜索（需要 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())

可运行版本请参见 examples/quickstart.py。

命令行界面

# 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

示例

示例	展示内容
quickstart.py	Hello World —— 用 30 行代码完成写入、读取、搜索和列表操作
kv_config.py	使用 KV 存储管理配置、功能标志和带 TTL 的缓存
version_control.py	版本历史、差异比较和时间回溯读取
file_operations.py	移动、复制、二进制文件和 glob 模式
multi_agent.py	使用共享工作区进行多 Agent 协作
research_agent.py	涵盖所有方法的综合参考示例

参考 Agent

sayou 随附一个参考 Agent 服务端——一个多轮助手，可使用你的工作区进行搜索、读取、写入和调研。这是一个完整可用的示例，展示如何基于 sayou 构建 Agent。

快速开始

# 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

Agent 运行在 http://localhost:9008，并在 POST /chat/stream 提供流式 SSE 端点。

Agent 可以做什么

能力	工作方式
回答问题	优先搜索工作区，找不到时再进行网络搜索
研究主题	进行多次网络搜索，提取事实并保存结构化发现
存储知识	写入包含 YAML frontmatter、章节标题和来源引用的文件
执行代码	可选的 E2B 沙箱，支持 Python 和 bash（设置 SAYOU_AGENT_E2B_API_KEY）

评估 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

架构

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：结构化 Agent 记忆基准

sayou 包含 SAMB——一个用于评估记忆系统在真实 Agent 工作流中表现的开放基准。现有基准（LOCOMO、LongMemEval、DMR）测试对话回忆能力。SAMB 测试 Agent 的实际需求：回忆决策、检索工件内容，以及跨会话关联知识。

SAMB 的衡量内容

维度	测试内容
决策推理	“为什么选择 bcrypt 而不是 Argon2？”
工件内容	“API 文档中有哪些端点？”
跨会话	“会话 3 中的身份验证决策如何影响会话 5 的实现？”
事实回忆	“每月 GCP 成本估算是多少？”
时间信息	“第一次和第二次架构评审之间有什么变化？”

包含 10 个场景、62 个会话和 131 组问答，涵盖 7 种问题类型。每个场景都模拟一个跨多个会话的专业项目（身份验证系统设计、云迁移、电子邮件营销活动、事件响应等），包含真实的对话、决策和工件。

运行基准

# 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

结果将以 JSON 格式保存到 benchmarks/results/，并包含每个问题的完整细分结果。

可用适配器

适配器	系统	检索方式
sayou	sayou 工作区	FTS5 + grep + 文件读取（Agent 式、多工具）
mem0	mem0	大模型事实提取 + 嵌入搜索（Agent 式）
zep	Zep Cloud	知识图谱 + 时间边（Agent 式）
oracle	基准线	直接访问源会话（上限）
no_memory	基准线	不进行检索（下限）

方法

每个适配器都采用 Agent 式检索——由大模型生成多个搜索查询，而不是只进行一次查询。这样每个系统都有公平的机会找到相关信息。

评分：由大模型（gpt-4o-mini）按 0–3 分评分，并归一化为百分比。任务类型问题还会进行整体评分（1–5）和证据覆盖率评估（逐项标记为 FOUND/MISSING）。通过带有 Bonferroni 校正的 bootstrap 置信区间检验统计显著性。

完整方法：benchmarks/dataset/METHODOLOGY.md 数据集卡片：benchmarks/dataset/DATASET_CARD.md

安装选项

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

生产环境部署

用于采用 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": "..."
      }
    }
  }
}

安装所有后端：pip install sayou[all]

存储后端

后端	配置	适用场景
SQLite + 本地磁盘（默认）	无需配置	本地开发、单机 Agent、MCP 服务
MySQL + S3	设置 database_url、S3 凭据	生产环境、多 Agent、共享工作区

故障排除

验证设置

sayou status

这会显示你的工作区路径、数据库位置、存储后端和工具数量。如果一切正常，你会看到 11 tools registered。

常见问题

问题	原因	解决方法
Claude Code 看不到 sayou 工具	未加载 MCP 配置	编辑 ~/.claude/mcp.json 后重启 Claude Code
sayou: command not found	不在 PATH 中	再次运行 pip install sayou，或在 MCP 配置中使用完整路径："command": "/path/to/sayou"
sayou status 显示 0 个工具	服务未初始化	先运行 sayou init，然后检查输出中是否有错误
文件未持久保存	工作区路径错误	检查 sayou status 中的工作区路径——默认路径为 ~/.sayou/
启动时出现导入错误	缺少可选依赖项	安装所需的扩展：pip install sayou[api]、sayou[s3] 或 sayou[all]

获取帮助

• GitHub Issues — 错误报告和功能请求
• CONTRIBUTING.md — 开发环境设置和贡献指南

sayou 不是什么

• 不是向量数据库。 Pinecone、Weaviate 和 Chroma 会存储用于相似性搜索的嵌入。sayou 存储结构化文件，供 Agent 读取、写入和推理。
• 不是记忆层。 Mem0 等工具会存储对话片段。sayou 存储工作成果——研究、客户记录、项目文档——并随时间不断积累。
• 不是沙盒。 E2B 提供临时执行环境。sayou 提供持久存储，其生命周期超出任何单次执行。
• 不是文件系统。 AgentFS 会拦截系统调用，以虚拟化文件操作。sayou 是一个带有版本控制和索引的知识工作区。

理念

阅读 PHILOSOPHY.md，了解创立愿景和设计原则。

贡献

请参阅 CONTRIBUTING.md。

许可证

Apache 2.0 — 参见 LICENSE