dreamloop 0.1.1

A local-first AI dream journal for people who want to notice patterns in their dreams.

DreamLoop

English | 中文

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.
• Detailed dream analysis that favors emotions, real-life context, and multiple verifiable interpretations.

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

DreamLoop is a local-first dream journal for people who want fast capture, private storage, and pattern discovery without renting their inner life to another subscription app. The web app follows a six-page loop: Dashboard -> Log -> Detail -> Patterns -> Gallery -> Settings.

Quick Start

Five-minute PyPI demo

pipx install dreamloop
dreamloop init
dreamloop demo
dreamloop web

Expected result:

DreamLoop seeds three local sample dreams, mock analyses, and visual memory cards.
The dashboard opens at http://127.0.0.1:8765 with Dashboard, Patterns, and Gallery populated.
No cloud AI is required for this demo.

Run locally without AI

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

Expected result:

DreamLoop stores the entry in .dreamloop/dreamloop.sqlite3.
The local dashboard starts at http://127.0.0.1:8765.
AI analysis stays pending until you configure a provider.

You can also run uv run dreamloop doctor to check the data directory, SQLite, provider settings, Ollama connectivity, and hidden key status without printing secrets.

Enable local Ollama analysis

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

Expected result:

Ollama is used through http://localhost:11434/v1.
DreamLoop writes structured analysis back to local SQLite.

Why This Project

Commercial dream apps usually make you pay for analysis and push personal text into a cloud workflow. DreamLoop takes the opposite path: the journal is local, the CLI is the primary interface, 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. The code is small enough to fork and direct enough to extend.

Demo Assets

• Real dashboard screenshot: docs/assets/dashboard-screenshot.png
• Social preview image: docs/assets/social-preview.png
• Reproducible recording guide: docs/demo-recording.md

The recording guide covers CLI capture, the Dashboard -> Log -> Detail flow, Patterns filtering, Gallery, and Settings without exposing secrets.

CLI Demo

$ uv run dreamloop add "A door opened under the sea."
saved locally -> .dreamloop/dreamloop.sqlite3
analysis -> pending

$ uv run dreamloop ai use ollama --model qwen3:8b
AI provider set to ollama (qwen3:8b).

$ uv run dreamloop analyze --pending
Analyzed pending dreams when a provider is ready.

Privacy Promise

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

AI Providers

DreamLoop supports provider configuration without changing the journal model:

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 ai test

Provider defaults:

• ollama: local, http://localhost:11434/v1, model qwen3:8b
• deepseek: cloud, https://api.deepseek.com, model deepseek-v4-flash
• openai: cloud, OpenAI-compatible JSON analysis
• custom: any OpenAI-compatible /v1 endpoint, including local gateways
• none: capture-only local journal mode

Web App Loop

The FastAPI/Jinja dashboard is intentionally lightweight:

• Dashboard: README-ready overview with AI Insight, heatmap, stats, and recent dreams
• Log: draft-first dream capture, optional reflection prompts, and AI analysis before saving
• Detail: original dream text, detailed interpretation, reality-grounded questions, raw JSON, and an opt-in visual-memory entry point
• Patterns: clickable calendar, recurring symbols, theme trends, and filters back into Log
• Gallery: v0.1 local visual cards derived from saved dreams; image generation remains opt-in
• Settings: provider selection, launch notes, local data directory, and privacy status

DreamLoop is currently launched with uv run dreamloop web from a checkout or dreamloop web after package install. A native desktop app is a later packaging task; v0.1 stays lightweight so the local-first core remains easy to inspect and fork.

The same app exposes JSON endpoints:

• POST /api/dreams
• GET /api/dreams
• GET /api/dreams/{id}
• GET /api/dreams/{id}/similar
• POST /api/analyze/pending
• POST /api/dreams/{id}/feedback
• GET /api/feedback/summary
• POST /api/import/ics
• POST /api/weather/sync
• GET /api/insights/heatmap
• GET /api/insights/trends

Local Data Model

.dreamloop/
  dreamloop.sqlite3
  config.json
  secrets.env
  chroma/
  exports/
  imports/

SQLite stores dreams, analysis results, imported calendar events, and synced weather. ChromaDB remains optional for richer vector search.

PyPI Install

Install the published package with:

pipx install dreamloop
dreamloop init
dreamloop doctor
dreamloop demo
dreamloop add "I was flying above a dark ocean."
dreamloop web

Obsidian Roadmap

• v0.2: Markdown export for dream entries and analysis summaries.
• v0.3: Obsidian vault sync with stable frontmatter.
• v0.4: Community plugin for capture, backlinks, and local dashboard launch.

Roadmap

v0.1

• Local CLI and six-page Web loop.
• SQLite storage.
• Ollama-first provider settings.
• Optional DeepSeek/OpenAI/custom structured analysis.
• Optional reflection prompts and longer reality-grounded interpretation reports.
• Heatmap, .ics import, weather sync.
• Similar dreams and basic trends.
• Real screenshot assets, CI, changelog, and public release packaging.

v0.1.1

• Dashboard hero overflow fix for English and Chinese layouts.
• dreamloop doctor for local setup checks without revealing secrets.
• dreamloop demo for a fast no-AI walkthrough with sample dreams and local visual cards.
• Local feedback buttons on interpretations: resonates, not accurate, unsure.
• Patterns summary for high-resonance themes.

v0.2

• Markdown export.
• CLI GIF/cast release assets.
• ChromaDB-backed clustering and recurring-theme insights.
• Backup and restore flows.

v0.3+

• Obsidian vault sync.
• Obsidian community plugin.
• Generated dream illustrations stored locally as opt-in artifacts.

Contributing

DreamLoop is deliberately small and forkable. Good first contributions:

• improve local model prompts
• add .ics fixtures
• polish dashboard accessibility
• expand Markdown/Obsidian export
• add terminal demo assets

Run tests with:

uv run --extra dev pytest

Build the package with:

uv build

License

MIT