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.
Quickstart
The fastest way to get started is using the install script:
curl -LsSf https://raw.githubusercontent.com/elroy-bot/elroy/main/scripts/install.sh | sh
Or install manually with UV:
# 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.
Basic Usage
Once installed, run elroy to open the interactive chat interface:
elroy
For source development with automatic restart on code changes, use:
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.
For a full reference of tools and their schemas, see: tools schema reference
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.
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:
# 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 Sonnetopus: Anthropic's Claude 4.5 Opushaiku: Anthropic's Claude 3.5 Haikuo1: OpenAI's o1 model
Claude Code Integration
Elroy provides skills for 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:
elroy install-skills
Or use the just command from the repository:
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:
elroy install-skills --uninstall
For detailed usage and examples, see 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
1 maintainer
Release files for elroy 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| elroy-0.5.0.tar.gz | 58.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| elroy-0.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 59.1 MB
Release files / elroy-0.5.0.tar.gz
| Download URL | elroy-0.5.0.tar.gz |
|---|---|
| Size | 58.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
02f8f7c9e8ec2b940259e63b04cb2650e4bc78534e776b70210848bf548f7351
|
|
BLAKE2b-256 checksum How to use checksums |
e57e3763214cafb5660ab0297a22d6a7497c803ab4405a5ede2bb46f766b85f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / elroy-0.5.0-py3-none-any.whl
| Download URL | elroy-0.5.0-py3-none-any.whl |
|---|---|
| Size | 219.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f5e1b790bf29e7172ad11c3f549b53f70dc0d227bb70c580e06ef52fa350a461
|
|
BLAKE2b-256 checksum How to use checksums |
ff7d43528c0b0fdc450af2f41df1a8d65a3b60d3f9ea307641b1b76e6a2aef2c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
