Skip to main content

​
What it does

Creates a named snapshot of current memory state, optionally including specific memories. Use at project milestones, before risky changes, or when you want a labeled restore point. Checkpoints are immutable and can be listed and reviewed later. Supports two modes: create (capture a snapshot) and list (retrieve past checkpoints).

​
Parameters

ParameterTypeRequiredDefaultDescription
modestringNo”create”Checkpoint mode: create (save snapshot) or list (retrieve checkpoints).
labelstringConditional—Checkpoint name/title. Required when mode="create". Should be descriptive: “Implemented vector search”, “Before auth refactor”, etc.
descriptionstringNo—Longer description of what this checkpoint captures or why it’s significant.
memoryIdsarrayNo—Array of specific memory IDs to include in checkpoint. If omitted, includes all memories in the scope (channel/session).
sessionIdstringNo—Scope checkpoint to a specific session. Used in list mode to filter checkpoints.
semanticSummarystringNo—AI-generated or manual semantic summary of the checkpoint’s significance.
tagsarrayNo—Array of tag strings for organizing checkpoints (e.g., ["release", "v0.8", "production"]).
limitnumberNo20In list mode: maximum number of checkpoints to return. Range: 1-100.
createdBystringNo—Identifier for who created this checkpoint: gerald or andy.
channelstringNo—Scope checkpoint to a specific channel. Used in both create and list modes.

​
Returns (Create mode)

{
  "checkpointId": "string",
  "mode": "create",
  "label": "string",
  "createdAt": 1234567890000,
  "memoryCount": number
}

​
Returns (List mode)

[
  {
    "checkpointId": "string",
    "label": "string",
    "description": "string",
    "createdAt": 1234567890000,
    "createdBy": "gerald|andy",
    "channel": "string",
    "memoryCount": number,
    "tags": ["string"]
  }
]
Field descriptions:
  • checkpointId — Unique identifier for the checkpoint
  • label — Human-readable name
  • createdAt — Unix milliseconds when checkpoint was created
  • memoryCount — Number of memories included in the checkpoint
  • tags — Optional tags for filtering and organization

​
Examples

​
Basic usage

// Create a checkpoint after implementing a major feature
crystal_checkpoint({
  mode: "create",
  label: "Implemented semantic search via embeddings"
})

// Result: { 
//   checkpointId: "cp_abc123def456",
//   mode: "create",
//   label: "Implemented semantic search via embeddings",
//   createdAt: 1713283200000,
//   memoryCount: 42
// }

​
Advanced usage

// Create a detailed checkpoint with description and tags
crystal_checkpoint({
  mode: "create",
  label: "Release v0.8.0 — Vector search ready",
  description: "All vector search infrastructure implemented and tested. Dashboard updated. Docs written. Ready for production deploy.",
  tags: ["release", "v0.8", "stable"],
  channel: "main"
})

// List all checkpoints
crystal_checkpoint({
  mode: "list",
  limit: 50
})

// List checkpoints from a specific session
crystal_checkpoint({
  mode: "list",
  sessionId: "session_xyz789",
  limit: 20
})

// List checkpoints with a specific tag
crystal_checkpoint({
  mode: "list",
  limit: 30,
  channel: "claude-code"
})

// Create checkpoint with specific memories
crystal_checkpoint({
  mode: "create",
  label: "Before auth system refactor",
  description: "Saved auth decisions before rearchitecting from JWT to session-based",
  memoryIds: ["mem_auth1", "mem_auth2", "mem_auth3"],
  tags: ["auth", "refactor"]
})

​
When to use this vs alternatives

  • crystal_checkpoint — When you want to save a named snapshot of memory state at a milestone
  • crystal_capture — When you want to save a single memory immediately
  • crystal_recent — When you need to see recent conversation messages, not checkpoint history

​
Error handling

ErrorCauseResolution
”Invalid arguments”args is not an objectPass a valid object
”mode must be create or list”Invalid mode valueUse either "create" or "list"
”label is required for create mode”label missing when mode=“create”Provide a non-empty label string
”limit must be a number”limit is provided but not numericOmit or provide a number in range 1-100
”memoryIds must be array of ids”memoryIds is not an arrayProvide an array of strings (can be empty)
“channel must be a string”channel is not a stringProvide a string or omit
API connection errorConvex endpoint unavailableRetry; check CONVEX_URL environment variable

​
Notes

  • Checkpoints are immutable — once created, they cannot be modified
  • Labels should be descriptive and action-oriented (✅ “Implemented vector search” vs ❌ “checkpoint 42”)
  • Tags are lightweight and support filtering checkpoints by theme or project
  • Scoping by session, channel, or explicit memoryIds lets you create focused checkpoints
  • List mode supports pagination via limit parameter
  • Checkpoints are useful before risky changes (auth refactors, migrations, schema changes)
  • Use descriptions to explain WHY a checkpoint was created or what state it represents
  • The createdBy field helps track who made each checkpoint (useful in multi-user contexts like Gerald and Andy)