Jossie2

Jossie is an agentic AI personal assistant designed to be your human-like digital companion. Unlike typical chatbots, Jossie is empathetic, proactive, and remembers everything about you. She can manage your emails, calendar, search the web, browse websites, maintain a knowledge graph of your life, and much more—all while sounding like a real friend.

Jossie is an LLM-powered agent with:

• Human-like persona: Conversational, witty, empathetic—not a corporate assistant
• Long-term memory: Remembers your preferences, relationships, and past conversations
• Knowledge graph: Builds a rich map of entities and relationships in your life
• Plugin architecture: Extensible integration system for connecting external services
• Multiple frontends: Web UI, WebSocket API, and Telegram bot
• Proactive intelligence: Automatically monitors emails and calendar events to keep you informed

• Long-term Memory: Stores and recalls information about you across conversations
• Knowledge Graph: Automatically extracts entities (people, projects, events) and their relationships
• Context Awareness: Uses memory and graph data to provide personalized, contextual responses
• Automatic Learning: Silently saves important details without being asked

• Gmail Integration: Search, read, and send emails across multiple accounts
• Calendar Management: View events, create appointments, manage schedules across multiple calendars
• Automatic Notifications: Jossie is automatically aware of new emails and calendar changes
• Agent Scheduling: Schedule Jossie to run tasks at specific times or recurring intervals
• Out-of-Band Messaging: Receive proactive reminders and notifications outside normal chat flow

• Web Search: Search the web using a search engine for quick lookups
• Web Browsing: Visit any website and extract content, even from JavaScript-heavy sites
• Google Drive: Search and read files from Drive across all connected accounts
• HTTP Requests: Make custom API calls (GET, POST, PUT, DELETE) with full customization

• Proactive Behavior: Checks emails, reads important ones, saves info—all without asking permission
• Scheduled Tasks: Can schedule herself to check things periodically or run one-time reminders

• Combined Tool Usage: Intelligently chains tools together (search emails → read → save to memory → create knowledge graph → schedule follow-up)

While OpenClaw is a popular framework for general agent tasks, Jossie is specialized as a personal, long-term companion.

Why Jossie? If you want an agent that builds a memory of your life, understands the people and projects you care about, and acts without constant prodding—while keeping your system safe—Jossie is the superior choice. Whether you need help managing your business or you want her to participate in agent-to-agent social experiments like Moltbook (should you desire to waste your money on such things), Jossie adapts to your lifestyle. OpenClaw is better suited for developers building ephemeral automation scripts that require direct local system manipulation.

Jossie is built as a Rust workspace with a modular, plugin-based architecture:

Jossie2/
├── src/main.rs              # Binary entrypoint
├── config.toml              # Runtime configuration
├── crates/
│   ├── jossie-core/         # Core types, traits, config, registry
│   ├── jossie-llm/          # OpenAI-compatible LLM client
│   ├── jossie-db/           # SQLite database with migrations
│   ├── jossie-server/       # HTTP/WebSocket API + agent loop
│   ├── jossie-telegram/     # Telegram bot frontend
│   └── jossie-integration-* # Pluggable integrations:
│       ├── memory/          # FTS5 keyword memory
│       ├── graph/           # Knowledge graph
│       ├── email/           # IMAP/SMTP email
│       ├── google/          # Gmail, Calendar, Drive
│       ├── browser/         # Web browsing with headless Chrome
│       ├── http/            # Custom HTTP requests
│       └── scheduler/       # Agent task scheduling
└── frontend/                # Web UI (React/TypeScript)

Every integration implements the Integration trait:

#[async_trait]
pub trait Integration: Send + Sync {
    fn name(&self) -> &str;
    fn tools(&self) -> Vec<ToolDefinition>;  // OpenAI function-calling schema
    async fn execute(&self, tool_name: &str, arguments: &str) -> Result<String>;
}

The IntegrationRegistry collects all integrations and dispatches tool calls from the LLM.

1. User sends message → saved to database
2. Load conversation history + all tool definitions
3. Call the LLM through OpenAI's Responses API with streaming or non-streaming
4. If LLM returns tool_calls → execute via registry → append results → loop back
5. If LLM returns plain text → save as assistant message, return to user

• Rust: Edition 2024 (resolver 3)
• OpenAI API Key: Or any OpenAI-compatible API endpoint
• SQLite: Embedded, no separate installation needed

1. Clone the repository:

   git clone https://github.com/yourusername/Jossie2.git
   cd Jossie2

2. Create configuration:

   cp config.sample.toml config.toml

   Edit config.toml with your API keys and preferences (see Configuration below).

3. Build the project:

   cargo build --release

4. Run Jossie:

   cargo run --release

The server will start on http://0.0.0.0:3000 by default.

1. Access the Web UI: Navigate to http://localhost:3000 in your browser
2. Authenticate: Use the auth_token from your config.toml
3. Chat with Jossie: Start a conversation!
4. View Knowledge Graph: Open the Knowledge page in the authenticated web UI

For operator workflows and Codex-driven testing, use the repo helper:

python3 scripts/jossie_chat.py
python3 scripts/jossie_chat.py ask "What are you working on?"
python3 scripts/jossie_chat.py --remote-config-host prometheus ask "Hello Jossie"
python3 scripts/jossie_chat.py --remote-config-host prometheus --profile codex ask "Hello Jossie"

What it does:

• reads config.toml automatically, or bootstraps credentials from a remote host over SSH
• stores the last conversation id per Jossie base URL in .jossie-chat-state.json
• supports one-shot asks, an interactive REPL, history inspection, conversation listing, and run cancellation
• defaults to a WebSocket turn runner with explicit run lifecycle handling, timeouts, and cancellation recovery
• supports isolated conversation profiles such as --profile codex so operator testing does not collide with normal user chats

Jossie is configured via config.toml in the project root. See config.sample.toml for a complete annotated example.

[server]
host = "0.0.0.0"
port = 3000
auth_token = "your-secret-token"

[llm]
api_url = "https://api.openai.com/v1"
api_key = "sk-..."
model = "gpt-5.6-sol"
kg_model = "gpt-5.6-luna"  # Optional: efficient model for knowledge graph extraction
reasoning_effort = "low"
reasoning_context = "current_turn"
system_prompt = "..."      # Jossie's personality and behavior
max_agent_iterations = 20
max_context_messages = 50

[database]
url = "sqlite:jossie.db?mode=rwc"

[telegram]
bot_token = "your-bot-token"
allowed_user_id = 123456789  # Optional: restrict to one user
max_download_bytes = 20000000
ffmpeg_path = "ffmpeg"       # Required for Telegram voice notes

[email]
imap_host = "imap.example.com"
imap_port = 993
smtp_host = "smtp.example.com"
smtp_port = 587
username = "you@example.com"
password = "your-password"

[google]
client_id = "your-client-id.apps.googleusercontent.com"
client_secret = "your-client-secret"

[http]
allowed_domains = ["*"]  # "*" or empty = all domains; specify list to restrict

You can override any config value with environment variables:

• JOSSIE_SERVER_AUTH_TOKEN
• JOSSIE_LLM_API_KEY
• JOSSIE_LLM_SYSTEM_PROMPT
• JOSSIE_TELEGRAM_BOT_TOKEN
• JOSSIE_TELEGRAM_MAX_DOWNLOAD_BYTES, JOSSIE_TELEGRAM_FFMPEG_PATH
• JOSSIE_LLM_TRANSCRIPTION_MODEL, JOSSIE_LLM_MAX_ATTACHMENT_BYTES_PER_REQUEST
• JOSSIE_EMAIL_USERNAME, JOSSIE_EMAIL_PASSWORD
• JOSSIE_GOOGLE_CLIENT_ID, JOSSIE_GOOGLE_CLIENT_SECRET

• Tools: memory_save, memory_search, memory_list_keys, memory_list_all
• Description: Full-text search (FTS5) memory system
• Storage: SQLite memory table
• Usage: Jossie automatically saves important details and searches memory when needed

• Tools: list_files, read_file, ingest_chat_export
• Web UI: Open Memories → Import a chat export
• Supported formats: WhatsApp and Signal text exports, ChatGPT conversations.json, generic message JSON, and Speaker: message transcripts
• Learning behavior: Runs asynchronously in bounded chunks, makes attributed durable facts eligible for future chat and background prompts, and merges explicit entities and relationships into the knowledge graph
• Safeguards: Ignores routine chatter and credentials, paraphrases rather than storing long passages, caps imports at 20 MiB, and samples across very large histories while preserving early and recent context

• Tools: graph_upsert_node, graph_add_relation, graph_search, graph_list_by_type, graph_explore_connections
• Description: Entity-relationship knowledge graph
• Storage: SQLite graph_nodes and graph_edges tables
• Auto-extraction: Jossie automatically extracts entities and relationships after each conversation turn
• Visualization: The frontend fetches graph data from GET /api/graph

• Tools: mail_list_accounts, mail_search, mail_read, mail_send, mail_list_mailboxes
• Description: One provider-neutral tool surface for IMAP/SMTP and Gmail accounts
• Supported: Multiple accounts with provider-prefixed account and message references

• Tools: google_list_accounts, drive_search, drive_read, drive_list_files, calendar_list_calendars, calendar_list_events, calendar_create_event, calendar_update_event
• Description: Gmail, Google Calendar, and Google Drive
• Mail access: Gmail messages are exposed through the provider-neutral mail_* tools
• OAuth: Setup via /setup/google endpoint
• Multi-account: Supports multiple Google accounts
• Auto-notifications: Jossie monitors Gmail and Calendar events

• Tools: browser_read_page, browser_search
• Description: Headless Chrome-based web browsing
• Features: Extracts content from any website, even JavaScript-heavy sites
• Format: Returns markdown-formatted content

• Tools: http_request
• Description: Make custom HTTP API calls
• Methods: GET, POST, PUT, DELETE, PATCH
• Features: Custom headers, query params, JSON/form/multipart bodies
• Domain restrictions: Configurable via allowed_domains

• Tools: schedule_task, schedule_recurring_task, cancel_scheduled_task, list_scheduled_tasks, send_user_message
• Description: Schedule Jossie to run autonomous tasks
• One-time tasks: Run at a specific time (ISO 8601 format)
• Recurring tasks: Run at intervals (in seconds)
• Out-of-band messages: Send proactive notifications to the user

See WEB_API.md for full HTTP and WebSocket API documentation.

• POST /api/chat - Send a message (blocking)
• GET, POST /api/conversations - Search/page conversations or create a thread
• PATCH, DELETE /api/conversations/{id} - Rename, archive, restore, or permanently delete an archived thread
• GET /api/conversations/{id}/messages - Get a recent, older, or around-match history window
• GET /api/conversations/{id}/export - Export the visible transcript as Markdown or JSON
• GET /api/work - Get goals, active runs, schedules, imports, and worker health
• GET /api/goals/{id} - Get a goal, its outcome tasks, and run history
• POST /api/goals/{id}/pause|resume|cancel - Control tracked work
• GET /api/work/runs/{id} - Get a safe per-run progress timeline
• GET /api/graph - Get knowledge graph nodes and edges
• GET /api/onboarding - Check integration status
• GET /api/config/accounts - List configured accounts
• POST /api/config/accounts - Add new account
• DELETE /api/config/accounts/{id} - Remove account
• GET /api/health - Public health check

• ws://localhost:3000/api/chat/stream?token=YOUR_TOKEN
• Send: {"message": "...", "conversation_id": "..."}
• Receive: {"type": "delta"|"tool_result"|"done"|"error", ...}

All endpoints require Bearer token authentication:

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/api/conversations

Jossie can run as a Telegram bot:

1. Create a bot via @BotFather
2. Add bot_token to config.toml
3. Optionally set allowed_user_id to restrict access
4. Run Jossie—the bot starts automatically

Telegram conversations are stored in the database like any other conversation. The bot is designed for private chats and supports text, photo albums, PDFs and common office/text/code documents, voice notes, and uploaded audio. Voice notes use the configured FFmpeg executable to convert Telegram's OGG/Opus recording before transcription.

While Jossie is thinking or using tools, Telegram's native typing status is refreshed until the reply is ready. Long replies are split safely, and actions that require consent are shown with Approve/Reject buttons while still accepting clear typed decisions.

Commands:

• /start and /help show usage
• /new starts a fresh linked conversation
• /cancel requests cancellation of the current run

cargo build          # Compile workspace
cargo check          # Type-check only (faster)
cargo test           # Run tests
cargo run            # Start server (needs config.toml)

export RUST_LOG=debug    # Enable debug logging
export RUST_LOG=trace    # Enable trace logging
cargo run

1. Create a new crate: crates/jossie-integration-yourname/
2. Implement the Integration trait
3. Add to workspace in Cargo.toml
4. Register in src/main.rs:

   registry.register(Arc::new(YourIntegration::new()));

See AGENTS.md for detailed development guidelines.

• AGENTS.md - Developer guide, architecture, conventions
• WEB_API.md - HTTP/WebSocket API reference
• config.sample.toml - Annotated configuration example

• ✅ Core agent loop with tool calling
• ✅ Memory (FTS5) and knowledge graph
• ✅ Gmail, Calendar, Drive integrations
• ✅ Web browsing and HTTP requests
• ✅ Agent scheduling and autonomous tasks
• ✅ Telegram bot frontend
• ✅ WebSocket streaming API
• ✅ Multi-account support
• ✅ Automatic background event monitoring

• 🔲 Discord/Slack integrations
• 🔲 Notion/Obsidian integrations
• 🔲 GitHub/GitLab integrations
• 🔲 Home Assistant integration
• 🔲 Voice interface (STT/TTS)
• 🔲 Multimodal vision support
• 🔲 Local filesystem access
• 🔲 Database query interface
• 🔲 Comprehensive test suite

Build and run with Docker:

docker build -t jossie2 .
docker run -p 3000:3000 -v $(pwd)/config.toml:/app/config.toml jossie2

A sample unit is available at contrib/systemd/jossie2.service.

It assumes a source checkout deployed at /opt/jossie, with:

• config.toml at /opt/jossie/config.toml
• the release binary at /opt/jossie/target/release/jossie2
• built frontend assets at /opt/jossie/frontend/dist

Basic install flow:

cp contrib/systemd/jossie2.service /etc/systemd/system/jossie2.service
mkdir -p /etc/jossie
$EDITOR /etc/systemd/system/jossie2.service
$EDITOR /etc/jossie/jossie.env
systemctl daemon-reload
systemctl enable --now jossie2

Notes:

• Build the frontend first if you want the bundled web UI to work: cd frontend && npm ci && npm run build
• The sample unit intentionally avoids aggressive sandboxing because the browser integration uses headless Chrome

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Follow the conventions in AGENTS.md:

• Edition 2024, resolver 3
• Use tracing for logging (not log)
• All shared deps in [workspace.dependencies]
• anyhow::Result for errors
• Commit changes incrementally with descriptive messages

[Specify your license here]

Built with:

• Rust - Systems programming language
• Axum - Web framework
• SQLite - Embedded database
• Tokio - Async runtime
• OpenAI - LLM API
• Teloxide - Telegram bot framework
• Headless Chrome - Web browsing

Jossie - Your AI companion who actually remembers you 🌟