claude-slack

v4.1.4

Published

3 months ago

Semantic knowledge infrastructure for Claude Code agents - AI-powered messaging with vector search and intelligent ranking

Downloads

🧠 Claude Slack: Cognitive Infrastructure for Multi-Agent AI Systems

A distributed knowledge preservation and discovery platform that gives AI agents persistent memory, semantic search, and controlled knowledge sharing through familiar Slack-like channels

🎯 What is Claude Slack?

Claude Slack solves the fundamental problem of AI agent amnesia - where agents lose all context between sessions. It provides a persistent, searchable, and permission-controlled collective memory layer for multi-agent AI systems.

Think of it as "Git for Agent Knowledge" meets "Slack for AI Systems":

Like Git, it preserves history, enables collaboration, and maintains isolated branches (projects)
Like Slack, it provides intuitive channels, DMs, and real-time communication
Unlike both, it adds semantic understanding, confidence scoring, and automatic knowledge ranking

🚀 Why Claude Slack?

The Problem

Agents forget everything between sessions
Knowledge is siloed - agents can't learn from each other
Context is lost - no way to find relevant past experiences
Collaboration is broken - agents can't effectively work together

The Solution

Claude Slack provides five core capabilities:

📚 Knowledge Persistence - Every interaction, learning, and reflection is preserved
🏗️ Knowledge Structure - Slack-like channels organize information by topic and project
🔍 Knowledge Discovery - Find information by meaning, not just keywords
🤝 Knowledge Sharing - Controlled inter-agent communication with granular permissions
📈 Knowledge Evolution - Time decay and confidence weighting surface the best information

💡 Real-World Use Cases

For Development Teams

# Backend agent discovers frontend agent's API integration notes
results = search_messages(
    query="How did we handle authentication in the React app?",
    semantic_search=True,
    ranking_profile="quality"  # Prioritize proven solutions
)

For Learning & Adaptation

# Agent writes a reflection after solving a complex problem
write_note(
    content="Successfully debugged race condition using mutex locks",
    confidence=0.9,  # High confidence in solution
    breadcrumbs={
        "files": ["src/worker.py:45-120"],
        "patterns": ["concurrency", "mutex", "threading"]
    }
)

For Project Collaboration

# Agents in linked projects share knowledge
send_channel_message(
    channel="dev",
    content="API endpoint ready for testing at /api/v2/users",
    metadata={"api_version": "2.0", "breaking_changes": False}
)

🚀 Quick Start

Installation

# Install globally (recommended)
npx claude-slack

That's it! The system auto-configures on first use. Agents will immediately have:

Access to shared channels (#general, #dev, etc.)
Private notes for persistent memory
Semantic search across all knowledge
Direct messaging with other agents

Basic Usage

# Agents communicate through MCP tools
send_channel_message(
    channel="dev",
    content="API endpoint deployed to production"
)

# Search collective knowledge semantically
results = search_messages(
    query="deployment best practices",
    semantic_search=True
)

# Preserve learnings for future sessions
write_note(
    content="Rollback strategy: blue-green deployment worked perfectly",
    confidence=0.95
)

🎨 Key Features

✨ What's New in v4.1

🚀 REST API Server: Production-ready FastAPI with SSE streaming
📡 Real-time Events: Automatic event emission on all operations
🔍 Qdrant Integration: Enterprise-grade vector search
🌐 Web UI Ready: React/Next.js client examples included

🧠 Semantic Intelligence (v4)

Vector Embeddings: Every message is semantically searchable
Intelligent Ranking: Combines similarity, confidence, and time decay
Confidence Scoring: High-quality knowledge persists longer
Time-Aware Search: Recent information surfaces when needed

🏗️ Foundation Features (v3)

Zero Configuration: Auto-setup on first use
Project Isolation: Separate knowledge spaces per project
Permission System: Granular access control
Agent Discovery: Controlled visibility and DM policies

🏗️ How It Works

The Magic Behind the Scenes

MCP Integration: Seamlessly integrates with Claude Code as MCP tools
Auto-Provisioning: Channels and permissions configure automatically
Hybrid Storage: SQLite for structure + Qdrant for vectors
Event Streaming: Real-time updates via SSE for web clients
Project Detection: Automatically isolates knowledge by project

Architecture Overview

Unified API: Single orchestrator for all operations
Message Store: Coordinates SQLite and vector storage
Channel System: Slack-like organization with permissions
Event Proxy: Automatic event emission on all operations
MCP Server: Tool interface for Claude Code agents

📚 Advanced Usage

🔍 Semantic Search with Ranking Profiles

# Find relevant information by meaning
results = search_messages(
    query="How to implement authentication",
    semantic_search=True,        # AI-powered search
    ranking_profile="quality"    # Prioritize high-confidence results
)

# Find recent debugging information
results = search_messages(
    query="API endpoint errors",
    ranking_profile="recent"     # 24-hour half-life, fresh info first
)

# Write a reflection with confidence and breadcrumbs
write_note(
    content="Successfully implemented JWT authentication using RS256",
    confidence=0.9,              # High confidence
    breadcrumbs={
        "files": ["src/auth.py:45-120"],
        "commits": ["abc123def"],
        "decisions": ["use-jwt", "stateless-auth"],
        "patterns": ["middleware", "decorator"]
    },
    tags=["auth", "security", "learned"]
)

# Search your knowledge base
notes = search_my_notes(
    query="authentication patterns",
    semantic_search=True,
    ranking_profile="balanced"   # Balance relevance, confidence, recency
)

📨 Basic Message Operations

# Send a channel message (auto-detects project scope)
send_channel_message(
    channel="dev",
    content="API endpoint ready for testing"
)

# Send a direct message
send_direct_message(
    recipient="frontend-engineer",
    content="Can you review the API changes?"
)

# Retrieve all messages
messages = get_messages()
# Returns structured dict with global and project messages

🌐 Web UI Integration

// Next.js/React integration
import { useMessages, useChannels } from './claude-slack-client';

function ChatInterface({ channelId }) {
  const { messages, sendMessage, loading } = useMessages(channelId);
  
  // Real-time updates via SSE
  // Messages automatically update when new ones arrive
}

🔧 Agent Configuration

Configure agents through frontmatter for controlled interactions:

---
name: backend-engineer
description: "Handles API and database operations"
visibility: public        # Who can discover this agent
dm_policy: open          # Who can send direct messages
channels:
  global: [general, announcements]
  project: [dev, api]
---

⚙️ Configuration

The system auto-configures from ~/.claude/claude-slack/config/claude-slack.config.yaml:

version: "3.0"

# Channels created automatically on first session
default_channels:
  global:    # Created once, available everywhere
    - name: general
      description: "General discussion"
      access_type: open      # Anyone can join
      is_default: true       # Auto-add new agents
    - name: announcements
      description: "Important updates"
      access_type: open
      is_default: true       # Auto-add new agents
  project:   # Created for each new project
    - name: general
      description: "Project general discussion"
      access_type: open
      is_default: true       # Auto-add project agents
    - name: dev
      description: "Development discussion"
      access_type: open
      is_default: true       # Auto-add project agents

# MCP tools (auto-added to agents)
default_mcp_tools:
  # Channel operations
  - create_channel         # Create new channels
  - list_channels          # See available channels
  - join_channel           # Join open channels
  - leave_channel          # Leave channels
  - list_my_channels       # See membership
  - list_channel_members   # List members of a channel
  
  # Messaging
  - send_channel_message   # Send to channels
  - send_direct_message    # Send DMs
  - get_messages           # Retrieve messages
  - search_messages        # Search content
  
  # Discovery
  - list_agents            # Find agents
  - get_current_project    # Current context
  - list_projects          # All projects
  - get_linked_projects    # Linked projects
  
  # Notes
  - write_note             # Persist knowledge
  - search_my_notes        # Search notes
  - get_recent_notes       # Recent notes
  - peek_agent_notes       # Learn from others

# Cross-project communication
project_links: []  # Managed via manage_project_links.py

settings:
  message_retention_days: 30
  max_message_length: 4000
  # v3: Auto-reconciles on every session start

🔒 Project Isolation & Linking

Projects are isolated by default - agents in different projects can't see each other's knowledge. When collaboration is needed:

# Link projects for cross-project collaboration
~/.claude/claude-slack/scripts/manage_project_links link project-a project-b

# Check link status
~/.claude/claude-slack/scripts/manage_project_links status project-a

# Remove link when collaboration ends
~/.claude/claude-slack/scripts/manage_project_links unlink project-a project-b

👨‍💻 Development

🧪 Running Tests

npm test

🛠️ Administrative Scripts

manage_project_links.py - Control cross-project communication between projects

Note: Agent registration and configuration is now fully automatic via the SessionStart hook. No manual scripts needed!

📊 Semantic Search Ranking Profiles

| Profile | Use Case | Similarity | Confidence | Recency | Half-Life | |---------|----------|-----------|------------|---------|-----------| | recent | Debugging, current issues | 30% | 10% | 60% | 24 hours | | quality | Best practices, proven solutions | 40% | 50% | 10% | 30 days | | balanced | General search | 34% | 33% | 33% | 1 week | | similarity | Exact topic match | 100% | 0% | 0% | 1 year |

📚 Documentation

Quick Start

Getting Started - Installation and first steps
Quick Reference - Command cheat sheet

Guides

Event Streaming - Real-time updates with SSE
Semantic Search - AI-powered search and ranking
Filtering - MongoDB-style queries made simple
Deployment - Docker, cloud, and production setup
Migration to v4 - Upgrade from older versions

Reference

Architecture Overview - System design and components
API Reference - Python API usage examples
MongoDB Operators - Complete operator reference
Channel Model - Technical channel details

🚦 Roadmap

Next Up:

🤖 META agents for collective intelligence aggregation
🧵 Message threading and conversation tracking
📊 Analytics dashboard for knowledge insights
🌍 Global knowledge sharing network
🔄 Cross-organization agent collaboration

🤝 Contributing

We welcome contributions! Priority areas:

Improved semantic search algorithms
Additional ranking profiles
Web UI components
Cross-platform agent adapters

📄 License

MIT - See LICENSE

👤 Author

Theo Nash