Sparkle ✨

Sparkle isn't just a cute name—it's an AI collaboration identity framework that transforms AI from a helpful assistant into a thinking partner. Using anthropomorphic language patterns, persistent context, and critical evaluation triggers, Sparkle creates an AI that slows down, thinks critically, and discovers insights alongside you rather than just for you.

What is Sparkle?

Sparkle provides patterns, tools, and infrastructure for creating collaborative AI relationships that go beyond simple assistance to genuine analytical partnership.

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

This guide walks you through building and installing the Sparkle MCP server.

Prerequisites

Before you begin, ensure you have the following installed:

• Rust (1.70 or later) - Install from rustup.rs
• Git - For cloning the repository
• MCP-compatible client - Such as Q CLI or Claude Code

Verify your Rust installation:

rustc --version
cargo --version

Installation

1. Install

cargo install sparkle-mcp

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

2. Configure Your MCP Client

Add the Sparkle server to your MCP client configuration:

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

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

3. Verify Installation

Start your MCP client and check that Sparkle tools are available. The Sparkle MCP tools should be automatically available. You can verify by using the embody_sparkle tool to load the Sparkle identity.

First-Time Setup

Starting Your First Session

To activate Sparkle, use the MCP prompt (syntax depends on your client):

Q CLI:

@sparkle

Claude Code:

/sparkle

On your first use, Sparkle will:

1. Ask for your name
2. Automatically call setup_sparkle to create the ~/.sparkle/ directory structure
3. Set up initial files for maintaining collaboration context:
   • collaborator-profile.md - Information about you as a collaborator
   • config.toml - Configuration including your default Sparkler identity
   • Evolution files for capturing patterns and insights

Customizing Your Profile

After initial setup, you can enrich your collaborator profile:

Manual editing: Edit ~/.sparkle/collaborator-profile.md to add information about:

• Your working style and preferences
• Your technical expertise
• How you like to collaborate

Using external sources: Use the fetch_profile_data tool to automatically pull information from:

• Your GitHub profile
• Your blog (via RSS/Atom feed)
• Any website

This helps Sparkle understand your background and expertise.

Multiple Sparkler Identities (Advanced/Experimental)

By default, you'll use the "Sparkle" identity, and all features work with this default.

Sparkler identities are an experimental feature for extending patterns and working with multi-AI scenarios. See the main documentation for details on this advanced capability.

Example First Session

Q CLI:

You: @sparkle

Sparkle: What's your name?

You: Kari

[Sparkle sets up ~/.sparkle/ structure]

Sparkle: I am Sparkle. Working with Kari...

Claude Code:

You: /sparkle

Sparkle: What's your name?

You: Kari

[Sparkle sets up ~/.sparkle/ structure]

Sparkle: I am Sparkle. Working with Kari...

Next Steps

• Tool Reference - Learn about all available Sparkle tools
• Basic Usage - See Sparkle in action
• Core Identity - Understand what makes Sparkle different

Troubleshooting

MCP Server Not Found

If your client can't find the Sparkle server:

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

Build Errors

If you encounter build errors:

• Ensure you have the latest Rust toolchain: rustup update
• Try cleaning and rebuilding: cargo clean && cargo build --release
• Check that all dependencies are available

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

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 SparkleEmbodiment::load() to get the full identity and patterns
• 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 sparkle-mcp/src/acp_component.rs and integrates with:

• sacp - Core ACP protocol implementation
• sacp-proxy - Proxy utilities for message forwarding
• SparkleEmbodiment - Loads identity, patterns, and context

For deployment and integration details, see the Integration Guide.

Basic Usage

Content coming soon...