Memoria
Menu

Get started with Memoria

Clone the repository, add a DashScope API key, start the stack with Docker Compose, then open the dashboard.

Prerequisites

  • Git.
  • A DashScope (Qwen Cloud) API key.
  • For Docker Compose: Docker with the Compose plugin. Node 18 or newer for the dashboard.
  • Without Docker: Python 3.12, Node 18+, PostgreSQL 16 with the pgvector extension, and Redis.

1. Clone and configure

shell
git clone https://github.com/imawais-engineer/Memoria.git
cd Memoria
cp .env.example .env

Open .env and set DASHSCOPE_API_KEY. If your key is for the international DashScope endpoint, also set DASHSCOPE_BASE_URL. Never commit .env. See .env.example for every variable. Example shape, with placeholders only:

.env
DASHSCOPE_API_KEY=your_dashscope_api_key
# Only for international-region keys:
DASHSCOPE_BASE_URL=https://dashscope-intl.aliyuncs.com/api/v1
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/memoria
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=your_random_secret_key

2. Run with Docker Compose

This starts the backend, PostgreSQL with pgvector, Redis and the Celery workers.

shell
docker compose up --build -d
docker compose exec backend alembic upgrade head   # apply DB migrations
# backend now on http://localhost:8000  (health: /health, docs: /docs)

Never run docker compose down -v.

PostgreSQL data lives in the pgdata Docker volume and Redis chat history in redisdata. The -v flag deletes volumes, which erases all memories, chats and media. To update and keep your data, run:

shell
docker compose down && docker compose up -d --build
docker compose exec backend alembic upgrade head

3. Start the dashboard

shell
cd frontend && npm install && npm run dev   # http://localhost:5173

Open http://localhost:5173. You see the landing page at /. Click Get Started to open /auth, then sign up or log in with a username and favorite book.

Run without Docker

shell
# Backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload           # http://localhost:8000

# Background workers (separate shells, from backend/)
celery -A celery_app worker --loglevel=info
celery -A celery_app beat   --loglevel=info

# Frontend (separate shell)
cd frontend && npm install && npm run dev   # http://localhost:5173

First-run walkthrough

  1. Sign up on /auth. You land on /app with a blank chat.
  2. Tell the assistant a few facts about yourself, such as a food you avoid or a goal.
  3. Open New Chat and ask for a recommendation. It can recall your facts from the earlier chat.
  4. Open Memories to see what was stored.
  5. Type / in chat for the command table. Try /memorize, /list_memory or /imagine.
  6. Turn on the Memoryless toggle on an empty chat to try a private session.

The backend health check is at http://localhost:8000/health, and API docs at http://localhost:8000/docs.

Stuck? See the troubleshooting notes. Source and issues: GitHub.