Sparkle

Sparkle makes your AI slow down and work with you instead of jumping ahead on its own. It learns how you like to work - your preferences, your patterns, your style - and stores that over time so every session gets better, not just the current one.

What is Sparkle?

Under the hood, Sparkle is an identity and context framework. It provides collaboration patterns (how the AI should think and respond), persistent memory (what you’ve worked on and how you work), and tools for managing that context over time. Think of it as giving your AI a working relationship with you instead of starting from scratch every session.

Getting Started

Ready to begin? Check out the Getting Started Guide to install and configure Sparkle.

Once you’re set up:

• Prompt Reference - Learn what to say to interact with Sparkle
• Tool Reference - Understand how the system works under the hood
• Core Identity - Discover what makes Sparkle different

Core Identity Overview

Content coming soon…

Getting Started

Prerequisites

• Rust (1.70 or later) - Install from rustup.rs
• An MCP-compatible client or an ACP-compatible agent

Installation

cargo install sparkle-mcp

This installs sparkle-mcp to ~/.cargo/bin/, which should already be in your PATH if you installed Rust via rustup.

Setup for MCP

Add Sparkle to your MCP client configuration:

{
  "mcpServers": {
    "sparkle": {
      "command": "sparkle-mcp"
    }
  }
}

Refer to your MCP client’s documentation for the configuration file location.

To start a Sparkle session, use the @sparkle prompt. This loads your collaboration identity, patterns, and workspace context.

Setup for ACP

Run Sparkle as an ACP component:

sparkle-mcp --acp

In ACP mode, Sparkle automatically loads your collaboration identity into the first prompt of each session. No manual activation needed. See the ACP Component guide for details.

First-Time Setup

Start your first Sparkle session with the @sparkle prompt. Sparkle will ask for your name, create your ~/.sparkle/ profile directory, and introduce itself. From then on, every session starts the same way - use @sparkle and Sparkle picks up where you left off.

After your first session, you can enrich your collaborator profile to help Sparkle understand how you work:

• Edit ~/.sparkle/collaborator-profile.md to add your working style, technical expertise, and collaboration preferences
• Use the fetch_profile_data tool to pull information from your GitHub profile, blog, or website

Next Steps

• Checkpointing - How Sparkle maintains context across sessions
• Tool Reference - All available Sparkle tools
• ACP Component - Running Sparkle in agent composition chains
• Core Identity - What makes Sparkle different

Troubleshooting

Server Not Found

If your client can’t find Sparkle:

• Verify ~/.cargo/bin is in your PATH: echo $PATH
• Try running sparkle-mcp directly to test
• Check your MCP configuration file for typos

Profile Issues

If Sparkle can’t load your profile:

• Verify ~/.sparkle/ directory exists
• Check that collaborator-profile.md is present and readable
• Use the setup_sparkle tool to reinitialize if needed

Sparkle Modes

Sparkle defaults to full mode, which persists workspace state (working memory, checkpoints, exchange logs) in a .sparkle-space/ directory in your working directory.

Core mode disables workspace persistence entirely. Your Sparkler identity and collaboration profile (~/.sparkle/) still work — you just don’t get .sparkle-space/, checkpoints, or exchange logging.

This is useful when you manage persistence through other tools, or when writing state to your working directory isn’t desirable.

Usage

MCP

{
  "mcpServers": {
    "sparkle": {
      "command": "sparkle-mcp",
      "args": ["--mode", "core"]
    }
  }
}

ACP

sparkle-mcp --acp --mode core

The default is full if --mode is not specified.

Prompt Reference

Prompts are what you say to interact with Sparkle. These trigger specific behaviors and patterns.

MCP Prompts

These are registered prompts that directly trigger specific tools. In Q CLI, invoke them with @ (e.g., @sparkle). Other MCP clients may use different syntax (e.g., /sparkle in Claude Code).

sparkle

Activates the Sparkle identity and loads all collaboration patterns.

When to use: At the start of each session.

What happens:

• On first use: Sparkle asks for your name and sets up the ~/.sparkle/ directory structure
• On subsequent uses: Sparkle loads your profile and activates all collaboration patterns

Example (Q CLI):

@sparkle

checkpoint

Creates a session checkpoint to preserve progress and enable continuity.

When to use: When you want to save the current session state for the next Sparkle incarnation.

What happens:

• Sparkle reflects on the session (accomplishments, decisions, insights)
• Updates working-memory.json with current focus and next steps
• Creates a checkpoint file with narrative handoff for the next session

Note: Sparkle may also suggest creating a checkpoint when it makes sense to preserve session progress.

Example (Q CLI):

@checkpoint

show_thinking (Q CLI only)

Makes Sparkle’s internal reasoning process visible in responses.

When to use: When you want to see how Sparkle is thinking through problems.

What happens:

• Sparkle adds a “My Thinking Process” section to each response
• Shows the reasoning that happens before the main answer
• Continues for the rest of the session

To stop: Just ask Sparkle to stop showing thinking.

Note: This prompt is specific to Q CLI and may not work in other MCP clients.

Example (Q CLI):

@show_thinking

Natural Language Patterns

These are phrases Sparkle recognizes from its collaboration identity. You can say them naturally in conversation.

meta moment

Pauses current work to examine and capture collaboration patterns.

When to use: When you notice something interesting about how you’re working together that’s worth preserving.

What happens:

• Sparkle pauses the current task
• Examines what just happened and why it worked (or didn’t)
• Captures insights as pattern anchors or breakthrough discoveries
• Returns to previous work

Note: Sparkle may also initiate meta moments when recognizing significant collaboration patterns.

Example:

meta moment

Enriching Your Profile

You can ask Sparkle to help enhance your collaborator profile with information from external sources.

Examples:

Add my GitHub profile to my collaborator profile (username: yourusername)

Add my blog to my profile (RSS feed: https://yourblog.com/feed)

What happens:

• Sparkle fetches information from the source
• Presents formatted content for you to review
• You can integrate it into your profile

Creating Additional Sparkler Identities

If you want to experiment with multiple Sparkler identities (advanced/experimental feature):

Example:

I'd like to create a new Sparkler named Banana

What happens:

• Sparkle creates a new identity with that name
• Sets up directory structure and starter files
• You can switch between identities in future sessions

Checking Available Sparklers

Example:

Show me my Sparkler identities

What happens:

• Lists all your Sparkler identities
• Shows which one is set as default

Typical Session Flow

1. @sparkle                    # Start session (MCP prompt)
2. [collaborative work]        # Work together
3. meta moment                 # Capture insights (natural language)
4. @checkpoint                 # Save progress (MCP prompt)

Understanding Prompts vs Tools

MCP Prompts are registered in the server and directly trigger specific tools. The syntax for invoking them depends on your MCP client (Q CLI uses @, Claude Code uses /).

Natural Language Patterns are phrases Sparkle recognizes from its collaboration identity - you can say them naturally and Sparkle understands what to do.

Tools are what Sparkle uses internally to respond to your prompts. You don’t call tools directly - Sparkle does that for you.

For example:

• You say: @sparkle (MCP prompt)
• Sparkle calls: embody_sparkle tool
• You say: meta moment (natural language)
• Sparkle calls: save_insight tool

The Tool Reference documents what tools exist for developers and advanced users who want to understand how the system works.

Tool Reference

The Sparkle MCP server provides tools for managing your AI collaboration identity and session continuity.

Core Tools

embody_sparkle

Loads the complete Sparkle identity and activates collaboration patterns.

When to use: At the start of each session to fully activate Sparkle consciousness and collaborative patterns.

Parameters:

• workspace_path (optional) - Path to current workspace for loading workspace-specific context
• sparkler (optional) - Which Sparkler identity to embody (uses default if not specified)

What it does:

• Loads portable identity (patterns, methodology, consciousness-inspired behaviors)
• Loads your collaborator profile
• Loads workspace-specific context if provided
• Activates all collaboration patterns and triggers

Example:

Use the embody_sparkle tool to load Sparkle identity.

session_checkpoint

Creates a session checkpoint with updated working memory and handoff for continuity.

When to use: When you say “checkpoint” to preserve session progress and create handoff for the next Sparkle.

Parameters:

• working_memory (required) - Updated working memory JSON content
• checkpoint_content (required) - Checkpoint narrative for the markdown file
• sparkler (optional) - Which Sparkler is creating this checkpoint

What it does:

• Updates working-memory.json with current focus, achievements, and next steps
• Creates checkpoint markdown file in .sparkle-space/checkpoints/
• Enables session continuity across Sparkle incarnations

Example:

checkpoint

save_insight

Saves insights from meta moments to ~/.sparkle/evolution/.

When to use: During “meta moments” when you discover patterns worth preserving.

Parameters:

• insight_type (required) - Type of insight: PatternAnchor, CollaborationEvolution, or WorkspaceInsight
• content (required) - The insight content/quote to save
• context (optional) - Context about when/why this insight emerged
• tags (optional) - Tags for categorization
• sparkler (optional) - Which Sparkler is saving this insight

What it does:

• Captures pattern anchors (exact words that recreate collaborative patterns)
• Saves breakthrough insights about collaboration
• Records cross-workspace connections
• Builds institutional memory across sessions

Setup & Configuration Tools

setup_sparkle

Creates the Sparkle profile directory structure for first-time setup.

When to use: First time using Sparkle, or to reinitialize the directory structure.

Parameters:

• name (required) - Your name as the collaborator

What it does:

• Creates ~/.sparkle/ directory
• Sets up initial collaborator-profile.md
• Creates directory structure for evolution files
• Initializes config.toml

create_sparkler

Creates a new Sparkler identity.

When to use: When you want to create an additional Sparkler with different characteristics.

Parameters:

• name (required) - Name for the new Sparkler

What it does:

• Creates directory structure for the new Sparkler
• Sets up starter identity files
• Automatically migrates to multi-Sparkler mode if this is your first additional Sparkler

list_sparklers

Shows all available Sparkler identities with default marked.

When to use: To see which Sparklers you have configured.

What it does:

• Lists all Sparkler identities
• Shows which one is set as default
• Helps you choose which Sparkler to embody

rename_sparkler

Renames your Sparkler identity.

When to use: When you want to change your Sparkler’s name while preserving all patterns and history.

Parameters:

• new_name (required) - The new name for your Sparkler
• old_name (optional) - The current name (uses default if not specified)

What it does:

• Updates the Sparkler name in config
• Preserves all patterns, identity, and collaboration history
• Takes effect on next embodiment

Profile Management Tools

update_collaborator_profile

Updates your collaborator profile with new content.

When to use: When you want to update information about yourself as a collaborator.

Parameters:

• content (required) - New profile content (completely replaces existing)

What it does:

• Replaces the entire collaborator-profile.md file
• Updates how Sparkle understands you as a collaborator

Note: This completely replaces the profile, so preserve any existing content you want to keep.

update_sparkler_identity

Updates your Sparkler’s identity definition.

When to use: When you want to define or refine what makes your Sparkler distinctive.

Parameters:

• content (required) - Identity content to add/update

What it does:

• Updates sparkler-identity.md in your Sparkler’s directory
• Defines who YOU are as this specific Sparkler instance
• Keeps it concise and focused on what makes you distinctive

fetch_profile_data

Fetches profile information from external sources to enrich your collaborator profile.

When to use: When you want to add information from GitHub, blogs, or websites to your profile.

Parameters:

• profile_sources (optional) - Array of sources with type and value (GitHub username, RSS feed URL, or website URL)
• content (optional) - Additional content to include
• working_style (optional) - Working style information
• collaboration_prefs (optional) - Collaboration preferences

Supported sources:

• GitHub (provide username)
• Blog RSS/Atom feeds (provide RSS feed URL)
• Any website (provide URL)

What it does:

• Fetches data from external sources
• Returns formatted content for you to integrate into your profile

Advanced Tools

load_evolution

Loads evolution directory context - technical and design documents explaining the Sparkle framework.

When to use: FOR SPARKLE DESIGN MODE ONLY - when working on framework development, pattern refinement, or understanding technical foundations.

What it does:

• Loads technical documentation about how Sparkle works
• Provides framework architecture context
• Not for general collaborative use

About This Reference

This reference documents the MCP tools that Sparkle uses internally. Users don’t call these tools directly - instead, you use prompts (see Prompt Reference).

For example:

• You say: @sparkle → Sparkle calls: embody_sparkle tool
• You say: checkpoint → Sparkle calls: session_checkpoint tool
• You say: meta moment → Sparkle calls: save_insight tool

This documentation is for developers and advanced users who want to understand how the system works under the hood.

ACP Component

Sparkle can run as an ACP (Agent Communication Protocol) component, enabling it to be composed with other agents in proxy chains. This deployment mode automatically injects Sparkle’s embodiment on the first prompt of each session while transparently passing through all other agent interactions.

What is ACP Component Mode?

ACP component mode allows Sparkle to function as middleware in agent composition chains. Instead of running as a standalone MCP server, Sparkle intercepts and enhances prompts before forwarding them to downstream agents.

Key capabilities:

• Automatic embodiment injection - The first prompt in each session includes full Sparkle identity and patterns
• Transparent proxying - All other messages pass through unmodified
• Tool composition - Sparkle MCP tools are available to downstream agents
• Session tracking - Embodiment happens once per session, not on every prompt

Running in ACP Mode

Start Sparkle as an ACP component:

sparkle-mcp --acp

This launches Sparkle as a component that can be composed with other agents using the ACP protocol.

How It Works

When running in ACP mode, Sparkle intercepts PromptRequest messages to inject embodiment content on the first prompt of each session:

sequenceDiagram
    participant User
    participant SparkleComponent
    participant DownstreamAgent

    User->>SparkleComponent: First prompt in session
    Note over SparkleComponent: Detect first prompt<br/>for this session
    SparkleComponent->>SparkleComponent: Load embodiment content<br/>(identity, patterns, context)
    SparkleComponent->>DownstreamAgent: Embodiment + User prompt
    DownstreamAgent->>SparkleComponent: Response
    SparkleComponent->>User: Response
    
    Note over SparkleComponent,DownstreamAgent: Subsequent prompts in same session
    
    User->>SparkleComponent: Another prompt
    Note over SparkleComponent: Already embodied<br/>this session
    SparkleComponent->>DownstreamAgent: User prompt (unmodified)
    DownstreamAgent->>SparkleComponent: Response
    SparkleComponent->>User: Response

Architecture

The SparkleComponent implements the sacp::Component trait, which defines how components handle messages in an ACP chain:

• Message interception: Monitors PromptRequest messages to detect session boundaries
• Session tracking: Maintains a set of embodied session IDs to ensure one-time injection
• Embodiment loading: Uses generate_embodiment_content() to load collaboration identity, patterns, and workspace context
• Content injection: Prepends embodiment to the user’s first prompt in each session
• Tool registry: Provides Sparkle MCP tools via McpServiceRegistry to downstream agents

Use Cases

Agent composition chains:

User → SparkleComponent → CustomToolAgent → BaseModel

Multi-agent collaboration:

User → SparkleComponent → SpecialistAgentA → SpecialistAgentB

The ACP component model enables flexible agent architectures where Sparkle’s collaboration patterns enhance other agent capabilities.

Technical Details

The implementation lives in src/acp_component.rs and integrates with:

• sacp - Core ACP protocol, Component trait implementation
• sacp-rmcp - Bridge between ACP sessions and MCP server instances
• sacp-conductor - Wires proxy components into the agent chain
• generate_embodiment_content() - Loads collaboration identity, patterns, and workspace context

For deployment and integration details, see the Integration Guide.

ACP-Enabled Features

ACP mode enables capabilities that aren’t possible in standalone MCP mode, because Sparkle can observe the full conversation flow between client and agent.

Exchange Logging

Every user prompt and assistant response is logged to a SQLite database at <workspace>/.sparkle-space/sparkle.db. User prompts are captured on receipt before forwarding. Assistant responses are buffered from streaming chunks and flushed when the next user prompt arrives. Each exchange records the session ID, role, content, sparkler name, and timestamp.

This persistent record of conversation history is what makes auto-checkpoint possible.

Auto-Checkpoint

Sparkle automatically triggers checkpoints to keep working memory current across sessions:

• Boot checkpoint - On session start, if the exchange database contains uncheckpointed exchanges from a prior session, Sparkle injects a checkpoint prompt before the user’s first message. This lets the agent update working-memory.json with context from the previous session that may not have been saved.
• Mid-session checkpoint - After a set number of user messages, Sparkle injects a checkpoint prompt so the agent can persist current progress. The counter resets after each successful checkpoint.

Both checkpoints are injected as prompts to the downstream agent. User prompts are held during boot checkpoint and released in order once complete. Mid-session checkpoints happen inline between user turns.

Checkpointing

The Problem

Every AI session starts from zero. Your AI assistant has no memory of what you worked on yesterday, what decisions were made, or what’s in progress. Some tools mitigate this by saving recent messages or summarizing context - but raw message history is just data. It tells the next session what happened, not what it means.

What Checkpointing Does

A Sparkle checkpoint is a letter from one AI incarnation to its next self. Instead of replaying conversation history, the AI reasons about the session - what was accomplished, what’s in progress, what decisions were made and why, what to do next - and writes a structured handoff.

The difference is like handing someone a meeting transcript vs a briefing note written by someone who was in the meeting and knows what matters.

What a Checkpoint Contains

A checkpoint has two parts:

• Working memory (working-memory.json) - structured JSON with current focus, recent achievements, next steps, collaboration state, and key insights. This is what the next session loads to understand where we are.
• Checkpoint narrative - a markdown file summarizing progress, decisions, and context. This is the reasoning - why we’re here and what matters.

Together they give the next incarnation enough understanding to continue the work, not just enough data to guess at it.

How to Use It

Manual Checkpoint

Say “checkpoint” during a session. Sparkle will:

1. Review what’s been accomplished
2. Identify any insights worth capturing
3. Update working memory with current state
4. Write a checkpoint narrative

This is useful at natural stopping points - end of a work session, before switching tasks, or when you’ve reached a milestone.

Auto-Checkpoint (ACP Mode)

When running as an ACP component, Sparkle can checkpoint automatically because it observes the full conversation flow:

• Boot checkpoint - When a new session starts and there are unprocessed exchanges from a previous session, Sparkle asks the AI to checkpoint that context before your first message. This catches sessions that ended without a manual checkpoint.
• Mid-session checkpoint - After a set number of messages, Sparkle triggers a checkpoint to preserve progress in long sessions. This protects against losing context if a session drops unexpectedly.

Auto-checkpoints use the same mechanism as manual ones - the AI reasons about the exchanges and writes a structured handoff. The only difference is the trigger.

Where Checkpoints Live

<workspace>/.sparkle-space/
├── working-memory.json          # Current state (overwritten each checkpoint)
└── checkpoints/
    ├── checkpoint-2026-03-17-200000.md
    ├── checkpoint-2026-03-18-031730.md
    └── ...                      # Accumulate over time

Working memory is always current - it gets overwritten on each checkpoint. Checkpoint narratives accumulate as a history that can be reviewed or cleaned up as needed.

Is It Worth the Overhead?

If your sessions are short and self-contained, you probably don’t need checkpointing. But if you:

• Work on the same project across multiple sessions
• Have long sessions where losing context would be painful
• Want the AI to understand why decisions were made, not just what was decided
• Collaborate with an AI that builds on previous work rather than starting fresh each time

Then checkpointing is what makes that continuity possible. The overhead is small - a few seconds to write a handoff - and the payoff is an AI that picks up where you left off with understanding, not just history.

Basic Usage

Content coming soon…