DreamLoop

English | 中文

"The repeating platform may reflect revisiting the same choice from different angles. Which real choice keeps bringing you back to the same concern?"

Your dreams have patterns. DreamLoop finds them locally.

• Runs fully local. Your data never leaves your machine.
• Free with Ollama. Optional DeepSeek/OpenAI or custom OpenAI-compatible endpoints.
• CLI-first, forkable, and built for Obsidian-minded knowledge workers.
• English and Chinese analysis is language-checked before saving; switching the UI preserves unsaved analyzed drafts without relabeling results.
• Full CJK fonts and responsive layouts are bundled locally with no remote font requests.
• PyPI and source checkout keep data in .dreamloop/; Docker uses a named volume by default.

pipx install dreamloop
dreamloop init
dreamloop demo
dreamloop web

git clone https://github.com/saime428/DreamLoop.git
cd DreamLoop
uv sync --extra dev
uv run dreamloop init
uv run dreamloop demo
uv run dreamloop web

What You Get

Private local journal

Dream entries, settings, secrets, generated images, and exports live under .dreamloop/. Nothing uploads by default.

AI interpretation

DreamLoop can use Ollama locally or an explicit cloud/custom OpenAI-compatible provider to produce structured analysis: emotions, symbols, themes, multiple interpretations, and reality-check questions. Output language is validated before analysis is stored.

Visual memory

Every saved dream can create a local visual-memory card without any image API. Real image generation is opt-in.

Quick Start

Five-minute PyPI demo

pipx install dreamloop
dreamloop init
dreamloop demo
dreamloop web

Open http://127.0.0.1:8765. The demo seeds local sample dreams, mock analyses, and visual memory cards. No cloud AI is required.

Docker demo

docker compose up

Open http://localhost:8765. Demo data is only added when the local store is empty. Docker Compose stores .dreamloop/ in the dreamloop-data named volume; switch the volume to ./.dreamloop:/app/.dreamloop if you want host-visible files.

To run the prebuilt release image instead of building from source:

docker run -p 127.0.0.1:8765:8765 -v dreamloop-data:/app/.dreamloop ghcr.io/saime428/dreamloop:latest

Keep the 127.0.0.1: prefix on -p: a plain -p 8765:8765 publishes the app to your whole local network. This image still enables token auth in that case (the access URL is in docker logs), but the bundled docker-compose.yml turns the token off — see Network exposure.

Markdown / Obsidian export

dreamloop export --format markdown

DreamLoop writes one Markdown file per dream plus an _index.md wikilink index under .dreamloop/exports/.

git clone https://github.com/saime428/DreamLoop.git
cd DreamLoop
uv sync --extra dev
uv run dreamloop init
uv run dreamloop add "I found a blue door under the sea."
uv run dreamloop web

ollama pull qwen3:8b
uv run dreamloop ai use ollama --model qwen3:8b
uv run dreamloop ai test
uv run dreamloop analyze --pending

uv run dreamloop ai status
uv run dreamloop ai use ollama --model qwen3:8b
uv run dreamloop ai use deepseek --model deepseek-v4-flash
uv run dreamloop ai use custom --model local-model --base-url http://localhost:1234/v1
uv run dreamloop image use local_card
uv run dreamloop image use cloud_openai_compatible --model image-model --base-url https://images.example/v1

dreamloop web --port 18080

Why This Project

Commercial dream apps often make you pay for analysis and push intimate text into a cloud workflow. DreamLoop takes the opposite path: the journal is local, the CLI is primary, and AI is a swappable layer.

The default path is zero-cost Ollama. DeepSeek, OpenAI, and custom OpenAI-compatible endpoints are optional for people who want stronger hosted models or their own local gateway.

Web App Loop

Dashboard -> Log -> Detail -> Patterns -> Gallery -> Settings.

• Dashboard: AI Insight, heatmap, stats, and recent dreams.
• Log: draft-first capture with optional reflection prompts; language switching preserves unsaved content and analyzed results.
• Detail: original dream text, truthful analysis-language labels, explicit regeneration, feedback, local cards, and opt-in images.
• Patterns: calendar, recurring symbols, themes, resonant feedback, and a symbol network.
• Gallery: real generated images when configured, otherwise local visual cards.
• Settings: AI provider, image provider, launch notes, data directory, and privacy status.

The same FastAPI app exposes JSON endpoints for dreams, feedback, images, heatmap, trends, and symbol graph data.

Privacy Promise

• Dream entries are stored in .dreamloop/dreamloop.sqlite3.
• .dreamloop/ is ignored by Git.
• Your dreams are never uploaded by default.
• Ollama keeps analysis local on your machine.
• DeepSeek/OpenAI/custom providers only run after explicit configuration.
• API keys live in .dreamloop/secrets.env; secrets do not belong in commits.

Network exposure

dreamloop web binds to 127.0.0.1 by default, so the app is only reachable from your own machine and needs no authentication. Keep the default loopback binding — the bundled docker-compose.yml already publishes only 127.0.0.1:8765 on the host — unless you fully trust the network. See SECURITY.md for the threat model.

Access token on non-loopback binds

Starting with a non-loopback host (for example dreamloop web --host 0.0.0.0) automatically enables token auth: the startup output prints an access URL ending in ?token=... — open that URL once and a browser cookie keeps you signed in. The token persists in .dreamloop/web_token; set DREAMLOOP_TOKEN to pin your own. In Docker, find the access URL with docker logs <container> (or docker compose logs dreamloop). --no-auth or DREAMLOOP_NO_AUTH=1 disables the token, which exposes your entire journal, unauthenticated, to anyone who can reach the address — the bundled compose file sets it only because its port stays on the host's loopback.

Local Data Model

.dreamloop/
  dreamloop.sqlite3
  config.json
  secrets.env
  assets/images/
  exports/
  imports/

.dreamloop/ is created relative to the current working directory. Run DreamLoop from one fixed directory: launching it somewhere else creates a new, empty journal there instead of opening your existing one.

Status

Available now

DreamLoop v0.2 adds:

• Docker demo with docker compose up.
• Markdown / Obsidian export via dreamloop export --format markdown.
• Symbol co-occurrence graph on Patterns for shareable screenshots.
• Chinese demo data via dreamloop demo --language zh.
• GHCR image publishing on GitHub releases.
• Stateless English/Chinese interface switching that preserves unsaved analyzed drafts.
• Analysis-language validation and explicit mismatch handling before persistence.
• Full offline Noto Sans SC and Noto Serif SC coverage with a fixed responsive type scale.

The source-based Docker demo builds locally today. Release images publish as ghcr.io/saime428/dreamloop when a GitHub release is published.

Current source verification: 157 automated tests pass. Browser QA covers all six pages in both languages across six desktop, tablet, and mobile viewports.

Next

• Obsidian vault sync.
• Obsidian community plugin.
• Lightweight local clustering without a required vector database.
• Backup and restore flows.

Contributing

DreamLoop is deliberately small and forkable. See CONTRIBUTING.md.

Run tests with:

uv run --extra dev pytest

Build the package with:

uv build

License

MIT