dreamloop 0.1.0

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

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.

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/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 Release Install

After the v0.1.0 package is published, install it with:

pipx install dreamloop
dreamloop init
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.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