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

pip install -e .

Usage

Command Line Interface (CLI)

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

# 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

# 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

# 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

# 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

ghost-brain

As a Python Package

from ghost_brain import Brain

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

Deployment Options

Local Development

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

Remote Desktop (for mobile users)

# 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

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

Team Sharing

# Deploy to shared server
# All team members use same URL in their Obsidian settings

Development

# 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:

# 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

Quick Configuration Examples

Local Development

# 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)

# 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

# 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

brainServer: {
    useCustomBrainServer: boolean;
    brainServerUrl: string;
    brainServerPort: number;
}

Configuration Testing

Test your configuration:

# 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

# 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 for detailed guidelines on code style, testing, and submitting PRs.

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