AIr-Friends

# AIr-Friends

![preview image](./docs/preview.webp)

[![codecov](https://codecov.io/gh/jim60105/AIr-Friends/graph/badge.svg?token=0DtdMc3GBq)](https://codecov.io/gh/jim60105/AIr-Friends) [![Build Status](https://img.shields.io/github/actions/workflow/status/jim60105/AIr-Friends/ci.yaml?branch=master)](https://github.com/jim60105/AIr-Friends/actions) [![Release](https://img.shields.io/github/v/tag/jim60105/AIr-Friends?label=release)](https://github.com/jim60105/AIr-Friends/releases) [![License](https://img.shields.io/badge/license-GPLv3-blue.svg)](LICENSE) [![Container Image](https://img.shields.io/badge/ghcr.io%2Fjim60105%2Fair--friends-available-brightgreen)](https://github.com/jim60105/AIr-Friends/pkgs/container/air-friends)

Your AIr friends custom chatbot with integrated shell and skills. Powered by ACP AI agents, it remembers conversations across channels while keeping your data organized in isolated workspaces.

## ✨ Highlights

- 🤖 **Multi-Platform**: Currently works on Discord and Misskey
- 🧠 **Persistent Memory**: Remembers conversations across different channels
- 🗜️ **Memory Maintenance**: Optional scheduled agent task to summarize and compact old memories
- 📝 **Agent Knowledge Base**: Personal workspace for long-term knowledge notes and reflections
- 🔒 **Privacy First**: Isolated workspaces per user with access control
- 💾 **Git Backup**: Automatic versioned backup of memories and notes to GitHub
- 🐳 **Easy Deploy**: One-command container deployment
- 🎨 **Customizable**: Template-based personality prompt system
- 🔌 **Extensible**: Skill-based architecture

## 🚀 Quick Start

The recommended way to run AIr-Friends is by using containers:

1. **Prepare .env file**

   ```bash
   # Download example file
   wget https://raw.githubusercontent.com/jim60105/AIr-Friends/master/.env.example -O .env

   # Edit with your credentials
   vim .env
   ```

2. **Run with Podman (or Docker)**

   ```bash
   podman run -d --rm \
     -v data:/app/data \
     --env-file .env \
     --name air-friends \
     ghcr.io/jim60105/air-friends:latest
   ```

3. **Or use Compose**

   ```bash
   wget https://raw.githubusercontent.com/jim60105/AIr-Friends/master/compose.yml
   podman compose up -d
   ```

That's it! Your bot should now be online.

## 🎨 Customizing Your Bot

Change the personality of your bot!

Override individual character prompt files — only the files you mount will be replaced; others keep their container defaults.

**With Compose** (recommended — see [`compose.yml`](compose.yml)):

```yaml
volumes:
  - data:/app/data:Z
  # Mount only the prompt files you want to override
  - ./prompts/character_name.md:/app/prompts/character_name.md:ro,Z
  - ./prompts/character_info.md:/app/prompts/character_info.md:ro,Z
  - ./prompts/character_personality.md:/app/prompts/character_personality.md:ro,Z
  - ./prompts/character_speaking_style.md:/app/prompts/character_speaking_style.md:ro,Z
  - ./prompts/character_reference_terms.md:/app/prompts/character_reference_terms.md:ro,Z
```

**With Podman/Docker run:**

```bash
podman run -d --rm \
  -v data:/app/data \
  -v ./prompts/character_name.md:/app/prompts/character_name.md:ro \
  -v ./prompts/character_info.md:/app/prompts/character_info.md:ro \
  --env-file .env \
  --name air-friends \
  ghcr.io/jim60105/air-friends:latest
```

**With Helm** (see [`helm/`](helm/) chart):

```yaml
# values.yaml
prompts:
  enabled: true
  files:
    character_name.md: |
      Yuna
    character_info.md: |
      An AI assistant
```

See [Development Guide -- Customizing the Bot](docs/DEVELOPMENT.md#customizing-the-bot) section for details.

## 🔐 Access Control

Control who can interact with your bot using the whitelist feature:

```yaml
accessControl:
  replyTo: "whitelist" # Options: all, public, whitelist
  whitelist:
    - "discord/account/123456789012345678"
    - "misskey/account/abcdef1234567890"
```

See [Development Guide -- Access Control & Reply Policy](docs/DEVELOPMENT.md#access-control--reply-policy) section for details.

## 🛡️ Rate Limiting

Prevent excessive API usage per user with configurable rate limiting:

```yaml
rateLimit:
  enabled: false
  maxRequestsPerWindow: 10
  windowMs: 600000    # 10-minute sliding window
  cooldownMs: 600000  # Cooldown after limit exceeded
```

## 🏗️ Architecture

AIr-Friends acts as an [ACP (Agent Client Protocol)](https://agentclientprotocol.com/) client, delegating AI reasoning to external agents while maintaining persistent memory:

```text
┌─────────────────────────────────────────┐
│  Platform (Discord/Misskey)             │
│            ↓                            │
│  AIr-Friends (ACP Client)               │
│            ↓                            │
│  External AI Agent                      │
│  (Copilot/Gemini/OpenCode)              │
│            ↓                            │
│  Skills & Memory System                 │
└─────────────────────────────────────────┘
```

See [Design Document](docs/DESIGN.md) for detail

... (truncated)