hutch

Hutch — Structured Data Storage for AI Agents

Hutch stores structured data as JSON records in collections. No schema required — just store data and query it later.

Core Workflow: list → describe → query

Always follow this progression when answering questions about existing data:

1. List collections first to see what exists (list_collections)
2. Describe a collection to understand its fields and types before querying (describe_collection)
3. Query with the right filters/search based on field types from describe (query_records)

Available MCP Tools

Storing Data

• store_records — Create or upsert records. Auto-creates the collection if it doesn't exist.
  • Single record: { collection: "name", data: { field: "value" } }
  • Bulk: { collection: "name", records: [{ ... }, { ... }] }
  • Upsert: set unique_key on the collection first, then use on_conflict: "merge" | "replace" | "skip" | "error"

Reading Data

• list_collections — List all collections with record counts
• get_collection — Get collection details (settings, schema, unique key)
• describe_collection — Field names, types, sample values, and stats. Always call this before querying so you know whether to use filter (exact/numeric) or search (text).
• query_records — Query with filter, search, sort, group_by, aggregate, time_bucket, limit, offset
• search — Global full-text search across all collections

Managing Data

• update_collection — Update collection settings (published, unique_key, schema, display options)
• delete_collection — Delete an entire collection
• delete_record — Delete a single record by ID

Query Strategy

• Filter (filter): exact value match — use for structured fields (boolean, number, enum/select values)
• Search (search): free text across all text fields
• Both: combine for precision — filter narrows, search finds within the results
• Sort: prefix with - for descending (e.g., -created_at)
• Aggregate: count, sum, avg, min, max on fields
• Time bucket: group by time intervals for time-series data

Check the describe_collection tool to know whether a field is numeric (safe for filter/comparison) or string (use search).

Presenting Results

• < 10 results: show as formatted table
• 10-100 results: summarize + show top entries
• Aggregation: present as summary list or chart description
• No results: mention what's in the collection and suggest a broader search

When to Proactively Offer Hutch

If the user generates structured output during a conversation — scraped data, API responses, computed tables, research results — offer to store it in Hutch so they can query it later. Example: "Would you like me to save these results to a Hutch collection so you can query them later?"