Skip to main content

Structured Data

Store and query JSON documents with metadata.

Data Model​

{
  namespace: string      // Logical grouping
  key: string           // Unique identifier
  data: object          // JSON document
  metadata: object      // Queryable attributes
  version: number       // Version number (auto-incremented)
  is_active: boolean    // Latest version flag
}

Operations​

Save​

Create or update an entry:

await context.call_tool("structured_data_save", {
    "namespace": "products",
    "key": "product:laptop-123",
    "data": {
        "name": "Pro Laptop",
        "price": 1299,
        "specs": {"ram": "16GB", "cpu": "M1"}
    },
    "metadata": {
        "category": "electronics",
        "brand": "Apple",
        "in_stock": True
    }
})

Creates new version, deactivates old version.

Get​

Fetch by key:

product = await context.call_tool("structured_data_get", {
    "namespace": "products",
    "key": "product:laptop-123"
})

# Returns latest active version by default

# Get specific version:
product_v1 = await context.call_tool("structured_data_get", {
    "namespace": "products",
    "key": "product:laptop-123",
    "version": 1
})

Query​

Search by metadata filters:

results = await context.call_tool("structured_data_query", {
    "namespace": "products",
    "filters": {
        "metadata.category": "electronics",
        "metadata.brand": "Apple",
        "metadata.in_stock": True
    }
})

# Returns: [{ namespace, key, data, metadata, version, ... }]

Delete​

Remove an entry (soft delete - keeps history):

await context.call_tool("structured_data_delete", {
    "namespace": "products",
    "key": "product:laptop-123"
})

# Marks all versions as inactive

List Keys​

List keys in namespace:

keys = await context.call_tool("structured_data_list_keys", {
    "namespace": "products",
    "pattern": "product:*"  // Optional: filter by pattern
})

# Returns: ["product:laptop-123", "product:phone-456", ...]

Versioning​

Every update creates a new version:

VersionDatais_active
1{"price": 1299}false
2{"price": 1199}false
3{"price": 999}true

Get always returns latest active unless version specified.

Key Patterns​

Recommended patterns:

  • Entity:ID: user:123, order:abc
  • Hierarchical: config:app:theme, config:app:lang
  • Timestamped: log:2026-07-10:001

Metadata Best Practices​

Use metadata for queryable attributes:

{
  "metadata": {
    "type": "user",           # Entity type
    "status": "active",       # Status
    "region": "us-west",      # Geographic
    "created_at": "2026-07-10",
    "tags": ["premium", "verified"]
  }
}

Query by these attributes efficiently.

Knowledge Scope​

Agents need permission to access namespaces:

{
  "structured_data_namespaces": {
    "products": {
      "keys": ["*"],
      "permission": "read_write"
    }
  }
}

Wildcards:

  • ["*"] - All keys
  • ["product:*"] - Keys starting with product:
  • ["config:*", "user:*"] - Multiple patterns

Next Steps​