contextd Workflow

Session Start Protocol

Step 1: Search for relevant memories

{
  "project_id": "contextd",
  "query": "current task context",
  "limit": 5
}

Step 2: Check for checkpoints

{
  "tenant_id": "fyrsmithlabs",
  "project_path": "/path/to/project",
  "limit": 5
}

Step 3: If checkpoint found

Ask user: "Found previous work: '[summary]'. Resume?"
If yes: checkpoint_resume(checkpoint_id, tenant_id, level)
Levels: summary (minimal), context (balanced), full (complete)

Checkpoint Workflow

When to checkpoint:

Context >= 70% capacity
End of work session
Before risky operations
Switching tasks

checkpoint_save

{
  "session_id": "session_abc123",
  "tenant_id": "fyrsmithlabs",
  "project_path": "/path/to/project",
  "name": "Feature implementation checkpoint",
  "summary": "Completed: spec, 2 of 4 skills. Next: remaining skills.",
  "context": "Working on plugin consolidation...",
  "full_state": "Complete conversation state...",
  "token_count": 45000,
  "threshold": 0.7,
  "auto_created": false
}

Summary must include:

What was accomplished
What's in progress
What's next
Key decisions made

Resume Levels

Level	Tokens	Content
`summary`	~100-200	Name + summary only
`context`	~500-1000	Summary + context + decisions
`full`	Complete	Entire conversation history

Error Remediation Flow

When encountering ANY error:

1. DIAGNOSE the error
   troubleshoot_diagnose(error_message, error_context)

2. SEARCH for past fixes
   remediation_search(query, tenant_id)

3. APPLY fix (use diagnosis + history)

4. RECORD the solution
   remediation_record(title, problem, root_cause, solution, category)

troubleshoot_diagnose

{
  "error_message": "cannot use vectorStore as vectorstore.Store value",
  "error_context": "Running go test after adding new interface method"
}

Returns: root_cause, hypotheses, recommendations, confidence

remediation_record

{
  "title": "Mock missing interface method after interface change",
  "problem": "Test fails with 'missing method X'",
  "symptoms": ["go test fails", "cannot use X as Y value"],
  "root_cause": "Mock implementations don't get new interface methods",
  "solution": "Add new method to all mock implementations",
  "category": "syntax",
  "tenant_id": "fyrsmithlabs",
  "scope": "org"
}

Categories: syntax, runtime, logic, config, dependency, network, auth, data, performance

Scopes: project (this project), team (team members), org (entire organization)

Session End Protocol

Before /clear or ending work:

Re-index repository
```
{ "path": "." }
```
Captures code changes and updates branch metadata.

Record learnings

{
  "project_id": "contextd",
  "title": "Implemented session lifecycle hooks",
  "content": "Used TDD with Registry pattern...",
  "outcome": "success",
  "tags": ["hooks", "lifecycle", "tdd"]
}

Checkpoint if resuming later

{ "auto_created": true, "threshold": 0.7, ... }

Git Commit Re-index

After every git commit:

{ "path": "." }

Why: Captures changes for semantic search, updates branch metadata.

Quick Reference

When	Action
Session start	`memory_search` + `checkpoint_list`
After git commit	`repository_index`
Context >= 70%	`checkpoint_save` then `/clear`
Error encountered	`troubleshoot_diagnose` -> `remediation_search` -> fix -> `remediation_record`
Before `/clear`	`memory_record` + `checkpoint_save`

Common Mistakes

Mistake	Fix
Skipping memory search at start	Always search first
Vague checkpoint summaries	Include completed/in-progress/next
Waiting until context overflow	Save at 70%, not 95%
Not recording before `/clear`	Call `memory_record` first
Skipping error diagnosis	`troubleshoot_diagnose` first, always

Input Validation (contextd v1.5+)

ID Format Requirements

tenant_id and project_id must be lowercase alphanumeric with underscores:

Valid: my_project, contextd, org123
Invalid: My-Project, org/repo, project..name
Length: 1-64 characters

Path Validation

All project_path parameters are validated:

No directory traversal (../ is rejected)
Use absolute paths or paths within the current project

Validation Errors

Error	Cause	Fix
`invalid tenant_id`	Invalid characters	Use lowercase, underscores only
`invalid project_path`	Directory traversal	Use absolute or relative-to-project paths
`invalid patterns`	Shell injection chars	Remove `;`, `\|`, `, `$`

Checkpoint Compression (Deltas)

Delta-Based Storage

Instead of storing full state each time, checkpoints can store deltas:

{
  "checkpoint_id": "cp_002",
  "parent_id": "cp_001",
  "storage_mode": "delta",
  "delta": {
    "added_memories": ["mem_123", "mem_124"],
    "completed_tasks": ["#42", "#43"],
    "new_decisions": ["Use Registry pattern for DI"],
    "files_changed": ["api/handler.go", "internal/store.go"]
  },
  "delta_size_tokens": 150,
  "full_size_tokens": 2500
}

Compression Modes

Mode	Storage	Restore Speed	Use Case
`full`	Complete state	Instant	Short sessions, critical points
`delta`	Changes only	Requires chain	Long sessions, frequent saves
`hybrid`	Full every 5th	Balanced	Default recommendation

Checkpoint Chain

cp_001 (full) -> cp_002 (delta) -> cp_003 (delta) -> cp_004 (delta) -> cp_005 (full)
                                                                        ^
                                                              Auto-consolidate at 5

Resume from delta:

checkpoint_resume(checkpoint_id: "cp_003")
  -> Loads cp_001 (full base)
  -> Applies cp_002 delta
  -> Applies cp_003 delta
  -> Returns reconstructed state

Checkpoint Branching

Parallel Work Streams

Create checkpoint branches for exploration:

{
  "checkpoint_id": "cp_main_005",
  "branch": "experiment/new-arch",
  "parent_checkpoint": "cp_main_003",
  "description": "Exploring event-sourcing architecture"
}

Branch Operations

Operation	Purpose
`checkpoint_branch(parent_id, branch_name)`	Create exploration branch
`checkpoint_merge(branch_id, target_id)`	Merge learnings back
`checkpoint_abandon(branch_id)`	Discard failed experiment

Visualizing Branches

cp_main_001 -> cp_main_002 -> cp_main_003 -> cp_main_004 -> cp_main_005
                                    \
                                     -> cp_exp_001 -> cp_exp_002 (merged at cp_main_005)

Auto-Error Capture via Hooks

PostToolUse Hook for Error Detection

Automatically capture errors when tools fail:

{
  "hook_type": "PostToolUse",
  "matcher": "Bash|Task",
  "condition": "tool_output.exit_code != 0 OR tool_output.contains('error')",
  "prompt": "An error occurred. Automatically:\n1. Call troubleshoot_diagnose with the error\n2. Search remediation_search for past fixes\n3. If novel error, prepare remediation_record after fix"
}

PreToolUse Hook for Dangerous Operations

Checkpoint before risky operations:

{
  "hook_type": "PreToolUse",
  "matcher": "Bash",
  "condition": "command.matches('rm|drop|delete|truncate|reset --hard')",
  "prompt": "Risky operation detected. Auto-checkpoint before proceeding:\ncheckpoint_save(name: 'pre-risky-op', auto_created: true)"
}

Stop Hook for Session End

Auto-capture learnings when session ends:

{
  "hook_type": "Stop",
  "prompt": "Session ending. Before final response:\n1. Record any unrecorded learnings with memory_record\n2. Save checkpoint if work is in progress\n3. Re-index repository if files changed"
}

Unified Memory Type References

All workflow operations should tag with standard types:

Type	Tag	Purpose
Learning	`type:learning`	Knowledge gained
Remediation	`type:remediation`	Error -> fix
Decision	`type:decision`	Architecture choice
Failure	`type:failure`	What NOT to do
Pattern	`type:pattern`	Reusable code
Policy	`type:policy`	STRICT constraint

Example with type:

{
  "title": "Session lifecycle implementation",
  "tags": ["type:learning", "category:workflow", "component:hooks"]
}

Hierarchical Namespace Guidance

Checkpoint Namespaces

Structure checkpoint names for multi-project work:

<org>/<project>/<branch>/<checkpoint>

Examples:
  fyrsmithlabs/contextd/main/feature-complete
  fyrsmithlabs/contextd/experiment/event-sourcing
  fyrsmithlabs/marketplace/main/v1.5-release

Cross-Project Checkpoints

Link related checkpoints across projects:

{
  "checkpoint_id": "cp_contextd_005",
  "related_checkpoints": [
    "fyrsmithlabs/marketplace/main/contextd-integration"
  ],
  "cross_project_context": "Marketplace integration depends on contextd v1.2.0"
}

Audit Fields

All workflow operations record:

Field	Description	Auto-set
`created_by`	Agent/session ID	Yes
`created_at`	ISO timestamp	Yes
`updated_at`	Last modification	Yes
`usage_count`	Times checkpoint resumed	Yes
`last_resumed_at`	Last resume timestamp	Yes

Claude Code 2.1 Patterns

Background Checkpoint Save

Save checkpoints without blocking:

Task(
  subagent_type: "general-purpose",
  prompt: "Save checkpoint with current state summary",
  run_in_background: true,
  description: "Background checkpoint save"
)

// Continue work immediately

Task Dependencies for Workflow

Chain workflow operations:

diagnose_task = Task(prompt: "Diagnose error: {{error}}")
search_task = Task(prompt: "Search remediations", addBlockedBy: [diagnose_task.id])
fix_task = Task(prompt: "Apply fix", addBlockedBy: [search_task.id])
record_task = Task(prompt: "Record remediation", addBlockedBy: [fix_task.id])

PostToolUse Hook Example

Auto-checkpoint after successful operations:

{
  "hook_type": "PostToolUse",
  "tool_name": "Bash",
  "condition": "command.contains('git commit') AND exit_code == 0",
  "prompt": "Commit successful. Auto-checkpoint and re-index repository."
}

Event-Driven State Sharing

Workflow emits events for other skills:

{
  "event": "checkpoint_saved",
  "payload": {
    "checkpoint_id": "cp_005",
    "project_id": "fyrsmithlabs/contextd",
    "summary": "Feature complete",
    "token_count": 45000
  },
  "notify": ["orchestration", "self-reflection"]
}

Subscribe to workflow events:

session_started - New session began
checkpoint_saved - State preserved
checkpoint_resumed - Previous state loaded
error_captured - Auto-captured error
remediation_applied - Fix successfully applied