FreeChat 💬

Your all-in-one, portable terminal AI chat tool - v2.4.0 with TUI Interface

FreeChat is a powerful, easy-to-deploy single-file AI chat command line tool, designed specifically for use on cloud VPS. After connecting via SSH, it provides you with a full-screen TUI (Terminal User Interface) with split panes, scrollable chat history, and a collapsible sidebar.

✨ Core Features

🖥️ Full-Screen TUI: A real terminal user interface with split layout — scrollable chat area, persistent header (model, prompt, cost), collapsible sidebar, and dedicated input area. No more fire-and-forget REPL.
✅ Ultimate Simplified Deployment: A true single-script file with no complex environment configuration required. Built-in intelligent dependency installer works out-of-the-box in a Python 3.7+ environment.
📦 Portable Mode: Supports saving all configuration, history, and session data in a directory alongside the script, making it easy to package, backup, and migrate as a whole.
📡 Multi-AI Provider Support: Seamlessly integrates with OpenRouter, OpenAI, Gemini, NVIDIA, and more, allowing for easy switching and optimal selection.
🧠 Universal Model Access: Dynamically retrieves and connects to any model from different providers, supporting instant selection and switching directly in the CLI.
🎨 Customizable AI Roles: Easily define and switch AI system prompts through a simple configuration file, allowing it to play different roles such as programmer, translator, etc.
🚀 Streaming Chat with Live Updates: AI responses stream directly into the chat area with real-time display updates.
📊 Performance and Cost Visualization: The header bar displays current model, active prompt, session cost, and session name in real-time.
💡 Intelligent Command Line Experience: Features command autocompletion (Tab), history navigation (↑↓), and auto-suggestions in the input area.
⌨️ TUI Keyboard Shortcuts: F1 for help, F2 to toggle sidebar, Ctrl+Enter to send, Ctrl+D to exit.
💾 Session Management and Export: Supports creating, saving, and loading chat sessions, with the ability to easily export session records in Markdown, JSON, or HTML formats.
🧠 Memory System with Auction Compression: Advanced long-term memory with automatic value-based compression using auction algorithms. Supports global and Git branch-specific memories with SQLite storage and full-text search.
⚡ Performance Optimizations: Includes connection pooling, model caching, token counting optimization, and memory management for faster response times and reduced resource usage.

🚀 Installation and Setup

FreeChat is designed to be "out-of-the-box." You only need a Linux environment with Python 3.7+ and pip installed.

Get started in just 4 steps:

Download the script
Download the latest script file freechat.py to your VPS.
```
wget <URL_to_your_script>/freechat.py
```
First run (automatic dependency installation)
Run the script directly with Python 3. It will automatically detect missing dependencies and prompt you to install them.
```
python3 freechat.py
```
When you see the prompt Do you want to proceed with the installation? [Y/n]:, press Enter or type y. The script will automatically complete the installation and restart.
Configure API Keys (critical step)
After dependencies are installed, the script will detect that there's no configuration file and automatically create config.toml and prompts.toml files in the default location ~/.config/freechat/.

You need to edit the main configuration file and enter your API keys.
```
nano ~/.config/freechat/config.toml
```
Fill in the API Key you obtained from platforms like OpenAI, OpenRouter, etc., following the comments in the file.
Run again and start chatting!
After configuration, run the script again to enter the chat interface.
```
python3 freechat.py
```

🧠 Memory System

FreeChat includes an advanced memory system for long-term context preservation across sessions. This system uses SQLite for efficient storage with full-text search capabilities and implements intelligent auction-based compression to manage storage limits.

Core Features

Global and Branch-Specific Memories: Support global memory storage or associate memories with specific Git branches for context-aware branch switching
Automatic Value Scoring: Calculates comprehensive scores for each memory based on importance, relevance, recency, and access frequency
Auction Compression Mechanism: Automatically compresses or archives low-value memories when storage limits are reached
Full-Text Search: Fast memory retrieval based on SQLite FTS5
Git Integration: Automatic detection of Git branch switches to load corresponding branch-specific memories

Memory Commands

# Store a new memory
> /memory remember "User prefers Python over JavaScript"
✓ Recorded (mem_abc123)

# Search memories
> /memory recall "programming preferences"
[Displays matching memories]

# List all memories (with scores)
> /memory list
ID       Category    Content                           Score    Access
mem_abc  preference  User prefers dark mode interface   0.85     5
...

# Run auction compression
> /memory compress
✓ Compressed 15 memories (archived low-value memories)

# View statistics
> /memory stats
Total memories: 42
Active: 37 | Archived: 5
Average score: 0.72

# Show branch-specific memories
> /memory branch feature/new-ui
[Displays memories for feature/new-ui branch]

Storage

Memories are stored in an SQLite database at ~/.config/freechat/memories/memories.db (or freechat_config/memories/memories.db in portable mode). The database includes:

Main memories table with full-text search index
memory_tags table for tag management
FTS5 virtual table for efficient content search
Automatic triggers to keep search indexes synchronized

Auction Algorithm

The auction-based compression uses weighted scoring:

Importance (40%): User-specified importance (1-10)
Relevance (30%): Based on tag richness
Recency (20%): Exponential decay (half-life 30 days)
Frequency (10%): Normalized access count

Memories below the storage limit threshold are compressed or archived to maintain optimal memory performance.

🛠️ Skill System

FreeChat includes a powerful Skill system that allows you to extend functionality through installable skill packages. Skills can provide custom tools that AI can use to help answer your questions.

Skill Package Structure

A skill package is a directory containing:

my_skill/
├── skill.toml          # Skill metadata (required)
└── README.md           # Documentation (optional)

Creating a Skill

Create a skill.toml file:

[skill]
name = "weather-skill"
version = "1.0.0"
description = "Get weather information for any city"
author = "Your Name"
entry_point = "main:initialize"
dependencies = []

[[tools]]
name = "get_weather"
description = "Get current weather for a city"
parameters = [
    { name = "city", type = "string", required = true, description = "City name" },
    { name = "units", type = "string", required = false, description = "Temperature units (celsius/fahrenheit)" }
]

Skill Commands

Install a Skill

> /skill install /path/to/your_skill
✓ Skill 'weather-skill' v1.0.0 installed successfully

List Installed Skills

> /skill list
Name          Version  Description                    Tools
weather-skill 1.0.0    Get weather information        1
example-skill 1.0.0    An example skill               2

View Skill Information

> /skill info weather-skill
╭──────────────────── Skill Information ─────────────────────╮
│ weather-skill v1.0.0                                        │
│ Author: Your Name                                           │
│ Description: Get weather information for any city           │
│ Tools: get_weather                                          │
╰─────────────────────────────────────────────────────────────╯

Uninstall a Skill

> /skill uninstall weather-skill
✓ Skill 'weather-skill' uninstalled successfully

Using Skills in Conversation

Once a skill is installed, its tools are automatically available to the AI. You don't need to do anything special - just chat naturally:

> 北京今天天气怎么样？
[AI will automatically use the get_weather tool with city=

`FreeChat` supports two configuration modes that you can easily switch between **without modifying any code**.

### Mode One: Global Mode (Default)

By default, `FreeChat` stores all configuration files and data in the standard location under your user's home directory:
*   **Address**: `~/.config/freechat/`

This is the recommended approach for Linux applications, keeping your home directory organized.

### Mode Two: Portable Mode (Recommended for Backup and Migration)

If you want to keep all configuration (API keys, prompts), history, and session data together with the script file for easy packaging and backup, you can activate portable mode.

**How to activate portable mode:**

Very simple. Just create a folder named `freechat_config` in the **same directory** as the `freechat.py` script.

```bash
# Assuming freechat.py is in /home/user/my_apps/ directory
cd /home/user/my_apps/

# Create configuration folder
mkdir freechat_config

Now your directory structure looks like this:

my_apps/
├── freechat.py
└── freechat_config/   <-- The existence of this folder activates portable mode

When you run python3 freechat.py again, it will automatically detect this folder and redirect all data read/write operations here. If it's the first run, it will create files like config.toml here.

Migrating from global mode to portable mode:

If you want to migrate existing global configuration to portable mode, simply move the contents of the old directory to the new directory:

# Make sure the freechat_config folder has been created
mv ~/.config/freechat/* /path/to/your/script/freechat_config/

📖 Usage Guide

FreeChat launches a full-screen TUI with the following layout:

┌─────────────────────────────────────────────────────────────┐
│ Model: openai/gpt-4o  |  Prompt: default  |  Cost: $0.05   │
├────────────────────────────────────────┬────────────────────┤
│                                        │ Commands           │
│  Chat Area (scrollable)                │ /help   Show help  │
│  You: Hello                            │ /model  Model mgmt │
│  AI: Hi! How can I help?               │ /prompt Switch...  │
│                                        │ /memory Memory...  │
│                                        │                    │
│                                        │ Status             │
│                                        │ Messages: 5        │
├────────────────────────────────────────┴────────────────────┤
│ > _                                                          │
├─────────────────────────────────────────────────────────────┤
│ F1=Help  F2=Sidebar  Ctrl+Enter=Send  Ctrl+D=Exit          │
└─────────────────────────────────────────────────────────────┘

Chat: Type your message in the input area and press Ctrl+Enter to send. AI responses stream directly into the chat area.
Commands: All special functions use slash commands /. Type / and press Tab to autocomplete.
Sidebar: Press F2 to toggle the sidebar showing available commands and session status.
Help: Press F1 or type /help to see the command list.

TUI Keyboard Shortcuts

Key	Action
`Ctrl+Enter`	Send message
`F1`	Show help
`F2`	Toggle sidebar
`Ctrl+D`	Exit application
`Ctrl+C`	Clear input
`Tab`	Autocomplete command/model

Memory System

FreeChat includes an advanced memory system for long-term context preservation across sessions.

Memory Commands:

/memory remember <text> [--cat <category>] [--tags <t1,t2>] - Store a new memory with optional category and tags (auto-detects duplicates)
/memory recall <query> - Search memories using full-text search
/memory search <query> [opts] - Advanced search with filters (--cat, --tags, --min-score, --min-importance)
/memory list [category] - List memories, optionally filter by category
/memory top [n] - Show highest value memories (default: 10)
/memory recent [n] - Show recently accessed memories (default: 10)
/memory categories - List all categories with memory counts
/memory view <id> - View a single memory in detail
/memory edit <id> <content> - Edit memory content
/memory tag <id> <tags...> - Set tags for a memory
/memory category <id> <category> - Change memory category
/memory priority <id> <1-10> - Set memory importance (1-10)
/memory related <id> - Find memories related by tags or category
/memory forget <id> - Delete a specific memory by ID
/memory restore <id> - Restore an archived memory
/memory compress - Run auction-based compression to archive low-value memories
/memory clear --force - Delete ALL memories permanently
/memory stats - Display memory statistics
/memory branch - List Git branches with memories
/memory merge <from> <to> - Merge memories from one branch to another
/memory export <file.json> - Export memories to JSON file
/memory import <file.json> - Import memories from JSON file

The memory system uses SQLite with FTS5 full-text search and implements an auction algorithm for intelligent compression based on importance, relevance, recency, and access frequency.

Markdown Rendering Support

FreeChat now supports exporting sessions with rendered Markdown content. When you use the /export md-rendered command, it will generate an HTML file with properly formatted Markdown content, including bold text, italic text, code blocks, and other Markdown elements rendered in a visually appealing way.

⌨️ Command Reference

Command	Parameters	Description
`/help`	(none)	Display this help message.
`/model`	(none)	Show the current model with detailed information (provider, status, favorites).
	`<provider/model_name>`	Switch the currently used AI model. Example: `/model openai/gpt-4o`. Automatically records to recent models.
	`list`	List all available models from all configured providers.
	`list <provider>`	List models from a specific provider (e.g., `/model list openai`).
	`search <keyword>`	Search models by keyword across all providers.
	`info <name>`	Show detailed information about a model, including pricing (if available).
	`recent`	Display recently used models (up to 10).
	`fav`	Display your favorite models list.
	`fav <name>`	Add or remove a model from favorites.
`/prompt`	`list`	Lists all available system prompts defined in `prompts.toml`.
	`view`	View the full content of the currently used system prompt.
	`<name>`	Switch to the specified system prompt and automatically start a new session. Example: `/prompt coder`.
`/session`	`new`	Start a completely new chat session with the default system prompt applied.
	`save <name>`	Save the current session with a name.
	`load <name>`	Load a previously saved session.
	`list`	List all saved sessions.
`/file`	`upload <path>`	Upload and process a file. Supported formats: txt, md, json, csv, py, js, html, css, pdf.
`/language`	`<code>`	Switch interface language. Use without arguments to list available languages.
`/export`	`<format>`	Export the current session to a file in the specified format. Supported formats: `md`, `json`, `html`, `md-rendered`.
`/clear`	(none)	Clear the current terminal screen.
`/exit`	(none)	Exit the FreeChat application.
`/memory`	`remember <text> [--cat <c>] [--tags <t1,t2>]`	Store a new memory with optional category and tags (auto-detects duplicates).
	`recall <query>`	Search memories using full-text search.
	`search <query> [opts]`	Advanced search with filters (`--cat`, `--tags`, `--min-score`, `--min-importance`).
	`list [category]`	List memories, optionally filter by category.
	`top [n]`	Show highest value memories (default: 10).
	`recent [n]`	Show recently accessed memories (default: 10).
	`categories`	List all categories with memory counts.
	`view <id>`	View a single memory in detail.
	`edit <id> <content>`	Edit memory content.
	`tag <id> <tags...>`	Set tags for a memory.
	`category <id> <cat>`	Change memory category.
	`priority <id> <1-10>`	Set memory importance (1-10).
	`related <id>`	Find memories related by tags or category.
	`forget <id>`	Delete a specific memory by ID.
	`restore <id>`	Restore an archived memory.
	`compress`	Run auction-based compression to archive low-value memories.
	`clear --force`	Delete ALL memories permanently.
	`stats`	Display memory statistics.
	`branch`	List Git branches with memories.
	`merge <from> <to>`	Merge memories from one branch to another.
	`export <file.json>`	Export memories to JSON file.
	`import <file.json>`	Import memories from JSON file.
`/skill`	`list`	List all installed skills.
	`install <path>`	Install a skill from a local directory.
	`uninstall <name>`	Remove an installed skill.
	`info <name>`	Display detailed information about a skill.

⚙️ Configuration Files Explained

FreeChat uses two configuration files that are automatically created on the first run.

1. Main Configuration File: `config.toml`

This file stores your API keys and general settings.

# FreeChat Main Configuration

[general]
# Set the model to load by default at startup.
# Format is "provider_name/model_identifier".
default_model = "openrouter/openrouter/free"

# Set the system prompt name to load by default at startup. This name corresponds to an entry in prompts.toml.
default_prompt = "default"

[providers]
# Enter your API keys here.

# OpenAI: https://platform.openai.com/api-keys
openai_api_key = ""

# OpenRouter.ai: https://openrouter.ai/keys (recommended, includes many free models)
openrouter_api_key = ""

# Google Gemini: https://aistudio.google.com/app/apikey
gemini_api_key = ""

# Anthropic: https://console.anthropic.com/settings/keys
anthropic_api_key = ""

# Mistral: https://console.mistral.ai/api-keys
mistral_api_key = ""

# NVIDIA: https://build.nvidia.com/explore/discover
nvidia_api_key = ""

2. System Prompts File: `prompts.toml`

This file allows you to define multiple AI roles or instruction sets.

# FreeChat System Prompts
# Define different roles or instructions for the AI here.
# Switch between them in the app using the /prompt <name> command.
# TOML format supports using triple quotes to define multi-line strings.

[default]
prompt = """You are FreeChat, a helpful and concise AI assistant running in a terminal."""

[coder]
prompt = """You are an expert programmer. Provide only code solutions."""

[translator]
prompt = """You are a multilingual translator. Your task is to translate the user's text into English."""

🚀 Deployment Options

Docker Deployment

FreeChat can be deployed using Docker for easier management and isolation.

Steps to deploy with Docker:

Build the Docker image
```
docker build -t freechat .
```

Run the Docker container

docker run -it --name freechat -v ./freechat_config:/app/freechat_config freechat

Using docker-compose

docker-compose up -d
docker-compose exec freechat python freechat.py

System Service Installation

FreeChat can be installed as a system service using systemd.

Steps to install as a system service:

Edit the service file
```
nano freechat.service
```
Replace your_username with your actual username and /path/to/freechat with the actual path to your FreeChat installation.

Copy the service file

sudo cp freechat.service /etc/systemd/system/

Reload systemd and start the service

sudo systemctl daemon-reload
sudo systemctl enable freechat
sudo systemctl start freechat

Check the service status
```
sudo systemctl status freechat
```

🤔 Frequently Asked Questions (FAQ)

Q: Error INCOMPATIBLE PYTHON VERSION on startup.
A: FreeChat requires Python 3.7 or higher. Your system's Python version is too old. It's recommended to install a newer Python version using tools like pyenv.
Q: HTTP Error 401 Unauthorized during chat.
A: Your API key is incorrect. Please check that the api_key in the config.toml file is filled in correctly.
Q: HTTP Error 429 Too Many Requests during chat.
A: You have reached the service provider's rate limit or usage quota. Please log in to the service provider's platform to check your account status.
Q: Can I add new AI providers?
A: Absolutely. The script's AIProvider abstract class is designed for easy extension. You just need to create a subclass for the new API, referring to the implementation of OpenAIProvider or GeminiProvider.
Q: How to run FreeChat in Docker?
A: Follow the Docker deployment instructions in the Deployment Options section.
Q: How to install FreeChat as a system service?
A: Follow the system service installation instructions in the Deployment Options section.

📄 License

This project is licensed under the GNU General Public License v3.0.

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
example_skill		example_skill
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
SKILL_QUICK_START.md		SKILL_QUICK_START.md
SKILL_SYSTEM_SUMMARY.md		SKILL_SYSTEM_SUMMARY.md
TOOLS_README.md		TOOLS_README.md
docker-compose.yml		docker-compose.yml
freechat.py		freechat.py
freechat.service		freechat.service
performance_test.py		performance_test.py
readme.md		readme.md
readme_cn.md		readme_cn.md
test_freechat.py		test_freechat.py
test_skill_memory.py		test_skill_memory.py

Folders and files

Latest commit

History

Repository files navigation

FreeChat 💬

✨ Core Features

🚀 Installation and Setup

🧠 Memory System

Core Features

Memory Commands

Storage

Auction Algorithm

🛠️ Skill System

Skill Package Structure

Creating a Skill

Skill Commands

Install a Skill

List Installed Skills

View Skill Information

Uninstall a Skill

Using Skills in Conversation

📖 Usage Guide

TUI Keyboard Shortcuts

Memory System

Markdown Rendering Support

⌨️ Command Reference

⚙️ Configuration Files Explained

1. Main Configuration File: config.toml

2. System Prompts File: prompts.toml

🚀 Deployment Options

Docker Deployment

System Service Installation

🤔 Frequently Asked Questions (FAQ)

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. Main Configuration File: `config.toml`

2. System Prompts File: `prompts.toml`

Packages