Satchel v0.2.0

Satchel 0.2.0

Eval suites can now run on a schedule, and a GitHub Action previews context repo pull requests,
runs the publish gate on them and publishes on merge.

Status: pre-alpha. Expect breaking changes between 0.x releases.

Install

uv tool install satchel-server     # or: uv tool upgrade satchel-server
satchel init --example jaffle
satchel up

Container image and Helm chart:

docker pull ghcr.io/getsatchel/satchel:0.2.0
helm install satchel oci://ghcr.io/getsatchel/charts/satchel --version 0.2.0 -n satchel --create-namespace -f my-values.yaml

This release ships with satchel-adapter-sdk 1.2.1 (IR 1.0.0).

New

• Scheduled eval runs. Add schedule: { interval_hours: N } to a suite and satchel worker
  runs it against the latest published release every N hours, on its own thread
  (SATCHEL_EVAL_TICK_MIN, default 15; 0 turns it off). The Suites tab shows the schedule and
  the next run, Run history labels scheduled and gate runs, and a scheduled run links
  Compare with previous. A suite that needs an LLM is skipped while no model is configured.
  See Evals.
• GitHub Action (getsatchel/satchel/action@v0.2.0). On a pull request it uploads the context
  folder, gets a preview, runs the gate's suites, comments the comparison and fails the check on
  a regression. On a push to the default branch it imports and publishes. See
  GitHub Action.
• Context repo uploads.
  • POST /v1/sync/preview (curator) builds a pull-request preview without changing drafts or
    what is served. Such previews are published by merging, not from the UI.
  • POST /v1/sync/import (admin) is satchel sync import over HTTP. Sources declared in the
    config are not synced from an upload.
  • Both calls are audited as sync.preview and sync.import.
• Evals documentation. Evals covers suites, graders, runs, the
  publish gate and schedules.

Changes

• Eval suite files whose names start with . (for example macOS ._* metadata) are ignored on
  import.
• New context versions are numbered after the highest existing one, so they never collide with
  versions a pull-request preview created.
• CI runs only the jobs a pull request can affect (contributors).

Upgrading from 0.1.1

uv tool upgrade satchel-server
satchel db upgrade

The migration 0013 adds release.ref. Run satchel db upgrade (or let the Helm chart's
migration job run) before starting the new version. The worker starts the eval schedule thread
by default; suites run on a schedule only once you add schedule: to them, so nothing changes
until then.

Satchel v0.1.1

Satchel 0.1.1

Satchel is now on PyPI as satchel-server, and the package includes the built curator UI.

Status: pre-alpha. Expect breaking changes between 0.x releases.

Install

uv tool install satchel-server     # the command is still `satchel`
satchel init --example jaffle
satchel up

Container image and Helm chart:

docker pull ghcr.io/getsatchel/satchel:0.1.1
helm install satchel oci://ghcr.io/getsatchel/charts/satchel --version 0.1.1 -n satchel --create-namespace -f my-values.yaml

This release ships with satchel-adapter-sdk 1.2.1 (IR 1.0.0).

Changes

• Published to PyPI as satchel-server. The PyPI name satchel belongs to an unrelated project. Only the package name changed: the command is satchel and the import package is satchel, as before.
• The UI is included. A 0.1.0 install from git had no built UI, so satchel up showed a "no built curator UI" page. The PyPI wheel is built after the UI and bundles it.
• Install hints no longer point at the wrong package. Messages about missing extras (S3, GCS, BigQuery, Snowflake, connection kinds, built-in source adapters) and the pip branch of satchel upgrade said pip install satchel, which would have installed the unrelated project. They now say satchel-server[<extra>]==<version>.
• Release notes links work on GitHub. The release page now links to the docs of the tagged version.

Upgrading from 0.1.0

If you installed 0.1.0 with uv tool install "satchel @ git+…", switch to the PyPI package once:

uv tool uninstall satchel && uv tool install satchel-server
satchel db upgrade

Your config and the MCP client entries written by satchel connect keep working: the command is still satchel,
at the same path. There are no database migrations in this release. Container and Helm users only need to move to
0.1.1.

Satchel v0.1.0

Satchel 0.1.0

The first release of Satchel, an open-source, self-hosted context server for data agents. Bring your own agent
(Claude, Claude Code, Cursor, ChatGPT, Codex), connect it over MCP, and Satchel serves curated, versioned,
permissioned context about your data. It also learns from how agents use that context and turns what they
struggle with into changes that analysts review.

Status: pre-alpha. Expect breaking changes between 0.x releases, and do not rely on it in production yet.

Install

Locally, with uv and Docker:

uv tool install "satchel @ git+https://github.com/getsatchel/satchel@v0.1.0#subdirectory=server"
satchel init --example jaffle
satchel up
satchel connect claude-desktop

Container image and Helm chart:

docker pull ghcr.io/getsatchel/satchel:0.1.0
helm install satchel oci://ghcr.io/getsatchel/charts/satchel --version 0.1.0 -n satchel --create-namespace -f my-values.yaml

See Install and get started and the self-hosting overview.

What's in it

Context for agents

• Guides, glossary terms, metrics, golden queries, table docs and endorsements, each versioned and published in releases with preview, publish and rollback.
• MCP over Streamable HTTP (/mcp) and stdio. Tools for context (search_context, get_context_pack, get_item, list_tables, describe_table), sessions (start_analysis, report_answer), governed metrics and guarded SQL (list_metrics, describe_metric, query_metrics, run_sql, get_result) and feedback (flag_context_gap, record_user_feedback, propose_context_change). See MCP tools.
• An MCP Apps result widget for query results.
• Hybrid search, with fastembed (local), hash (offline) or OpenAI-compatible embeddings.

The curation loop

• Records sessions, tool traces, flagged gaps and user feedback.
• A worker embeds signals, runs hygiene checks (stale, dead, duplicate and contradictory items, shared memories), clusters gaps and has a chat model draft concrete changes.
• Nothing is published automatically: every suggestion and agent proposal goes to the Inbox for a curator to review, then through preview and publish.

Evals and the publish gate

• Eval suites in YAML with a reference agent and graders (numeric_value, sql_equivalent, context_used, judge_final_answer, judge_session), run history and run comparison.
• An optional publish gate (publish.require_evals) that runs suites against a preview release before it can be published.

Sources

• Context from dbt, Cube and SQLMesh, and from files in a git repository, with scheduled syncs and push webhooks. Source-managed items get a read-only source block and an overlay editor.
• satchel-adapter-sdk for writing your own adapters (guide). This release ships with SDK 1.2.1 (IR 1.0.0).
• Warehouse connections for PostgreSQL, DuckDB, BigQuery and Snowflake, with guarded read-only SQL, governed metric queries and a catalog crawler.

The curator UI

• Inbox, Library, Changes, Releases, Sessions, Observability, Catalog, Sources, Evals and Settings, served by the API at /.

Security and operations

• Postgres (17, with pgvector) is the only required dependency. Workspace data is isolated with forced row-level security, and the app connects as a non-superuser role.
• OIDC sign-in, OAuth 2.1 for MCP clients, and personal access tokens.
• Evidence sent to models is redacted; audit events can be exported as JSONL to gs://, s3:// or a file.
• Deployment: one container image for every role, a Helm chart for any Kubernetes 1.29+ cluster, and Terraform for GKE, EKS and Cloud Run.

Known limitations

• Pre-alpha: the API, the MCP tools and the database schema can change between 0.x releases. Migrations run in place (satchel upgrade, or the Helm pre-upgrade hook), but back up first.
• Planned and not in this release: scheduled eval runs, a GitHub Action for evals and the publish gate, memory building, and a pgmq job queue. See the architecture diagram for status.