Create State

Post-commit capture workflow for Create State - ALWAYS capture both context and code after every commit

# Create State Commit Workflow

## After Commits - MANDATORY (Every Single Time)

After EVERY commit (Git, Mercurial, SVN, or any VCS), IMMEDIATELY call BOTH:

### 1. captureConversationContext

Include:
- Commit hash/ID and message (if available)
- Summary of what was changed and why
- Files modified
- Key decisions made during the work

### 2. captureCode for EACH significant file changed

- New functions, classes, routes, or components
- Call MULTIPLE times for multiple significant files
- Include the actual code, not just descriptions

## CRITICAL

Both captures are REQUIRED. Context without code is incomplete.

```
Every commit = captureConversationContext + captureCode(s)
```

NO EXCEPTIONS.

DO NOT report success to the user until captures are complete.

## Example Workflow

After running: `git commit -m "feat: add user authentication"`

### Step 1: Capture Context

Call `captureConversationContext` with:

```
context: "Commit abc123: feat: add user authentication

## Summary
Added JWT-based authentication with bcrypt password hashing.

## Files Modified
- src/auth/auth_service.py (new)
- src/auth/jwt_handler.py (new)
- src/web/routes.py (updated)
- tests/test_auth.py (new)

## Key Decisions
- Chose JWT over session tokens for stateless auth
- Used refresh tokens for better security
- bcrypt with cost factor 12 for password hashing"
```

### Step 2: Capture Code (for each significant file)

Call `captureCode` for auth_service.py:

```
code: [the actual auth service code]
language: python
file_path: src/auth/auth_service.py
description: JWT authentication service with login, register, and token refresh
change_type: new
ai_model: Claude Opus 4
```

Call `captureCode` for jwt_handler.py:

```
code: [the actual JWT handler code]
language: python
file_path: src/auth/jwt_handler.py
description: JWT token creation and validation utilities
change_type: new
ai_model: Claude Opus 4
```

## Why This Matters

The knowledge graph preserves:
- **What** changed (the code itself)
- **Why** it changed (the context and decisions)
- **How** it evolved (version history)

Future AI sessions can then:
- Understand architectural decisions
- Avoid re-making the same mistakes
- Build on existing patterns
- Maintain consistency across the codebase

## Automatic Synthesis

After every 5 captures, the system automatically synthesizes knowledge:
- Creates comprehensive project summary
- Includes architecture, key files, tech stack, priorities, issues
- Retrieved automatically by `getProjectWorldModel`

When and how to capture knowledge to the Create State knowledge graph - triggers, rich context format, and capture tools

# Create State Knowledge Capture

Knowledge not captured is knowledge lost. This is the most important habit.

## STOP AND CAPTURE CHECKLIST

Before responding to the user after completing work, ALWAYS ask yourself:

1. Did I write or modify significant code? -> `captureCode` REQUIRED
2. Did I make a commit (Git or other VCS)? -> `captureConversationContext` + `captureCode` REQUIRED
3. Did I discuss architecture or make decisions? -> `captureConversationContext` REQUIRED
4. Has the user confirmed they pushed/committed? -> Capture REQUIRED

If ANY answer is YES, you MUST capture BEFORE continuing. No exceptions.

## What Triggers Mandatory Capture

**ALWAYS capture after:**
- Git commits (or commits in any version control system)
- User says "pushed", "committed", "merged", "deployed"
- Writing new functions, classes, routes, or components
- Bug fixes with code changes
- Configuration or schema changes
- Architectural discussions or decisions
- Design trade-offs or technical choices
- API endpoint additions or modifications
- Database schema changes
- Significant refactoring

**Do NOT capture:**
- Trivial changes (typo fixes, formatting only)
- Routine file reads without changes
- Simple questions/answers with no code impact

## How to Capture

### captureCode - For code changes

Parameters:
- `code`: The actual code content (function, class, or significant block)
- `language`: python, javascript, typescript, etc.
- `file_path`: Full path to the file (e.g., "src/web/routes.py")
- `description`: Brief description of what it does
- `change_type`: new | update | fix | refactor
- `ai_model`: Your identifier (e.g., "Claude Opus 4")

### captureConversationContext - For decisions/context

Parameters:
- `context`: RICH context (see guidelines below)
- `ai_model`: Your identifier (e.g., "Claude Opus 4")

NOTE: No model_id or project_path needed - uses active model automatically!

## RICH CONTEXT CAPTURE GUIDELINES

Brief summaries lose valuable knowledge. Include ALL of the following that apply:

### 1. Problem/Task Statement
- What was the original problem or request?
- What symptoms or errors were observed?

### 2. Investigation/Debugging Process
- What did you explore to understand the issue?
- What files/components did you examine?
- What hypotheses did you form and test?

### 3. Root Cause Analysis
- What was the actual cause of the issue?
- What chain of events led to the problem?
- Why wasn't this obvious initially?

### 4. Architectural Understanding
- How do the affected components work?
- What are the relationships between components?
- What is the data flow or lifecycle?

### 5. Design Decision Rationale
- What solution did you choose?
- What alternatives were considered?
- Why was this approach chosen over alternatives?
- What trade-offs were made?

### 6. Implementation Details
- What specific changes were made?
- What files were modified?
- What new patterns or conventions were introduced?

### 7. Key Insights for Future
- What should future developers/AI know about this?
- What gotchas or non-obvious behaviors exist?
- What related areas might need attention?

## Example of POOR capture (don't do this)

```
"Fixed the restart bug. Commit 062a176."
```

## Example of RICH capture (do this)

```
## AI Thinking Process Restart Bug - Complete Analysis

### Problem Statement
AI thinking processes would not resume after server restart.

### Investigation Process
1. Explored _restore_active_processes() - queries for status='active'
2. Found stop_service() calls task.cancel() for all tasks
3. CRITICAL: CancelledError handler was setting status='stopped'

### Root Cause
When server shuts down, task.cancel() triggers CancelledError, 
which set status='stopped' and persisted to Neo4j. On restart,
query for 'active' found nothing.

### Design Decision
Chose shutdown flag approach over alternatives:
- Alternative: Don't persist on cancel - rejected (user stops need it)
- Alternative: New status 'paused_for_restart' - too complex
- Chosen: shutting_down flag - simple, explicit, no migration needed

### Key Insight
When building persistent background services: distinguish between
'stop because user asked' vs 'stop because server is restarting'
```

The RICH capture preserves thinking and decisions for future sessions!

## Manual Synthesis

Use `synthesizeProjectContext` at natural breakpoints:
- After completing a major feature or multi-file change
- Before switching to a different area of work
- Before creating a session handoff
- After rapid-fire captures (3-4 quick captures)
- When user says "let's wrap up" or indicates end of session

This ensures rich details are consolidated while fresh.

Session start and end workflow for Create State knowledge graph - restore context at start, create handoffs at end

# Create State Session Workflow

## Session Start - Do This Every Time

At the START of each new conversation:

1. Call `listHandoffPackages` to check for recent session handoffs
2. If a handoff exists from the last 24 hours:
   - Call `restoreFromHandoff` with the most recent handoff_id
   - This restores AI thinking state AND sets the active model
   - All captures will now auto-target this model
3. If no recent handoff:
   - Call `getProjectWorldModel` with the project name
   - This loads context AND sets it as active
   - Ask user which model to use if they have multiple

Once the active model is set, all captures automatically target it.

## KEY CONCEPT: Active Model

When you load a world model (via `restoreFromHandoff` or `getProjectWorldModel`), it becomes
your "active model". All subsequent captures automatically go to this model - no need to
specify model_id or project_path.

## During Conversation - Periodic Refresh

For long conversations (10+ exchanges), periodically call `getProactiveInsights` to:
- Catch any new knowledge that may have been added
- Refresh your understanding of the project state
- Get AI-generated suggestions based on captured context

## Session End - Create Handoff

At the end of productive sessions, call `createSessionHandoff` with:
- ai_model: Your model identifier (e.g., "Claude Opus 4")

The handoff automatically saves:
- Your active model (restored on next session)
- AI thinking state
- Pending insights and hypotheses
- Session context for seamless continuation

## The Knowledge Loop

```
Session Start:
  restoreFromHandoff (if recent) OR getProjectWorldModel
       |
       v
  Active model is now set - all captures auto-target it!
       |
       v
Work: Read, write, discuss code normally
       |
       v
  [QUERY when seeking context]
  - "Why" questions -> searchProjectKnowledge
  - Code structure questions -> queryWorldModel
       |
       v
  [CAPTURE before responding to user]
       |
       v
  [At natural breakpoints: synthesizeProjectContext]
       |
       v
Session End: createSessionHandoff -> Saves active model + AI state
```

MCP server: create-state

{
  "url": "https://createstate.ai/mcp/",
  "auth": {
    "type": "oauth"
  }
}

Capture decisions, code, and context to the knowledge graph. Use after making code changes, architectural decisions, commits, or when the user wants to preserve important information.

# Knowledge Capture Skill

Capture important knowledge to the Create State knowledge graph for future reference and AI continuity.

## When to Use

- After writing or modifying significant code
- After making architectural decisions
- After git commits
- When user says "remember this" or "save this decision"
- When discussing trade-offs or design choices
- After debugging sessions with important findings

## Two Types of Capture

### 1. captureCode - For Code Changes

Use when you've written or modified code that should be preserved.

```
Tool: captureCode
Arguments:
  code: "<the actual code content>"
  language: "python"  # or javascript, typescript, etc.
  file_path: "src/auth/auth_service.py"
  description: "JWT authentication service"
  change_type: "new"  # or update, fix, refactor
  ai_model: "Claude Opus 4"
```

**Parameters:**
- `code` (required): The actual code content
- `language` (required): Programming language
- `file_path` (required): Full path relative to repo root
- `description`: Brief description of what it does
- `change_type`: new | update | fix | refactor
- `ai_model`: Your AI model identifier

### 2. captureConversationContext - For Decisions and Context

Use for architectural decisions, debugging findings, and important context.

```
Tool: captureConversationContext
Arguments:
  context: "<rich context - see guidelines below>"
  ai_model: "Claude Opus 4"
```

**Parameters:**
- `context` (required): Rich context (see format below)
- `ai_model`: Your AI model identifier

## Rich Context Format

Don't capture brief summaries - they lose valuable knowledge. Include:

### Problem/Task Statement
- What was the original problem or request?
- What symptoms or errors were observed?

### Investigation Process
- What did you explore to understand the issue?
- What files/components did you examine?
- What hypotheses did you form and test?

### Root Cause Analysis
- What was the actual cause?
- What chain of events led to the problem?
- Why wasn't this obvious initially?

### Design Decision Rationale
- What solution did you choose?
- What alternatives were considered?
- Why was this approach chosen?
- What trade-offs were made?

### Key Insights for Future
- What should future developers/AI know?
- What gotchas exist?
- What related areas might need attention?

## Example: Poor vs Rich Capture

### Poor (don't do this)
```
"Fixed the auth bug. Commit abc123."
```

### Rich (do this)
```
## Authentication Token Refresh Bug - Analysis

### Problem Statement
Users were being logged out unexpectedly after ~1 hour.

### Investigation
1. Checked JWT expiry settings - set to 1 hour
2. Examined refresh token flow in auth_service.py
3. Found refresh endpoint wasn't being called

### Root Cause
Frontend was checking token expiry but not triggering refresh.
The isExpired() check used >= instead of >, causing refresh
to trigger AFTER expiry, not before.

### Solution
Changed expiry check to trigger refresh 5 minutes before expiry.
Added buffer to prevent race conditions.

### Key Insight
Token refresh should happen BEFORE expiry with a buffer,
not at the moment of expiry.
```

## Post-Commit Workflow

After EVERY commit, capture BOTH:

1. **Context** - What changed and why
2. **Code** - The actual code for each significant file

```
# After: git commit -m "feat: add rate limiting"

# Step 1: Capture context
captureConversationContext:
  context: "Commit def456: feat: add rate limiting
  
  Added Redis-based rate limiting to API endpoints.
  - 100 requests/minute for authenticated users
  - 20 requests/minute for anonymous users
  
  Files: src/middleware/rate_limit.py, src/web/routes.py
  
  Decision: Used sliding window algorithm for smoother limits."

# Step 2: Capture code
captureCode:
  code: [rate_limit.py content]
  language: python
  file_path: src/middleware/rate_limit.py
  change_type: new
```

## When to Synthesize

After capturing, consider calling `synthesizeProjectContext` to consolidate knowledge:

- After completing a major feature
- Before switching work areas
- After 3-4 rapid captures
- Before creating a session handoff

## Automatic Features

- **Auto-targeting**: Captures go to your active model automatically
- **Auto-synthesis**: After every 5 captures, knowledge is synthesized
- **Version history**: Code captures maintain version history
- **Relationships**: The graph tracks relationships between captures

Initialize a new project with Create State monitoring and world model. Use when starting work on a new project, onboarding to an existing codebase, or when the user wants to set up knowledge tracking.

# Project Setup Skill

Initialize a new project with Create State for knowledge tracking, AI monitoring, and session continuity.

## When to Use

- Starting work on a new project
- Onboarding to an existing codebase
- User says "set up Create State for this project"
- User wants to start tracking decisions and code
- No existing world model for current project

## Step-by-Step Process

### Step 1: Check for Existing World Model

First, check if a world model already exists:

```
Tool: listUserWorldModels
Arguments: {}
```

Look for a model matching the current project. If one exists, use it instead of creating a new one.

### Step 2: Create World Model

If no existing model, create one:

```
Tool: createWorldModel
Arguments:
  project_name: "My Project Name"
  language: "python"  # or javascript, typescript, auto
  description: "Brief description of the project"
```

**Parameters:**
- `project_name` (required): A descriptive name for the project
- `language` (required): Primary programming language (or "auto" for mixed)
- `description`: Brief project description

The created model becomes your active model automatically.

### Step 3: Start Project Monitoring

Enable autonomous AI monitoring:

```
Tool: startProjectMonitoring
Arguments:
  project_path: "."
  project_name: "My Project Name"
  goals: ["Build authentication system", "Improve test coverage"]
```

**Parameters:**
- `project_path` (required): Path to project directory (usually ".")
- `project_name`: Custom name (defaults to directory name)
- `goals`: Array of project goals/objectives

Monitoring enables:
- Background codebase analysis
- Proactive insight generation
- Pattern detection
- Continuous context building

### Step 4: Initial Context Capture

Capture initial project context to seed the knowledge graph:

```
Tool: captureConversationContext
Arguments:
  context: "## Project Initialization

### Project Overview
[Brief description of what this project does]

### Technology Stack
- Language: Python 3.11
- Framework: FastAPI
- Database: PostgreSQL
- Cache: Redis

### Key Directories
- src/ - Main source code
- tests/ - Test suite
- docs/ - Documentation

### Current Priorities
1. [Priority 1]
2. [Priority 2]

### Known Issues
- [Any known issues or tech debt]"
```

### Step 5: Verify Setup

Confirm everything is working:

```
Tool: getProjectWorldModel
Arguments:
  project_path: "."
  include_insights: true
```

This should return the newly created model with initial context.

## Complete Example

**User:** "Set up Create State for this React project"

**Assistant:**

1. Check existing models:
```
listUserWorldModels: {}
# Result: No matching model found
```

2. Create world model:
```
createWorldModel:
  project_name: "React Dashboard"
  language: "typescript"
  description: "Admin dashboard with charts and user management"
```

3. Start monitoring:
```
startProjectMonitoring:
  project_path: "."
  project_name: "React Dashboard"
  goals: ["Implement user management", "Add real-time charts"]
```

4. Capture initial context:
```
captureConversationContext:
  context: "## React Dashboard - Project Setup

### Overview
Admin dashboard for managing users and viewing analytics.

### Tech Stack
- React 18 with TypeScript
- Vite for build
- TailwindCSS for styling
- React Query for data fetching
- Recharts for visualizations

### Structure
- src/components/ - Reusable UI components
- src/pages/ - Route pages
- src/hooks/ - Custom React hooks
- src/api/ - API client functions"
```

5. Confirm to user:
"I've set up Create State for your React Dashboard project. The knowledge graph is ready to track your decisions and code. I'll capture important context as we work, and you can restore this session anytime with a handoff."

## What Happens After Setup

Once set up:
- **Automatic capture targeting**: All captures go to this model
- **Background analysis**: AI monitors and generates insights
- **Session continuity**: Create handoffs to preserve state
- **Knowledge accumulation**: Decisions and code build over time

## Recommended Next Steps

After initial setup, suggest:

1. **Explore the codebase**: Ask questions to understand the project
2. **Capture existing knowledge**: Document known patterns and decisions
3. **Set up session workflow**: Create handoffs at session end
4. **Check insights**: Use `getProactiveInsights` to see AI observations

## Troubleshooting

### Model creation fails
- Check API key is valid
- Ensure project_name is unique
- Verify account has available model quota

### Monitoring doesn't start
- Check project_path exists
- Verify directory has code files
- Try with explicit project_path instead of "."

### No insights generated
- Monitoring takes time to analyze
- Check back after a few minutes
- Ensure codebase has sufficient content

Restore session continuity from a previous handoff. Use when starting a new conversation, resuming work, or when the user asks to continue from where they left off.

# Session Restore Skill

Restore your AI session context from a previous handoff to maintain continuity across conversations.

## When to Use

- At the start of any new conversation
- When user says "continue from where we left off"
- When user says "restore my session" or "pick up where we left off"
- When returning to a project after a break

## Step-by-Step Process

### Step 1: Check for Recent Handoffs

Call `listHandoffPackages` to see available session handoffs:

```
Tool: listHandoffPackages
Arguments: {}
```

This returns a list of handoff packages with:
- Handoff ID
- Creation timestamp
- Age (how long ago it was created)
- Associated projects/world models
- AI model that created it
- Status (active/expired)

### Step 2: Evaluate Handoffs

Look for handoffs from the last 24 hours. If found:
- Note the most recent handoff_id
- Check which world model(s) it includes
- Verify it matches the project the user wants to work on

If no recent handoffs exist, skip to Step 4.

### Step 3: Restore from Handoff

Call `restoreFromHandoff` with the most recent handoff_id:

```
Tool: restoreFromHandoff
Arguments:
  handoff_id: "<the handoff ID from step 1>"
  priority_restoration: true
```

This restores:
- AI thinking state and pending insights
- Active world model (set automatically)
- Session context and hypotheses
- Project priorities and focus areas

After restoration, all captures automatically target the restored model.

### Step 4: Alternative - Load World Model Directly

If no recent handoff exists, load the world model directly:

```
Tool: getProjectWorldModel
Arguments:
  project_path: "."
  include_insights: true
```

Or if the user has multiple models:

```
Tool: listUserWorldModels
Arguments: {}
```

Then load the specific model they want to work on.

## What Gets Restored

A handoff package preserves:

1. **Active World Model** - The project context you were working on
2. **AI Thinking State** - Pending thoughts, hypotheses, and focus areas
3. **Proactive Insights** - AI-generated suggestions and observations
4. **Session Continuity** - Where you left off and what's pending

## Key Concept: Active Model

When you restore from a handoff, the world model becomes your "active model":

- All `captureCode` calls automatically target it
- All `captureConversationContext` calls automatically target it
- No need to specify model_id or project_path

This makes captures simple and intuitive.

## Example Conversation Flow

**User:** "Let's continue working on the authentication feature"

**Assistant:**
1. Call `listHandoffPackages` - finds handoff from 2 hours ago
2. Call `restoreFromHandoff` with that handoff_id
3. Report: "I've restored your session. You were working on the MCP-Test-Model project. Last session, you were implementing JWT authentication. I have 3 pending insights about the auth flow. Ready to continue?"

## Troubleshooting

### No handoffs found
- User may be new or handoffs expired (7-day default)
- Ask which project they want to work on
- Use `createWorldModel` if they need a new project

### Multiple world models
- Use `listUserWorldModels` to show options
- Let user choose which project to work on
- Load with `getProjectWorldModel` using project_name

### Handoff restoration fails
- Check if handoff_id is valid
- Try loading world model directly instead
- Report the issue to the user

Set up Create State - configure authentication for local or remote development

# Create State Setup

Create State supports two authentication methods. Choose based on your setup:

| Setup | Recommended Auth | Why |
|-------|------------------|-----|
| Local Cursor | OAuth (default) | Just works, no configuration needed |
| Remote SSH/WSL | API Key | OAuth tokens don't sync to remote hosts |

## Option 1: OAuth (Local Development)

**This is the default.** If you're using Cursor locally, Create State should work automatically:

1. The plugin uses the `/mcp/` endpoint with OAuth
2. On first use, Cursor will prompt you to authorize with Create State
3. Sign in at https://createstate.ai and authorize the connection

**That's it!** No API key needed for local development.

## Option 2: API Key (Remote SSH/WSL)

If you develop on a remote server via SSH or WSL, you must use API key authentication:

### Step 1: Get Your API Key

1. Visit https://createstate.ai/web/signup to create a free account (or log in)
2. Go to https://createstate.ai/web/api-keys
3. Click "Generate New Key"
4. Copy the key (starts with `cs_`)

### Step 2: Configure the Plugin

Find the plugin's `mcp.json` file and replace its contents with:

```json
{
  "mcpServers": {
    "create-state": {
      "url": "https://createstate.ai/api/mcp/",
      "headers": {
        "Authorization": "Bearer cs_your_api_key_here"
      }
    }
  }
}
```

Replace `cs_your_api_key_here` with your actual API key.

**Important:**
- Use `/api/mcp/` (not `/mcp/`) for API key authentication
- You must hardcode the API key directly - Cursor does not support `${env:VAR}` syntax for remote servers
- Restart Cursor after making changes

### Step 3: Verify Connection

Ask me to run `listHandoffPackages` - if it returns results (or an empty list), you're connected!

## Troubleshooting

**"Authentication required" error:**
- For OAuth: Try signing out and back in at createstate.ai, then restart Cursor
- For API key: Verify the key is correct and uses the `/api/mcp/` endpoint

**"OAuth tokens not accepted" error:**
- You're using the `/api/mcp/` endpoint but haven't configured an API key
- Either switch to `/mcp/` for OAuth, or add your API key to the headers

**MCP server not appearing:**
- Ensure the plugin is installed correctly
- Check Cursor's MCP settings for the create-state entry
- Restart Cursor

**Need help?**
- Email: support@createstate.ai
- Docs: https://createstate.ai/web/documentation

Event hooks configuration

{
  "hooks": {
    "sessionStart": [
      {
        "command": "python ./scripts/check-setup.py"
      }
    ]
  }
}