Skip to content
BranchesTags

Repository files navigation

RizzClaw 🐾

RizzClaw Logo

AI-Powered Coding Assistant

license go version

Introduction

RizzClaw is an AI-powered intelligent coding assistant built on MiniMax large language models. It helps developers with various tasks including code writing, debugging, file operations, web search, and more.

✨ Core Features

🚀 Gateway Multi-Channel Support

RizzClaw 0.2.0 introduces Gateway Mode, supporting multiple channels for AI interaction:

  • Feishu (Lark) - Enterprise instant messaging integration
  • Console - Command-line interactive mode
  • Extensible Architecture - Easy to add Telegram, Discord, and more channels

Gateway Architecture

┌─────────────────────────────────────────┐
│              Gateway                    │
│  ┌─────────┐    ┌──────────────┐       │
│  │ Agent   │◄──►│  MessageBus  │       │
│  │  Loop   │    │              │       │
│  └─────────┘    └──────┬───────┘       │
│         ▲              │                │
│         │         ┌────┴────┐          │
│         │         │ Channels│          │
│         │         ├────┬────┤          │
│         │         │Feishu│Console│      │
│         │         └────┴────┘          │
│         ▲                              │
│    LLM API                             │
└─────────────────────────────────────────┘

Multi-User Session Isolation

Gateway mode supports multiple users simultaneously, with each user/group having independent conversation context:

User A DM → feishu_chat_aaa_user_aaa.jsonl
User B DM → feishu_chat_bbb_user_bbb.jsonl
Group Chat → feishu_group_ccc_user_aaa.jsonl

🧠 Smart Session Management (Auto-Summary)

RizzClaw features an intelligent session compression mechanism that automatically manages context windows during long conversations:

  • Auto-Compression Trigger: Compression is triggered when session tokens exceed the threshold (default: 50% of 128K)
  • Smart Summary Generation: Early conversations are compressed into concise summaries, preserving key information while significantly reducing token usage
  • Configurable Parameters:
    • MaxTokens: Maximum token limit (default: 128000)
    • MaxHistoryShare: Maximum share of history messages (default: 0.5)
    • MinMessagesToKeep: Number of recent messages to keep (default: 10)
    • ChunkRatio: Compression ratio (default: 0.4)
┌─────────────────────────────────────────────────────────────┐
│  Session History                                             │
├─────────────────────────────────────────────────────────────┤
│  [Summary] Summary of 50 earlier messages...                │
│  [Summary] Summary of 30 mid-session messages...            │
├─────────────────────────────────────────────────────────────┤
│  [Recent] User: Help me refactor this function              │
│  [Recent] Assistant: Sure, let me help you...               │
│  ...                                                         │
└─────────────────────────────────────────────────────────────┘

💾 Long-term Memory System (BM25 + RAG)

RizzClaw implements an advanced hybrid retrieval memory system supporting long-term knowledge storage and intelligent recall:

Hybrid Retrieval Architecture

                    ┌──────────────────┐
                    │   User Query      │
                    └────────┬─────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
     ┌────────────────┐ ┌────────────────┐
     │  Vector Search │ │  BM25 Keyword  │
     │  (Semantic)    │ │  (Exact Match) │
     └───────┬────────┘ └───────┬────────┘
             │                  │
             │    ┌─────────────┘
             ▼    ▼
     ┌────────────────────┐
     │   Score Fusion     │
     │  Vector: 0.7       │
     │  Keyword: 0.3      │
     └─────────┬──────────┘
               ▼
     ┌────────────────────┐
     │   MMR Reranking    │
     │   (Optional)       │
     └─────────┬──────────┘
               ▼
     ┌────────────────────┐
     │   Temporal Decay   │
     │   (Optional)       │
     └─────────┬──────────┘
               ▼
         Final Results

Core Technologies

Technology Description
BM25 Full-text Search Built on SQLite FTS5, supports Chinese and English keyword search with precise matching of key terms in user queries
Vector Semantic Search Supports embedding model integration for semantic-level similarity search, understanding query intent beyond keyword matching
Hybrid Score Fusion Vector search weight 0.7 + keyword search weight 0.3, fully customizable
MMR Diversity Reranking Maximal Marginal Relevance algorithm avoids overly similar results, improving information coverage
Temporal Decay Based on exponential decay function, older memories have lower weights with default 30-day half-life
Evergreen Memory Memories marked as Evergreen never decay, ideal for storing user preferences, project context, and other long-term information

Memory Storage

type MemoryEntry struct {
    ID          string    // Unique identifier
    Content     string    // Memory content
    Embedding   []float32 // Vector embedding
    Keywords    []string  // Extracted keywords
    Source      string    // Source (e.g., "MEMORY.md", "conversation")
    CreatedAt   time.Time // Creation timestamp
    IsEvergreen bool      // Whether it's an evergreen memory
}

Search Configuration

type SearchOptions struct {
    MaxResults     int     // Maximum number of results (default: 6)
    MinScore       float64 // Minimum score threshold (default: 0.35)
    VectorWeight   float64 // Vector search weight (default: 0.7)
    KeywordWeight  float64 // Keyword search weight (default: 0.3)
    UseMMR         bool    // Enable MMR (default: false)
    MMRLambda      float64 // MMR relevance weight (default: 0.7)
    TemporalDecay  bool    // Enable temporal decay (default: true)
    HalfLifeDays   float64 // Temporal decay half-life (default: 30 days)
}

🛠️ Other Features

  • 🤖 AI-Powered - Built on advanced MiniMax M2.1/M2.5 large language models
  • 📁 Rich Tools - Built-in file operations, code execution, web search, and more
  • ⚡ Skills System - Compatible with skills.sh ecosystem, load custom skill extensions

🎯 Skills System

RizzClaw supports the skills.sh ecosystem, allowing you to extend AI capabilities with modular skill packages.

Installing Skills

# Install a skill globally
npx skills add vercel-labs/agent-skills

# Install a skill for current project
npx skills add vercel-labs/agent-skills --local

Skills Loading Paths

Skills are automatically loaded from the following directories (in priority order):

Priority Path Description
1 ./.rizzclaw/skills/ Project custom skills
2 ./skills/ Project skills
3 ./.agents/skills/ Project-level skills (npx skills add --local)
4 ~/.rizzclaw/skills/ User custom skills
5 ~/.agents/skills/ Global skills (npx skills add)

Skills CLI Commands

# List all skills
rizzclaw skills list

# List only eligible skills (enabled + dependencies met)
rizzclaw skills list --eligible

# Show skill details
rizzclaw skills info <skill-id>

# Enable/disable a skill
rizzclaw skills enable <skill-id>
rizzclaw skills disable <skill-id>

# Check skill dependencies
rizzclaw skills check [skill-id]

# Reload skills from disk
rizzclaw skills reload

Skill File Format (SKILL.md)

---
name: my-skill
description: "Description of what this skill does"
version: "1.0.0"
author: YourName
emoji: "🚀"
when: "When to use this skill"
tags:
  - tag1
  - tag2
requires:
  bins:
    - git
  env:
    - GITHUB_TOKEN
---

# Skill Instructions

Detailed instructions for the AI agent...

Dependency Checking

Skills can declare dependencies that are checked at runtime:

  • requires.bins - Required binaries (all must be available)
  • requires.anyBins - Alternative binaries (at least one must be available)
  • requires.env - Required environment variables
  • os - Supported operating systems

Skills with unmet dependencies are automatically excluded from the prompt.

🔍 Web Search

  • DuckDuckGo Integration - Uses DuckDuckGo HTML search instead of Bing for better accessibility
  • Proxy Support - Automatically reads proxy configuration from environment variables:
    • HTTP_PROXY / http_proxy - HTTP proxy
    • HTTPS_PROXY / https_proxy - HTTPS proxy
    • NO_PROXY / no_proxy - Bypass proxy for specific hosts

Tech Stack

  • Language: Go 1.23+
  • CLI Framework: Cobra
  • Configuration: Viper
  • Database: SQLite3 (memory storage)
  • Full-text Search: SQLite FTS5 (BM25)
  • LLM Provider: MiniMax API

Quick Start

Screenshot

RizzClaw Console

Installation

# Clone the project
git clone https://github.com/hoorayman/rizzclaw.git
cd rizzclaw

# Build
go build -o rizzclaw ./main.go

# Run
./rizzclaw chat

Configuration

  1. Copy the example config file:
cp config.example.json ~/.rizzclaw/config.json
  1. Edit config.json and add your MiniMax API Key:
{
  "models": {
    "mode": "merge",
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/anthropic",
        "apiKey": "API_KEY",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "MiniMax-M2.1",
            "name": "MiniMax M2.1",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0.3,
              "output": 1.2,
              "cacheRead": 0.03,
              "cacheWrite": 0.12
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "MiniMax-M2.1-lightning",
            "name": "MiniMax M2.1 Lightning",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0.3,
              "output": 1.2,
              "cacheRead": 0.03,
              "cacheWrite": 0.12
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "MiniMax-M2.5",
            "name": "MiniMax M2.5",
            "reasoning": true,
            "input": ["text"],
            "cost": {
              "input": 0.3,
              "output": 1.2,
              "cacheRead": 0.03,
              "cacheWrite": 0.12
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "MiniMax-M2.5-Lightning",
            "name": "MiniMax M2.5 Lightning",
            "reasoning": true,
            "input": ["text"],
            "cost": {
              "input": 0.3,
              "output": 1.2,
              "cacheRead": 0.03,
              "cacheWrite": 0.12
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "MiniMax-VL-01",
            "name": "MiniMax VL 01",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": {
              "input": 0.3,
              "output": 1.2,
              "cacheRead": 0.03,
              "cacheWrite": 0.12
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "minimax/MiniMax-M2.5": {
          "primary": "minimax/MiniMax-M2.5",
          "alias": "Minimax"
        }
      },
      "timeout": 120
    }
  }
}

Usage

# Show help
rizzclaw --help

# Start interactive chat (Console mode)
rizzclaw chat

# Start Gateway service
rizzclaw gateway

# Start Gateway in debug mode (show message logs)
rizzclaw gateway -d

# List available models
rizzclaw models

# Show current configuration
rizzclaw config show

# Skills management
rizzclaw skills list              # List all skills
rizzclaw skills list --eligible   # List eligible skills only
rizzclaw skills info <skill-id>   # Show skill details
rizzclaw skills enable <skill-id> # Enable a skill
rizzclaw skills disable <skill-id># Disable a skill
rizzclaw skills check             # Check skill dependencies
rizzclaw skills reload            # Reload skills from disk

Interactive Commands

In chat mode, the following commands are available:

Command Description
/exit or /quit Exit the conversation
/clear Clear current session history
/help Show help information

Feishu Integration

  1. Create an enterprise app on Feishu Open Platform and obtain App ID and App Secret

  2. Add Feishu configuration to config.json:

{
  "channels": {
    "feishu": {
      "enabled": true,
      "app_id": "cli_xxxxxxxx",
      "app_secret": "xxxxxxxx",
      "encrypt_key": "optional",
      "verification_token": "optional",
      "allow_from": []
    }
  }
}
  1. Start the Gateway service:
rizzclaw gateway
  1. Search for your app in Feishu and start chatting

Feishu Conversation Examples

Feishu Example 1 Feishu Example 2 Feishu Example 3

Project Structure

rizzclaw/
├── cmd/                # CLI command entry
│   ├── root.go         # Root command and chat command
│   ├── gateway.go      # Gateway command
│   └── skills.go       # Skills management commands
├── internal/           # Internal packages
│   ├── agent/          # Agent core logic
│   │   ├── agent.go    # Agent implementation
│   │   └── session.go  # Session management
│   ├── llm/            # LLM client abstraction
│   ├── tools/          # Tool collection
│   ├── skills/         # Skills system
│   │   ├── loader.go   # Skill loader (SKILL.md parser)
│   │   └── registry.go # Skill registry & dependency checking
│   ├── context/        # Context management
│   │   ├── manager.go  # Context manager
│   │   ├── session.go  # Session storage & compression
│   │   ├── memory.go   # Memory storage & retrieval
│   │   └── types.go    # Type definitions
│   ├── minimax/        # MiniMax API integration
│   └── config/         # Configuration management
├── docs/               # Documentation resources
│   └── pics/           # Image resources
└── main.go             # Program entry point

Supported Models

Model Name Type Context Window Max Output
MiniMax-M2.1 Text 200K 8K
MiniMax-M2.1-lightning Text 200K 8K
MiniMax-M2.5 Reasoning 200K 8K
MiniMax-M2.5-Lightning Reasoning 200K 8K
MiniMax-VL-01 Multimodal 200K 8K

Data Storage Location

All data is stored in the .rizzclaw folder in the user's home directory:

~/.rizzclaw/
├── config.json        # Configuration file
├── memory.db          # Memory database (SQLite)
├── sessions/          # Session storage
│   └── session-*.jsonl
├── workspace/         # Context files
│   ├── MEMORY.md      # Long-term memory
│   ├── USER.md        # User preferences
│   └── ...
└── skills/            # Skills registry
    └── skills.json    # Skills state (enabled/disabled)

~/.agents/skills/      # Global skills (npx skills add)
├── skill-a/
│   └── SKILL.md
└── skill-b/
    └── SKILL.md

License

MIT License - See LICENSE file for details

Made with ❤️ by RizzClaw

About

Go-based AI assistant with auto-summary sessions and BM25+RAG memory system

Resources

Readme
MIT license
Activity

Stars

120 stars

Watchers

18 watching

Forks

21 forks
Report repository

Releases

Packages

Contributors

Languages