Metadata-Version: 2.4
Name: elroy
Version: 0.5.0
Author-email: Elroy Bot <bot@elroy.ai>
License-File: LICENSE
Requires-Python: <3.13,>=3.12
Requires-Dist: alembic==1.14.1
Requires-Dist: apscheduler==3.11.0
Requires-Dist: chromadb==1.4.1
Requires-Dist: docstring-parser==0.16
Requires-Dist: importlib-resources==6.5.2
Requires-Dist: litellm==1.75.5.post1
Requires-Dist: lock==2018.3.25.2110
Requires-Dist: pygments==2.19.2
Requires-Dist: pytz==2024.2
Requires-Dist: pyyaml==6.0.2
Requires-Dist: requests==2.32.3
Requires-Dist: rich==14.3.3
Requires-Dist: scikit-learn==1.6.1
Requires-Dist: semantic-version==2.10.0
Requires-Dist: sqlalchemy==2.0.37
Requires-Dist: sqlmodel==0.0.22
Requires-Dist: textual==8.0.2
Requires-Dist: tiktoken==0.9.0
Requires-Dist: toolz==1.0.0
Provides-Extra: dev
Requires-Dist: bumpversion==0.6.0; extra == 'dev'
Requires-Dist: discord-py==2.4.0; extra == 'dev'
Requires-Dist: fawltydeps==0.18.0; extra == 'dev'
Requires-Dist: langchain-core==0.3.31; extra == 'dev'
Requires-Dist: lorem-text==2.1; extra == 'dev'
Requires-Dist: pydantic==2.11.4; extra == 'dev'
Requires-Dist: pytest-cov==6.0.0; extra == 'dev'
Requires-Dist: pytest-mock==3.14.0; extra == 'dev'
Requires-Dist: pytest-rerunfailures==15.0; extra == 'dev'
Requires-Dist: pytest==8.3.4; extra == 'dev'
Requires-Dist: ruff==0.15.0; extra == 'dev'
Requires-Dist: testcontainers==4.9.1; extra == 'dev'
Requires-Dist: ty==0.0.16; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-blog-plugin==0.25; extra == 'docs'
Requires-Dist: mkdocs-git-revision-date-localized-plugin==1.3.0; extra == 'docs'
Requires-Dist: mkdocs-macros-plugin==1.3.9; extra == 'docs'
Requires-Dist: mkdocs-material==9.1.20; extra == 'docs'
Requires-Dist: mkdocs-rss-plugin==1.2.0; extra == 'docs'
Requires-Dist: mkdocs==1.4.3; extra == 'docs'
Description-Content-Type: text/markdown

# Elroy

[![Discord](https://img.shields.io/discord/1200684659277832293?color=7289DA&label=Discord&logo=discord&logoColor=white)](https://discord.gg/5PJUY4eMce)
[![Documentation](https://img.shields.io/badge/docs-elroy.bot-C8C7E8)](https://elroy.bot)
[![PyPI](https://img.shields.io/pypi/v/elroy)](https://pypi.org/project/elroy/)

Elroy is a scriptable, memory augmented AI personal assistant, accessible from the command line. It features:

- **Long-term Memory**: Automatic memory recall of past conversations
- **Reminders** Track context based and timing based reminders
- **Simple scripting interface**: Script Elroy with minimal configuration overhead
- **CLI Tool interface**: Quickly review memories Elroy creates for you, or jot quick notes for Elroy to remember.

![Reminder demo](./docs/images/reminders_demo.gif)


## Quickstart

The fastest way to get started is using the install script:

```bash
curl -LsSf https://raw.githubusercontent.com/elroy-bot/elroy/main/scripts/install.sh | sh
```

Or install manually with UV:

```bash
# Install UV first
curl -LsSf https://astral.sh/uv/install.sh | sh

# Then install Elroy
uv pip install elroy
```

For detailed installation instructions including Docker and source installation options, see the [Installation Guide](docs/installation.md).

## Basic Usage

Once installed, run `elroy` to open the interactive chat interface:

```bash
elroy
```

For source development with automatic restart on code changes, use:

```bash
just dev
```

This requires `watchexec` and runs Elroy from the local source tree with restart-on-change behavior for `.py`, `.yml`, and `.yaml` files.
It uses the `elroy` console entrypoint rather than `python -m elroy.ui.app`, which avoids `runpy` module re-execution warnings from the package import layout.

Elroy opens a terminal UI where you can chat, create memories, and manage reminders. Use the Textual command palette with `Ctrl+P` to discover available actions.

## Memory and Reminder Tools

Elroy's tools allow it to create and manage memories and reminders. In the background, redundant memories are consolidated.

As reminders or memories become relevant to the conversation, they are recalled into context. A `Relevant Context` panel makes all information being surfaced to the assistant available to the user.

All commands available to the assistant are also available to the user through the Textual command palette.

For a guide of what tools are available and what they do, see: [tools guide](docs/tools_guide.md).

For a full reference of tools and their schemas, see: [tools schema reference](docs/tools_schema.md)


### Configuration
Elroy is designed to be highly customizable, including appearance and memory consolidation parameters.

Configuration can be provided via environment variables (e.g. `ELROY_CHAT_MODEL=gpt-5`) or a config file at `~/.elroy/elroy.conf.yaml`.

For full configuration options, see [configuration documentation](docs/configuration/index.md).


### Supported Models

Elroy supports OpenAI, Anthropic, Google (Gemini), and any OpenAI-compatible API.

The model is selected automatically based on which API key is set, or can be configured explicitly:

```bash
# Use an Anthropic model
ELROY_CHAT_MODEL=claude-sonnet-4-5-20250929 elroy

# Use a specific OpenAI model
ELROY_CHAT_MODEL=gpt-5 elroy

# Use Gemini
ELROY_CHAT_MODEL=gemini/gemini-2.0-flash elroy
```

Common model aliases can be used as the `chat_model` config value:
- `sonnet`: Anthropic's Claude 4.5 Sonnet
- `opus`: Anthropic's Claude 4.5 Opus
- `haiku`: Anthropic's Claude 3.5 Haiku
- `o1`: OpenAI's o1 model

## Claude Code Integration

Elroy provides skills for [Claude Code](https://github.com/anthropics/claude-code) that expose memory management as slash commands:

- `/remember` - Create a long-term memory
- `/recall` - Search through memories
- `/list-memories` - List all memories
- `/remind` - Create a reminder
- `/list-reminders` - List active reminders
- `/ingest` - Ingest documents into memory

### Installation

Install the Claude Code skills using the Elroy CLI:

```bash
elroy install-skills
```

Or use the just command from the repository:

```bash
just install-claude-skills
```

This installs skills to `~/.claude/skills/` making them available in all Claude Code sessions.

**Important**: Restart your Claude Code session after installation to load the new skills.

To uninstall:

```bash
elroy install-skills --uninstall
```

For detailed usage and examples, see [claude-skills/README.md](claude-skills/README.md).

## Branches

`main` comes with backwards compatibility and automatic database migrations.

`stable` is sync'd with the latest release branch.

`experimental` is a test branch with upcoming changes. These may contain breaking changes and/or changes that do not come with automatic database migrations.

## License

Distributed under the Apache 2.0 license. See LICENSE for more information.

## Contact

Bug reports and feature requests are welcome via [GitHub](https://github.com/elroy-bot/elroy/issues)

Get in touch on [Discord](https://discord.gg/5PJUY4eMce) or via [email](hello@elroy.bot)
