# sayou

A file-based workspace where an AI agent keeps notes, settings and research between sessions as versioned markdown files.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 28
- Author: pixell-global
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/pixell-global/sayou
- Updated: 2026-05-05
- HTML: https://affpapa.org/en/nevibecode/mcp/sayou

## What it does

sayou hands the agent a workspace of markdown files carrying YAML frontmatter. Writes are append-only: each edit becomes a new version, the previous one stays, and you can diff any two of them. Reads take a `token_budget`, so a long file comes back as summaries with pointers to sections instead of the whole thing.

The server exposes 11 MCP tools — write, read, list, full-text and frontmatter search, glob, grep, soft delete, version history, a key-value store with optional TTL, file links for a knowledge graph, and chunk access. A twelfth, `workspace_semantic_search`, appears only when `SAYOU_EMBEDDING_PROVIDER` is set.

Two install routes exist. The Claude plugin ships lifecycle hooks plus the `/ws`, `/save` and `/recall` skills, and pulls in sayou itself on first run if it is missing. Installing through pip gives you the MCP tools alone, with no hooks or skills. Python 3.11 or newer is required either way. Run `sayou status` to confirm: it prints the workspace path, the database location and how many tools registered.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add sayou -- uvx sayou
```
uvx runs the command named after the package; if the README names another one, use uvx --from sayou <command>

### Codex

**Platform CLI**
```bash
codex mcp add sayou -- uvx sayou
```
uvx runs the command named after the package; if the README names another one, use uvx --from sayou <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "sayou": {
            "command": "uvx",
            "args": [
                "sayou"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from sayou <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "sayou": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "sayou"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from sayou <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add sayou uvx sayou
```
uvx runs the command named after the package; if the README names another one, use uvx --from sayou <command>

## When to use it
- keep research findings alive after the session that produced them ends
- locate a note by its frontmatter metadata instead of its filename
- diff two versions of a document and see exactly what changed
- park agent settings in a key-value store with an expiry
- link files together into a knowledge graph

## Example prompts
- Search for anything tagged status: draft
- Show me the diff between versions of `research/competitor-pricing.md`

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md