Allow configuring the physical storage location for .exxperts configuration and memory data
- Dominant language
- TypeScript
- Stars
- 354
- Forks
- 40
- PR merge metrics
- No merged PRs in 30d
Description
# Configurable Storage Location for `.exxperts` Data
## Summary
Allow users to configure the physical storage location for `.exxperts` configuration and memory data.
## Context
`.exxperts` currently stores persistent configuration and state data, such as rooms, memories, and related metadata.
While the current default location is convenient for local usage, the physical storage location should not be fixed. Users and operators should be able to decide where `.exxperts` data resides, particularly for containerized deployments, persistent volumes, backups, migrations, shared or managed storage, and environments with specific security or governance requirements.
An additional important use case is sharing the same `.exxperts` configuration between multiple computers. For example, a user may want to place the data directory in a cloud-synchronized folder—such as OneDrive, iCloud Drive, Dropbox, Nextcloud, or a managed enterprise cloud drive—so that rooms, memories, and configuration are available on a desktop workstation, laptop, or other development machine without manual export/import steps.
## Goal
Provide a supported and documented way to configure the root directory in which `.exxperts` persists its data.
The existing `.exxperts` location should remain the default to preserve backwards compatibility.
## Requirements
- Introduce a central configuration option for the `.exxperts` data directory, for example via:
- Environment variable, e.g. `EXXPERTS_DATA_DIR`
- Application configuration file / settings
- Optionally, a CLI argument
- The configured directory must be used as the root location for persistent `.exxperts` data, including:
- Room definitions and room-related configuration
- Memories
- Persistent metadata, settings, indexes, and other stateful artifacts as applicable
- If no custom path is configured, `.exxperts` must continue to use the existing `.exxperts` directory as the default location.
- The application should create the configured directory automatically if it does not exist and the process has the required permissions.
- Invalid, inaccessible, or non-writable paths must result in clear and actionable error messages.
- The configuration should work consistently for local execution and Docker/container-based deployments.
- Relative-path behavior should be clearly defined and documented. Absolute paths should be recommended for production and container deployments.
- The documentation should explicitly include a cloud-synced-directory use case for sharing one configuration across multiple devices.
## Example
Local execution using a cloud-synchronized directory:
```bash
export EXXPERTS_DATA_DIR="$HOME/Library/CloudStorage/OneDrive-Company/exxperts"
```
Docker Compose:
```yaml
services:
exxperts:
image: ghcr.io/exxeta/exxperts:latest
environment:
EXXPERTS_DATA_DIR: /data/exxperts
volumes:
- ./exxperts-data:/data/exxperts
```
## Acceptance Criteria
- [ ] A documented configuration mechanism exists to set the `.exxperts` persistent-data root directory.
- [ ] Rooms, memories, and other relevant persistent artifacts are stored below the configured root directory.
- [ ] When no custom path is configured, the application continues to use the existing `.exxperts` directory.
- [ ] The configured directory is created automatically when possible.
- [ ] The application fails with useful error messages when the configured directory is invalid or not writable.
- [ ] The behavior is covered by automated tests for:
- Default `.exxperts` behavior
- A custom configured path
- Directory creation
- Invalid or non-writable locations
- [ ] Documentation includes examples for local usage, Docker/container deployments, and cloud-synchronized directories.
- [ ] Existing installations remain compatible without configuration changes.
## Motivation
Making the `.exxperts` storage location configurable improves:
- **Cross-device configuration sharing:** Users can store `.exxperts` data in a cloud-synchronized directory and use the same rooms, memories, and settings across a desktop computer, laptop, or other devices.
- **Portability:** Persistent data can be kept independently of the application installation or working directory.
- **Container persistence:** Rooms and memories can be reliably retained through explicitly mounted Docker volumes.
- **Backup and migration:** Operators can back up, restore, or move a single well-defined data directory.
- **Operational governance:** Storage can follow company policies for permissions, encryption, retention, tenant separation, or managed storage.
- **Testing and development:** Isolated temporary data directories can be used for automated tests and local experiments.
Contributor guide
Research direction
Start by locating where the application currently resolves and writes the `.exxperts` directory, then trace persistence for rooms, memories, metadata, and settings. Run the existing test suite before adding coverage for the default path, a custom path, directory creation, and invalid or unwritable locations. Done means local and Docker usage work with documented examples, including a cloud-synchronized directory.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, docker-compose, typescript
- Domain
- backend, devops, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100