🧠 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

npm version License: MIT

🎯 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