Vault write gateway and knowledge compiler.

---

matcha is the unified write entry point for an Obsidian vault. It accepts content from any source — supervisor sessions, web clips, Feishu messages, manual notes — formats it with proper frontmatter, and writes it atomically to the correct vault location.

Install

brew tap eggyShrimp/tap
brew install matcha

Or build from source.

Role in the system

supervisor ──┐
feishu ──────┤
web clip ────┤──→ matcha write ──→ vault/raw/
manual ──────┘                         │
                                       │
                              matcha compile
                                       │
                                       v
                               vault/wiki/
                                       │
                              pearl search ──→ supervisor

Tool	Responsibility
supervisor	Works, reflects, summarizes experience, sends to matcha
matcha	Receives writes, formats, deduplicates, stores; compiles raw notes into wiki pages
pearl	Searches vault, returns relevant context to supervisor

CLI

matcha write    Write content to the vault (stdin body + JSON metadata)
matcha init     Create ~/.config/matcha/config.toml
matcha config   Print resolved vault configuration
matcha status   Check whether matcha can write to the vault
matcha compile  Compile raw fragments into structured wiki pages

Usage

# Supervisor sends a decision
echo "选择 Rust 重写 matcha" | matcha write \
  --meta '{"type":"decision","title":"use Rust for matcha","project":"matcha","source":"session:abc","tags":["architecture","rust"]}'

# Web clip
curl -s "https://..." | defuddle | matcha write \
  --meta '{"type":"clip","title":"Rust Error Handling","source":"url:https://..."}'

# Feishu message
echo "部署用 k8s" | matcha write \
  --meta '{"type":"note","source":"feishu:msg_xxx","tags":["deploy"]}'

# Quick thought
echo "明天检查 CI" | matcha write --meta '{"tags":["todo"]}'

Output (JSON on stdout):

{
  "status": "written",
  "output_path": "/vault/raw/matcha/2026-05-19-use-Rust-for-matcha-beaa5864.md",
  "fingerprint": "beaa5864..."
}

Routing

• With "project":"X" in --meta → raw/<X>/YYYY-MM-DD-<title>-<hash>.md
• Without project → raw/inbox/YYYY-MM-DD-<title>-<hash>.md

Compile

Compile all raw notes into wiki/<project>.md pages:

matcha compile

Human-readable mode shows progress while it runs: scanning raw notes, grouping candidates by project/wiki/tag structure, agent read steps, skips, and writes. --json keeps stdout machine-readable and only prints the final JSON result. Add --debug to print agent turns and tool arguments to stderr while keeping stdout usable.

compile is not a general article summarizer. Isolated raw notes that do not match a project, existing wiki page, or stable tag stay in raw/ until they gain enough structure to become wiki candidates.

compile runs a Pi agent. Configure the model before writing wiki pages:

matcha init --vault-dir "$HOME/Documents/vault" --provider openai --model gpt-4o

This writes ~/.config/matcha/config.toml. You can edit the file and add api_key, or keep the key in an environment variable such as MATCHA_MODEL_API_KEY.

Preview without writing:

matcha compile --dry-run

Compile one project and print JSON:

matcha compile --project matcha --json

Debug a compile run:

matcha compile --project matcha --debug

Configuration

matcha init --vault-dir "$HOME/Documents/vault" --model gpt-4o

Default config file:

vault_dir = "/Users/me/Documents/vault"

[model]
provider = "openai"
name = "gpt-4o"
# api_key = ""
# base_url = "https://api.openai.com/v1"
context_window = 128000
max_tokens = 8192
thinking = "medium"

[compile]
max_turns = 12

Environment variables can still override the config file, for example:

export MATCHA_MODEL_API_KEY="..."
export MATCHA_MODEL_NAME="gpt-4o"
export MATCHA_VAULT_DIR="$HOME/Documents/vault"

Vault path resolution order:

1. MATCHA_VAULT_DIR
2. ~/.config/matcha/config.toml
3. pearl config --json
4. ~/.config/pearl/config.toml
5. ~/.config/pearl/state.json

Use human-readable output by default:

matcha config
matcha status

Use JSON output for scripts:

matcha config --json
matcha status --json

Development

cargo build
cargo test
cargo clippy

License

MIT