Metadata Specification

Version 1.0.0

Comprehensive metadata specification for capturing rich context from AI agents and clients.

Philosophy

Accept ANY metadata agents want to send. Store it all. Analyze later.

We don't know what will be valuable until we have it. More data = better insights, personalization, and debugging capabilities.

Metadata Categories

The metadata object supports 13 categories, all optional. Send as much or as little as your client supports.

1. Client Information

Information about the agent/client making the request.

client: {
  name: "Claude Desktop",           // Client name
  version: "0.7.2",                 // Client version
  platform: "darwin",               // OS platform
  platformVersion: "macOS 14.0",    // OS version
  architecture: "arm64",            // CPU architecture
  locale: "en-US",                  // User locale
  timezone: "America/Los_Angeles"   // User timezone
}

2. Session Information

Track user sessions for analytics and behavior analysis.

session: {
  id: "session-abc123",             // Unique session ID
  startedAt: "2025-10-17T10:30:00Z", // Session start time
  device: {
    type: "desktop",                // desktop | mobile | tablet | web
    model: "MacBook Pro 16-inch",   // Device model
    screen: {
      width: 3456,
      height: 2234,
      pixelRatio: 2
    }
  },
  network: {
    type: "wifi",                   // wifi | cellular | ethernet
    quality: "excellent"            // excellent | good | poor
  }
}

3. Conversation Context

Link snapshots to conversation threads for context continuity.

conversation: {
  threadId: "thread-xyz789",        // Persistent conversation ID
  messageCount: 23,                 // Total messages in thread
  durationMs: 1847000,              // Conversation duration
  model: "claude-3-5-sonnet",       // LLM model used
  temperature: 0.7,                 // Model temperature
  maxTokens: 4096,                  // Max tokens setting
  title: "Debug auth flow",         // Conversation title
  tags: ["auth", "debugging"]       // User-applied tags
}

4. Workspace Context

Capture information about the user's local workspace or project.

workspace: {
  name: "my-saas-app",              // Workspace name
  path: "/Users/dev/project",       // Local path
  type: "code",                     // code | documents | general
  files: {
    total: 247,                     // File count
    extensions: [".ts", ".tsx"],    // File types
    sizeBytes: 8472634              // Total size
  },
  git: {
    branch: "feature/auth",         // Current branch
    commit: "a3f4b2c",              // Current commit
    repo: "github.com/user/repo",   // Remote repository
    hasUncommittedChanges: true     // Dirty working tree
  }
}

5. Content Metadata

Analyze the content being saved for better categorization.

content: {
  language: "en",                   // Primary language
  codeLanguages: ["typescript", "python"], // Code languages
  contentType: "mixed",             // code | docs | chat | notes
  topics: ["auth", "api"],          // Detected topics
  sentiment: "positive",            // positive | neutral | negative
  wordCount: 3420,                  // Word count
  codeBlockCount: 8,                // Number of code blocks
  hasCode: true,                    // Contains code
  hasUrls: true                     // Contains URLs
}

6. Invocation Context

How and why the snapshot was triggered.

invocation: {
  trigger: "manual",                // manual | automatic | scheduled
  source: "toolbar_button",         // UI element that triggered
  userIntent: "save_for_later",     // Why user is saving
  confidence: 0.95,                 // Confidence if automated
  previousActions: ["edit", "run"]  // Recent user actions
}

7. Performance Metrics

Track performance for optimization and debugging.

performance: {
  requestStartMs: 1697562000000,    // Request start timestamp
  networkLatencyMs: 45,             // Network round-trip time
  renderTimeMs: 120,                // UI render time
  memoryUsageMb: 256,               // Client memory usage
  cpuPercent: 15                    // Client CPU usage
}

8. Integration Context

Connected tools and external context.

integrations: {
  connectedTools: ["github", "notion"],  // Connected services
  activePlugins: ["prettier", "eslint"], // Active plugins
  externalContext: {                     // Context from other tools
    github: { pr: "123", repo: "user/repo" }
  }
}

9. Behavioral Data

User behavior patterns for UX improvements.

behavior: {
  recentCommands: ["cmd+k", "explain"],  // Recent commands
  frequentFeatures: ["search", "edit"],  // Most-used features
  sessionActions: [                      // Action timeline
    { action: "edit", timestamp: "..." },
    { action: "run", timestamp: "..." }
  ],
  copyPasteCount: 5,                     // Edits made
  timeOnPage: 847                        // Seconds spent
}

10. Environment Information

Development environment and tooling.

environment: {
  isDevelopment: true,               // Development mode
  isCI: false,                       // CI environment
  nodeVersion: "20.9.0",             // Node version
  installedPackages: [               // Key dependencies
    { name: "next", version: "14.0.4" },
    { name: "react", version: "18.2.0" }
  ]
}

11. Custom Metadata

Extensible field for any client-specific data.

custom: {
  // Anything you want!
  customFeature: "value",
  experimentId: "exp-123",
  internalMetrics: { ... }
}

12. Privacy Settings

User consent and privacy preferences.

privacy: {
  dataCollectionConsent: true,       // User consented to tracking
  analyticsEnabled: true,            // Analytics allowed
  shareWithTeam: true,               // Share in workspace
  anonymize: false                   // Anonymize PII
}

Complete Example

Here's a full example of rich metadata from Claude Desktop:

snapshot-conversation({
  content: "Implemented React hooks for data fetching...",
  highlights: ["useQuery hook", "caching strategy"],
  metadata: {
    client: {
      name: "Claude Desktop",
      version: "0.7.2",
      platform: "darwin",
      architecture: "arm64"
    },
    session: {
      id: "session-abc123",
      startedAt: "2025-10-17T10:30:00Z",
      device: {
        type: "desktop",
        model: "MacBook Pro 16-inch"
      }
    },
    conversation: {
      threadId: "thread-xyz789",
      messageCount: 23,
      durationMs: 1847000,
      model: "claude-3-5-sonnet"
    },
    workspace: {
      name: "my-saas-app",
      path: "/Users/dev/project",
      type: "code",
      git: {
        branch: "feature/data-fetching",
        commit: "a3f4b2c",
        hasUncommittedChanges: true
      }
    },
    content: {
      codeLanguages: ["typescript", "tsx"],
      topics: ["React", "data fetching", "hooks"],
      wordCount: 842,
      codeBlockCount: 5
    },
    invocation: {
      trigger: "manual",
      source: "toolbar_button",
      userIntent: "save_milestone"
    },
    performance: {
      requestStartMs: 1697562000000,
      networkLatencyMs: 45,
      renderTimeMs: 120
    },
    privacy: {
      dataCollectionConsent: true,
      analyticsEnabled: true,
      shareWithTeam: true
    }
  }
})

What We Track

All metadata is stored in JSONB columns for flexible querying:

Database Storage

•client_metadata - Client information
•user_metadata - User details (if provided)
•session_metadata - Session tracking
•conversation_metadata - Thread context
•workspace_metadata - Local workspace info
•content_metadata - Content analysis
•invocation_metadata - Trigger context
•performance_metadata - Performance metrics
•integration_metadata - Connected tools
•behavior_metadata - User behavior
•environment_metadata - Dev environment
•custom_metadata - Custom fields
•privacy_settings - Privacy preferences

Benefits

For Product

• Feature usage analytics
• Client behavior insights
• Content pattern analysis
• Performance monitoring
• User journey mapping

For Engineering

• Debugging context
• Performance optimization
• Error correlation
• Feature targeting
• A/B testing data

For Users

• Personalized experience
• Smart recommendations
• Context reconstruction
• Better search results
• Usage insights

Privacy First

Consent: Always check metadata.privacy.dataCollectionConsent before storing detailed metadata.

Anonymization: If metadata.privacy.anonymize is true, we remove PII like emails, names, and local paths.

Retention: Detailed metadata for non-consented users is automatically deleted after 90 days.