sayou

sayou

AI エージェントのためのファイルシステムに着想を得たコンテキストストア。

ウェブ時代のデータベースを置き換えるために作られました。オープンソース。ファイルファースト。SQL 互換。

データベースはトランザクションのために設計されました — スキーマに収めるためにニュアンスを切り捨てます。エージェントは深く考えますが、セッションが終わるとすべてを忘れてしまいます。sayou は、推論が持続し、コンテキストが蓄積し、知識が時間とともに複利で積み上がる場所です。

• データベースが保持できないものを保持するファイル — 構造にはフロントマター。コンテキストには Markdown。バージョン管理済み。監査可能。
• 1 回の読み取り。完全なコンテキスト。 — すべての読み取りは token_budget を受け付けます。コンテンツが予算を超える場合は、セクションポインタ付きの要約を返します。
• 複利で積み上がる知識 — 追記のみのバージョン履歴。すべての変更が新しいバージョンです。完全な監査証跡とタイムトラベル読み取り。
• あらゆるエージェントが接続可能 — MCP サーバー、Python ライブラリ、またはコマンドライン。pip install sayou[api] によるオプションの REST API。

クイックスタート

Claude Code (推奨)

Claude Code 内から:

/plugin install sayou@pixell-global

またはターミナルから:

claude plugin install sayou@pixell-global

コマンド 1 つ。これにより、ライフサイクルフック (セッション開始時のワークスペースコンテキスト、パッシブなアクティビティキャプチャ、セッションサマリー) とスキル (/ws、/save、/recall) を備えたプラグインがインストールされます。sayou がまだインストールされていない場合、プラグインは初回実行時に自動インストールします。

クラウドモード: Sayou Drive 経由でワークスペースを同期するには、インストール後に sayou auth を実行し、設定 から 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 ツールをトリガーします — 上記のクイックスタート以外のセットアップは不要です。

プロンプト	何が起こるか	ツール
"Save a note about our Q1 goals with status: draft"	YAML フロントマター付きのバージョン管理されたファイルを作成します	workspace_write
"What files are in my workspace?"	すべてのファイルとサブフォルダを一覧表示します	workspace_list
"Search for anything tagged status: draft"	フロントマターのメタデータでファイルをフィルタリングします	workspace_search
"Read the Q1 goals note"	トークン予算を考慮してファイルの内容を取得します	workspace_read
"Update the status to reviewed"	新しいバージョンを書き込みます (古いバージョンは保持されます)	workspace_write
"Show me the diff between versions"	2 つのバージョンを unified diff で比較します	workspace_history
"Store a setting: theme = dark"	キーと値のペアを保存します (オプションの TTL 付き)	workspace_kv
"Find all markdown files in research/"	glob パターンでファイルを照合します	workspace_glob
"Search file contents for the word 'budget'"	コンテキスト付きの grep 形式のコンテンツ検索	workspace_grep

すべての書き込みが新しいバージョンを作成します。何も上書きされません。いつでも元に戻せます。

どのように見えるか

セッションをまたいだ sayou の動作を示す短い会話です:

---

あなた: エンタープライズ向けプランの競合他社の価格を調査して、結果を保存してください。

Claude Code: 調査して、結果をワークスペースに保存します。

[workspace_write を使用して research/competitor-pricing.md を作成]

フロントマター付きで research/competitor-pricing.md に保存しました: status: draft、topic: competitor-pricing

---

あなた (翌日、新しいセッション): 競合他社の価格について何が分かりましたか？

Claude Code: ワークスペースを確認します。

[クエリ「competitor pricing」で workspace_search を使用]

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

これにより、現在の作業ディレクトリの .cursor/mcp.json に sayou が追加されます。

Windsurf

sayou init --windsurf

これにより、~/.codeium/windsurf/mcp_config.json に sayou が追加されます。

MCP 互換の任意のクライアント

sayou は標準的な MCP サーバーです。sayou init（フラグなし）を実行して設定スニペットを取得し、エディターの MCP 設定に貼り付けてください。エントリは常に同じで、"command": "sayou" だけです。

MCP ツール

エージェントは 11 個のツールを利用できます（埋め込みを有効にすると 12 個）:

ツール	説明
workspace_write	ファイルを作成または更新します（テキスト、または YAML フロントマター付きのバイナリ）
workspace_read	最新バージョンまたは特定のバージョンを、任意の行範囲指定付きで読み取ります
workspace_list	自動生成されたインデックス付きでファイルとサブフォルダーを一覧表示します
workspace_search	全文クエリ、フロントマターフィルター、またはチャンク単位で検索します
workspace_delete	ファイルをソフト削除します（履歴は保持されます）
workspace_history	タイムスタンプ付きのバージョン履歴、または 2 つのバージョン間の差分を表示します
workspace_glob	glob パターンに一致するファイルを検索します
workspace_grep	前後の文脈行付きでファイルの内容を検索します
workspace_kv	キー・バリューストア（任意の TTL 付きで get/set/list/delete）
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 を参照してください。

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

例

例	示す内容
quickstart.py	Hello World — 30 行で write、read、search、list
kv_config.py	設定、機能フラグ、TTL 付きキャッシュのための KV ストア
version_control.py	バージョン履歴、差分、タイムトラベル読み取り
file_operations.py	移動、コピー、バイナリファイル、glob パターン
multi_agent.py	共有ワークスペースによるマルチエージェント協調
research_agent.py	すべてのメソッドを網羅 — 包括的なリファレンス

リファレンスエージェント

sayou にはリファレンスエージェントサーバーが同梱されています — ワークスペースを使って検索、読み取り、書き込み、調査ができるマルチターンのアシスタントです。これは sayou 上でエージェントを構築する完全な動作例です。

クイックスタート

# 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

エージェントは http://localhost:9008 で動作し、POST /chat/stream にストリーミング SSE エンドポイントがあります。

エージェントにできること

機能	動作方法
質問に回答する	まずワークスペースを検索し、見つからない場合は Web 検索にフォールバックします
トピックを調査する	複数の Web 検索を実行し、事実を抽出し、構造化された調査結果を保存します
ナレッジを保存する	YAML フロントマター、セクション見出し、出典引用を含むファイルを書き込みます
コードを実行する	Python および bash 用のオプションの E2B サンドボックス (SAYOU_AGENT_E2B_API_KEY を設定)

エージェントを評価する

# 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: Structured Agent Memory Benchmark

sayou には SAMB が含まれています — 実際のエージェントワークフローでメモリシステムを評価するためのオープンなベンチマークです。既存のベンチマーク (LOCOMO、LongMemEval、DMR) は会話の想起をテストします。SAMB はエージェントが実際に必要とするもの、すなわち意思決定の想起、成果物の内容の取得、セッションをまたいだナレッジの接続をテストします。

SAMB が測定するもの

次元	テストする内容
意思決定の推論	「なぜ Argon2 ではなく bcrypt が選ばれたのか?」
成果物の内容	「API ドキュメントにはどのようなエンドポイントがあるか?」
セッション横断	「セッション 3 の認証の決定はセッション 5 の実装にどう影響するか?」
事実の想起	「月間の GCP コスト見積もりはいくらだったか?」
時間的変化	「最初と 2 回目のアーキテクチャレビューの間で何が変わったか?」

7 種類の質問タイプにわたる 10 シナリオ、62 セッション、131 の QA ペア。各シナリオは、現実的な会話、意思決定、成果物を伴う複数セッションのプロフェッショナルプロジェクト (認証システム設計、クラウド移行、メールキャンペーン、インシデント対応など) をシミュレートします。

ベンチマークを実行する

# 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 workspace	FTS5 + grep + ファイル読み取り (エージェント的、マルチツール)
mem0	mem0	LLM による事実抽出 + 埋め込み検索 (エージェント的)
zep	Zep Cloud	ナレッジグラフ + 時間的エッジ (エージェント的)
oracle	ベースライン	ソースセッションへの直接アクセス (上限)
no_memory	ベースライン	検索なし (下限)

方法論

各アダプターはエージェント的検索を使用します — LLM が単発の検索ではなく複数の検索クエリを生成します。これにより、すべてのシステムが関連情報を見つける公平な機会を得られます。

スコアリング: LLM による判定 (gpt-4o-mini) を 0〜3 のスケールで行い、パーセンテージに正規化します。タスクタイプの質問では、全体的なスコアリング (1〜5) とエビデンスカバレッジ (項目ごとの FOUND/MISSING) が追加されます。統計的有意性は、Bonferroni 補正を伴うブートストラップ信頼区間によって算出します。

完全な方法論: 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 + ローカルディスク (デフォルト)	設定不要	ローカル開発、単一マシンのエージェント、MCP サーバー
MySQL + S3	database_url、S3 認証情報を設定	本番環境、マルチエージェント、共有ワークスペース

トラブルシューティング

セットアップを確認する

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/ です
起動時のインポートエラー	オプションの依存関係が不足している	必要な extra をインストールしてください: pip install sayou[api]、sayou[s3]、または sayou[all]

ヘルプを得る

• GitHub Issues — バグ報告と機能リクエスト
• CONTRIBUTING.md — 開発環境のセットアップとコントリビューションガイド

sayou ではないもの

• ベクトルデータベースではありません。 Pinecone、Weaviate、Chroma は類似検索用の埋め込みを保存します。sayou はエージェントが読み取り、書き込み、推論する構造化ファイルを保存します。
• メモリレイヤーではありません。 Mem0 や同様のツールは会話の断片を保存します。sayou は作業成果物 — リサーチ、顧客記録、プロジェクトドキュメント — を保存し、それらは時間とともに蓄積されます。
• サンドボックスではありません。 E2B は一時的な実行環境を提供します。sayou は単一の実行を超えて存続する永続ストレージを提供します。
• ファイルシステムではありません。 AgentFS はシステムコールをインターセプトしてファイル操作を仮想化します。sayou はバージョニングとインデックスを備えたナレッジワークスペースです。

哲学

設立のビジョンと設計原則については PHILOSOPHY.md をお読みください。

コントリビューション

CONTRIBUTING.md をご覧ください。

ライセンス

Apache 2.0 — LICENSE をご覧ください