Skip to content

zachswift615/workshop

BranchesTags

Repository files navigation

Workshop

PyPI version Tests codecov Python 3.8+ License: MIT

Give Claude Code long-term memory and project knowledge.

Workshop is a production-ready context management system that gives Claude Code institutional memory. It automatically captures decisions, gotchas, and learnings from your conversations—and can even import months of past session history.

No manual note-taking. No context loss. Just continuous, persistent project knowledge.

🎯 Why Workshop?

The Problem: Claude Code has amazing conversations but terrible memory. Every new session starts from scratch. Your architectural decisions, lessons learned, and project context vanish after each compaction.

The Solution: Workshop gives Claude persistent memory. It automatically:

  • 📝 Records decisions with reasoning as you discuss them
  • ⚠️ Documents gotchas and constraints as you discover them
  • 🔄 Captures session summaries when conversations end
  • 🧠 Answers "why" questions by searching past decisions
  • 📥 Imports historical sessions to backfill months of knowledge
  • 🎯 Tracks goals and blockers across sessions

Result: Claude remembers everything about your project, even weeks or months later.

⚡ Quick Start

# Install
pip install claude-workshop

# Set up Claude Code integration (one-time)
workshop init

# Import your past sessions (optional but recommended)
workshop import --execute

That's it! Claude now has persistent memory in this project.

In your next Claude Code session, try:

"What decisions have we made about the database?"
"What gotchas should I know about?"
"What were we working on last session?"

Claude will search Workshop's knowledge base and give you context-aware answers.

🚀 Key Features

1. Automatic Context Capture

Claude automatically records important information as you work:

  • Architectural decisions with reasoning
  • Gotchas, constraints, and lessons learned
  • Session summaries (what you worked on, files changed)
  • User preferences and coding style
  • Current goals and blockers

You do nothing—it just works.

2. Historical Session Import 🔥

The game-changer: Import your existing Claude Code conversation history.

workshop import --execute

Workshop analyzes past sessions using pattern matching to extract:

  • Decisions: "We decided to use PostgreSQL because..."
  • Gotchas: "Watch out for the rate limit on this API..."
  • Discoveries: "Turns out the cache needs to be invalidated..."
  • Summaries: Complete session summaries from compactions

This means Workshop can learn from conversations you had weeks or months ago, giving Claude instant access to all your project's history.

3. Smart Search & Context

Claude can query Workshop to answer questions:

workshop why "using zustand"     # Why did we choose this?
workshop search "authentication"  # Find all auth-related entries
workshop context                  # Current project state
workshop sessions                 # Past session summaries

Full-text search powered by SQLite FTS5 makes everything instantly retrievable.

4. Per-Project Memory

Each project gets its own knowledge base:

  • Per-project .workshop/workshop.db database
  • Auto-configuration via ~/.workshop/config.json
  • Works seamlessly across project directories
  • Optional web UI for browsing (workshop web)

5. Production-Ready

  • ✅ 63% test coverage (128 tests)
  • ✅ Cross-platform (macOS, Linux, Windows)
  • ✅ Schema migrations for upgrades
  • ✅ Robust error handling
  • ✅ Type-safe with comprehensive testing

📖 How It Works

Setup (One-Time)

pip install claude-workshop
workshop init

This configures Claude Code to:

  1. Load Workshop context at session start
  2. Record knowledge automatically during conversations
  3. Capture session summaries at session end

Automatic Operation

Once set up, Workshop works invisibly in the background:

Session Start → Claude loads project context from Workshop During Conversation → Claude records decisions/gotchas as you discuss them Session End → Workshop captures session summary automatically

Manual Usage (Optional)

While Claude handles everything automatically, you can also:

# Query knowledge
workshop why "database choice"
workshop context
workshop recent

# Manually add entries
workshop decision "Using Redis for caching" -r "Need sub-millisecond latency"
workshop gotcha "API has 100 req/min rate limit"
workshop goal add "Implement retry logic"

# Import history
workshop import --execute
workshop import-status

# Manage entries
workshop search "authentication"
workshop delete <id>

# Admin
workshop info
workshop web  # Launch web UI

📥 Importing Historical Sessions

One of Workshop's most powerful features: import months of past conversations.

Basic Import

# Preview what would be imported (safe, read-only)
workshop import

# Actually import sessions
workshop import --execute

# Check import status
workshop import-status

Advanced Import

# Import specific file
workshop import ~/.claude/projects/my-project/session.jsonl --execute

# Interactive review (approve each extraction)
workshop import --interactive --execute

# See detailed extraction preview
workshop import --verbose

What Gets Imported

Workshop uses intelligent pattern matching to extract:

  • Decisions: "We chose X because Y"
  • Gotchas: "Watch out for...", "Important to note..."
  • Discoveries: "Found that...", "Turns out..."
  • Summaries: Complete session summaries from compactions
  • Preferences: User coding style and preferences

Each extraction includes:

  • Confidence score (0.0-1.0)
  • Source message UUID for traceability
  • Timestamp for temporal context
  • Automatic deduplication

Import Intelligence

Workshop is smart about imports:

  • ✅ Tracks what's been imported (no duplicates)
  • ✅ Incremental imports (only new sessions)
  • ✅ Handles compaction summaries (months of context)
  • ✅ Filters noise (code snippets, JSON, hooks)
  • ✅ Validates content quality before storing

🎨 Example Workflows

Starting a New Session

claude  # Start Claude Code

# Claude automatically loads Workshop context:
# "📝 Workshop Context Available
#  Recent decisions: Using PostgreSQL, Zustand for state
#  Active goals: Implement caching layer
#  Gotchas: API rate limit 100/min..."

Querying Past Decisions

You: "Why did we choose PostgreSQL over MongoDB?"

Claude: *searches Workshop* "According to the decision recorded 2 weeks ago,
you chose PostgreSQL because you needed ACID guarantees for transactions and
complex relational queries. The reasoning was that MongoDB's eventual
consistency wasn't suitable for financial data."

Bootstrapping a Project

# You've been working in Claude Code for months
# Install Workshop and import everything:

pip install claude-workshop
workshop init
workshop import --execute

# Workshop now has months of project knowledge
# Claude can answer questions about past decisions immediately

🗂️ Entry Types

Workshop tracks different types of knowledge:

Type Icon Purpose Example
decision 💡 Architectural choices with reasoning "Using PostgreSQL for ACID guarantees"
note 📝 General observations and findings "API endpoint returns paginated results"
gotcha ⚠️ Constraints, limitations, warnings "Rate limit is 100 requests per minute"
preference 👤 User coding style preferences "Prefer async/await over promises"
goal 🎯 Current objectives "Implement caching layer"
blocker 🛑 Issues preventing progress "Waiting for API key from vendor"
next_step 📍 Immediate next actions "Add error handling to login flow"

📋 CLI Commands

Query & Search

workshop why <query>           # Search decisions with reasoning
workshop search <query>        # Full-text search all entries
workshop context               # Show current project state
workshop recent                # Show recent entries
workshop sessions              # Show past session summaries
workshop info                  # Show workspace information

Add Entries

workshop decision <text> -r <reasoning>  # Record decision
workshop note <text>                     # Add note
workshop gotcha <text>                   # Record gotcha
workshop preference <text>               # Record preference
workshop goal add <text>                 # Add goal
workshop blocker add <text>              # Add blocker
workshop next add <text>                 # Add next step

Goals & Next Steps

workshop goal list              # Show all goals
workshop goal done <id>         # Mark goal complete
workshop next                   # Show next steps
workshop next done <id>         # Mark step complete
workshop next skip <id>         # Skip step

Import & Export

workshop import                 # Preview import (read-only)
workshop import --execute       # Import sessions
workshop import <file> --execute  # Import specific file
workshop import --interactive   # Review each extraction
workshop import-status          # Show import history
workshop export                 # Export context for web chat

Manage

workshop delete <id>            # Delete entry by ID
workshop clear <date>           # Delete entries before date
workshop web                    # Launch web UI (optional)

🔧 Configuration

Workshop uses ~/.workshop/config.json for per-project settings:

{
  "version": "1.0",
  "default_mode": "per-project",
  "projects": {
    "/Users/you/myproject": {
      "database": "/Users/you/myproject/.workshop/workshop.db",
      "jsonl_path": "~/.claude/projects/-Users-you-myproject",
      "auto_import": true
    }
  }
}

Auto-configured on first use - you typically don't need to edit this manually.

Database Location

By default, Workshop stores data in .workshop/workshop.db at your project root.

You can customize per-project in the config, or use the optional web UI to manage settings.

🌐 Web UI (Optional)

Workshop includes an optional web interface:

workshop web
# Opens http://localhost:5001

Features:

  • Browse all entries by type
  • Full-text search
  • Edit and delete entries
  • View session summaries
  • Manage configuration

Great for exploring Workshop's knowledge base visually!

🔍 JSONL File Locations

Workshop imports from Claude Code's JSONL session files:

macOS/Linux:

~/.claude/projects/<normalized-project-path>/

Windows:

%USERPROFILE%\.claude\projects\<normalized-project-path>\

Path Normalization:

  • /Users/name/project → -Users-name-project
  • Underscores in project names are preserved

Workshop auto-detects the correct location. If import can't find files, it provides platform-specific troubleshooting.

🤝 Integration with Claude Code

Workshop provides three integration points:

1. Session Start Hook

Loads project context when Claude Code starts:

~/.claude/projects/myproject/workshop-session-start.sh

2. Session End Hook

Captures session summary when Claude Code exits:

~/.claude/projects/myproject/workshop-session-end.sh

3. Pre-Compact Hook

Preserves context before compaction:

~/.claude/pre-compact/workshop-pre-compact.sh

All hooks are set up automatically by workshop init.

📊 Why the Test Coverage Matters

Workshop has 63% test coverage with 128 tests across:

  • JSONL parsing and pattern extraction (95% coverage)
  • SQLite storage operations (75% coverage)
  • Configuration management (98% coverage)
  • Display and formatting (27% coverage - mostly console I/O)

This isn't just for show—it means:

  • ✅ Reliable imports that won't corrupt your data
  • ✅ Safe schema migrations when upgrading
  • ✅ Consistent behavior across platforms
  • ✅ Confidence that Workshop won't lose your knowledge

Production-ready means tested.

📝 Example Use Cases

1. Architectural Decision Records

# Claude automatically captures these during conversations
workshop why "microservices"

# Output:
# 💡 DECISION (2 weeks ago)
# Using microservices architecture for backend
# Why: Need independent scaling of services, team prefers polyglot approach

2. Onboarding New Team Members

workshop context
workshop sessions --limit 10

# New devs can see entire project history:
# - What decisions were made and why
# - What gotchas to avoid
# - Current architecture and patterns

3. Debugging Production Issues

workshop search "authentication flow"

# Instantly find all discussions about auth:
# - Original implementation decisions
# - Known gotchas with OAuth
# - Recent changes to token handling

4. Resuming After Time Away

# After weeks off the project:
workshop recent
workshop context

# Claude: "Welcome back! Since your last session:
#  - Completed caching implementation
#  - Discovered rate limiting issue with API
#  - Next step: Add retry logic with exponential backoff"

🎯 Roadmap

Workshop v1.0.0 is feature-complete for core use cases. Future possibilities:

  • Team Sync: Share Workshop knowledge across team members
  • Slack/Discord Integration: Bot that answers project questions
  • GitHub Integration: Link decisions to PRs and issues
  • Advanced Analytics: Visualize decision timelines
  • AI-Powered Summaries: Automatically generate weekly summaries

Have ideas? Open an issue or start a discussion!

📚 Documentation

🤝 Contributing

We welcome contributions! If you find a bug or have a feature request, please open an issue.

For bug reports, please include:

  • Workshop version (pip show claude-workshop)
  • Python version (python --version)
  • Operating system
  • Steps to reproduce
  • Error messages or logs

Pull requests are welcome! For major changes, please open an issue first to discuss.

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built with Claude Code - an AI pair programmer that needed better memory. Workshop exists because developers and AI assistants both benefit from persistent context.

Workshop is for Claude, by Claude (and humans who want their AI to remember).

⭐ Star History

If Workshop helps your workflow, consider starring the repo to help others discover it!

Star History Chart

Ready to give Claude long-term memory?

pip install claude-workshop && workshop init

🚀 That's it. Claude now remembers everything.

About

Give Claude long-term memory for your projects

Resources

Readme
Activity

Stars

8 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

27 tags

Packages

No packages published

Languages