ghost-brain 0.1.3
Advanced memory management and RAG capabilities for AI assistants with CLI and environment variable configuration
Requires Python: >=3.11
Keywords: ai assistant memory rag embeddings llm cli environment-variables

# Ghost Brain

The intelligent AI brain component for the Ghost project, providing memory management, RAG capabilities, and LLM integration.

## Features

- **Memory Management**: SQLite-based conversation history with embeddings
- **RAG System**: Semantic search with citations using `txtai`
- **LLM Integration**: Support for OpenAI and Google Gemini models
- **HTTP API**: RESTful interface for plugin communication
- **Intelligent Chunking**: Automatic conversation segmentation and summarization
- **Flexible Deployment**: Run locally, on remote desktops, or in the cloud
- **Mobile Support**: Connect mobile Obsidian to desktop brain servers

## Installation

```bash
pip install -e .
```

## Usage

### Command Line Interface (CLI)

Ghost Brain provides a comprehensive CLI for easy configuration and server management:

```bash
# Start server with default settings
ghost-brain server

# Start server on custom port
ghost-brain server --port 9000

# Start server with debug logging
ghost-brain server --host 0.0.0.0 --port 8000 --log-level debug

# Start server with custom database and backend
ghost-brain server --db-path ./data/memory.db --memory-backend txtai

# Show current configuration
ghost-brain config

# Show configuration in JSON format
ghost-brain config --format json

# Show environment variables documentation
ghost-brain env-docs

# Show version information
ghost-brain version
```

### CLI Commands

| Command | Description | Options |
|---------|-------------|---------|
| `server` | Start the brain server | `--host`, `--port`, `--log-level`, `--reload`, `--db-path`, `--memory-backend`, etc. |
| `config` | Show current configuration | `--format {text,json,env}` |
| `env-docs` | Show environment variables documentation | None |
| `version` | Show version information | None |

### CLI Examples

#### Development
```bash
# Start with auto-reload for development
ghost-brain server --reload --log-level debug

# Use custom database path
ghost-brain server --db-path ./dev/memory.db

# Override multiple settings
ghost-brain server --port 9000 --memory-backend txtai --temperature 0.5
```

#### Production
```bash
# Start on all interfaces
ghost-brain server --host 0.0.0.0 --port 8000

# Use production settings
ghost-brain server --log-level info --memory-backend txtai
```

#### Configuration Management
```bash
# Check current configuration
ghost-brain config

# Export configuration as environment variables
ghost-brain config --format env > .env

# Get configuration in JSON for automation
ghost-brain config --format json
```

### As a Service
```bash
ghost-brain
```

### As a Python Package
```python
from ghost_brain import Brain

brain = Brain()
response = await brain.process_message("Hello, how are you?")
```

### Deployment Options

#### Local Development
```bash
# Start brain server locally
python -m ghost_brain.server
# Default: http://localhost:8000
```

#### Remote Desktop (for mobile users)
```bash
# Install on desktop
python -m pip install ghost-brain

# Start brain server
python -m ghost_brain.server

# Find desktop IP
ifconfig  # Mac/Linux
ipconfig  # Windows

# Mobile users connect to: http://YOUR_DESKTOP_IP:8000
```

#### Cloud Deployment
```bash
# Deploy to Railway, Heroku, etc.
# Users connect to: https://your-deployment-url.com
```

#### Team Sharing
```bash
# Deploy to shared server
# All team members use same URL in their Obsidian settings
```

## Development

```bash
# Create the dev environment
pip install -r requirements.txt

# Install in editable mode
pip install -e .

# Run tests
pytest

# Start development server
uvicorn ghost_brain.server:app --reload
```

## API Endpoints

- `POST /chat` - Process a chat message
- `GET /health` - Health check
- `POST /memory/search` - Search memory
- `GET /memory/stats` - Get memory statistics
- `GET /settings` - Get current settings
- `POST /settings` - Update settings

## Configuration

Ghost Brain can be configured entirely through environment variables, making it perfect for cloud deployments, Docker containers, and team sharing.

### Environment Variables (Recommended)

The brain server supports comprehensive configuration via environment variables:

```bash
# API Keys
OPENAI_API_KEY=sk-your-openai-key
GEMINI_API_KEY=your-gemini-key

# Server Configuration
BRAIN_SERVER_PORT=8000
BRAIN_SERVER_HOST=0.0.0.0

# Memory Configuration
BRAIN_DB_PATH=./data/memory.db
BRAIN_MEMORY_BACKEND=txtai

# General Settings
BRAIN_LOG_LEVEL=info
BRAIN_SYSTEM_PROMPT="You are a helpful AI assistant."
```

**📖 [Complete Environment Variables Documentation](ENVIRONMENT_VARIABLES.md)**

### Quick Configuration Examples

#### Local Development
```bash
# Start with custom port
BRAIN_SERVER_PORT=9000 python -m ghost_brain.server

# Start with debug logging
BRAIN_LOG_LEVEL=debug python -m ghost_brain.server
```

#### Cloud Deployment (Railway)
```bash
# Set in Railway environment variables
OPENAI_API_KEY=sk-your-key
BRAIN_SERVER_HOST=0.0.0.0
BRAIN_SERVER_PORT=8000
BRAIN_DB_PATH=/app/data/memory.db
```

#### Team Sharing
```bash
# Shared server configuration
BRAIN_SERVER_HOST=0.0.0.0
BRAIN_SERVER_PORT=8000
BRAIN_DB_PATH=/shared/memory.db
BRAIN_MEMORY_BACKEND=txtai
```

### Brain Server Settings (Obsidian Plugin)
The Obsidian plugin supports configurable brain server connections:

- **Local Mode**: Default localhost:8000 configuration
- **Custom Mode**: Connect to any brain server URL
- **Port Configuration**: Customize local brain server port
- **Status Monitoring**: Real-time connection health checks

### Settings Interface
```typescript
brainServer: {
    useCustomBrainServer: boolean;
    brainServerUrl: string;
    brainServerPort: number;
}
```

### Configuration Testing

Test your configuration:
```bash
# Run configuration test
python test_environment_config.py

# Check configuration via API
curl http://localhost:8000/config/environment-variables
```

## Architecture

The brain consists of several core modules:

- **Memory Manager**: Handles conversation storage and retrieval
- **LLM Handler**: Manages API calls to language models
- **RAG Engine**: Provides semantic search capabilities
- **HTTP Server**: Exposes functionality via REST API
- **Settings Manager**: Handles configuration and deployment options

## Use Cases

### Desktop Users
- Default localhost:8000 configuration
- No changes needed
- Brain server runs on same machine

### Mobile Users
- Install brain on desktop
- Use desktop IP address in mobile settings
- No Python installation needed on mobile

### Cloud/Team Users
- Deploy brain to cloud service
- Share one brain server across team members
- Centralized memory and processing

## Testing

```bash
# Test brain server connectivity
python test_brain_server.py

# Test Obsidian integration
python test_obsidian_integration.py

# Test settings integration
python test_settings_integration.py
```

## Contributing

We welcome contributions to Ghost Brain!

### Adding New Chat Archive Importers
If you want to add support for importing chat archives from other AI providers (Claude, Gemini, Bing, etc.), please:
- Open an issue or discussion with a sample export file and format description.
- Submit a pull request with a new parser or endpoint for the provider's format.
- See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on code style, testing, and submitting PRs.

We encourage community contributions to expand Ghost Brain's compatibility with more chat platforms!