`DREAM`

Persistent project memory for Claude Code sessions.

Dreaming allows animals to consolidate memory and wake up sharper. Claude does the opposite — it hallucinates, loses context, and forgets everything between sessions. That's why I built Dream.

What it does

Dream scans your repository and generates a structured CLAUDE.md memory file that loads into every Claude Code session automatically via MCP. Claude instantly understands your stack, architecture, conventions, and current task — without you explaining anything.

It learns your preferences over time. Every correction you give Claude, every pattern you reinforce — Dream records it, weights it by frequency, and injects it as permanent instructions for all future sessions.

When the hallucinations begin, type /dream. Claude saves everything, you open a fresh session, and it picks up exactly where you left off — just like sleeping.

Install

npm install -g dream-mcp

Requires: Node.js 18+

Quick start

cd your-project
dream init

Run dream init once per project. It scans your repo, generates CLAUDE.md, and configures the MCP server. The /dream slash command is installed globally — it works in every Claude Code session automatically from that point on, no setup needed per project.

At the end of every session, type /dream in Claude Code. Claude saves everything, you open a fresh session, and it picks up exactly where you left off.

The session loop

dream init          → memory generated, /dream command installed
↓
work in Claude Code → Claude reads CLAUDE.md automatically
↓
type /dream         → Claude saves everything: task, changes, preferences, issues
↓
new session         → Claude reads updated CLAUDE.md, already knows where you left off
↓
repeat

Commands

Core

dream init              # Initialize Dream in this repository
dream scan              # Full rescan — regenerate CLAUDE.md from scratch
dream update            # Incremental update from recent git commits
dream status            # Show memory state, token count, MCP config
dream load              # Print memory to terminal (supports piping)
dream watch             # Background file watcher — auto-updates on change
dream doctor            # Validate full setup, diagnose issues
dream install-command   # Install the /dream slash command into Claude Code

Preferences

dream preferences list                        # Show all learned preferences
dream preferences set <key> <value> [cat]     # Set a preference manually
dream preferences remove <key>                # Remove a preference
dream preferences learn                       # Auto-detect from codebase + git
dream preferences export                      # Export to .dream/PREFERENCES.md
dream preferences clear                       # Clear all preferences

Obsidian

dream obsidian connect [vault-path]   # Connect your Obsidian vault
dream obsidian sync                   # Manual sync to vault
dream obsidian status                 # Show integration status
dream obsidian disconnect             # Disconnect vault

How memory works

dream init generates a CLAUDE.md in your project root:

# PROJECT
Name: my-app
Purpose: SaaS dashboard for analytics teams
Stage: development

# STACK
Language: TypeScript
Frontend: Next.js (App Router)
Database: PostgreSQL (Prisma)
Auth: Clerk
Styling: Tailwind CSS
Testing: Vitest

# ARCHITECTURE
- Full-stack monorepo
- Prisma ORM
- Service-layer backend structure
- tRPC API layer

# CONVENTIONS
- Named exports only
- Strict TypeScript mode
- @/ path aliases throughout
- Prettier formatting

# CURRENT TASK
Implement streaming AI responses

# OPEN ISSUES
- WebSocket reconnect instability on mobile

# RECENT CHANGES
2026-05-14
- Migrated auth to Clerk
- Added Prisma schema
- Refactored sidebar component

# HOW CLAUDE SHOULD OPERATE
- Preserve existing architecture patterns
- Use Prisma for all database operations
- Prefer Server Components — Client Components only when required
- Maintain strict typing

Token target: ≤ 1,500 tokens. Dream trims automatically by priority if you exceed the budget.

Preference learning

Dream learns how you work. There are two ways preferences accumulate:

Auto-detection — on dream init and dream preferences learn, Dream analyses your codebase:

Export style (named vs default)
Comment density
TypeScript strictness
Commit message style from git history
Formatting tools (Prettier, ESLint)

Claude reports them — the most powerful mechanism. When you correct Claude mid-session ("stop adding comments", "keep it shorter", "use named exports"), Claude calls dream_observe_preference and it's permanently recorded. Every future session inherits it.

Conflicts are resolved by frequency weighting: if a preference is observed 5× and a conflicting one 2×, the former wins. The count is always visible.

Preferences are injected directly into CLAUDE.md as hardcoded instructions:

# CLAUDE PREFERENCES
_Auto-learned from 12 observations. Last updated: 2026-05-14_

## Response Style
- Keep responses concise — under 3 sentences unless asked for detail
- No emoji unless explicitly requested

## Code Style
- Named exports only, never default exports (high)
- No comments unless the WHY is genuinely non-obvious (high)
- Strict TypeScript — never introduce any (high)

## Workflow
- Run typecheck before declaring done (medium)
- Follow existing patterns before introducing new abstractions (medium)

Obsidian integration

Connect your vault and Dream automatically keeps a structured note in sync:

dream obsidian connect
# → scans iCloud, ~/Documents, ~/Desktop for Obsidian vaults
# → lets you confirm, runs initial sync

The generated note includes frontmatter compatible with Dataview, your full stack as a table, current task as a callout, open issues as checkboxes, and a recent changes timeline. It updates automatically on every dream scan or dream update.

MCP integration

dream init automatically configures everything. Here's what happens and how to verify it's working:

1. Install Dream globally

npm install -g dream-mcp

2. Initialize in your project

cd your-project
dream init

This writes a .mcp.json to your project root:

{
  "mcpServers": {
    "dream": {
      "type": "stdio",
      "command": "dream",
      "args": ["mcp"]
    }
  }
}

3. Open the project in Claude Code

Open the project folder in Claude Code (desktop app or VS Code extension). Claude Code detects .mcp.json on startup and connects to the Dream MCP server automatically. You'll see dream listed under active MCP servers.

4. Verify it's connected

dream doctor

All checks should pass. Claude now has full access to your project memory.

5. Use /dream at the end of every session

Type /dream in the Claude Code chat panel. Claude saves your task, logs changes, records preferences, and flags issues — all written to CLAUDE.md. Open a new session and Claude picks up exactly where you left off.

MCP tools available to Claude:

Tool	Purpose
`dream_get_context`	Return full project memory
`dream_update_task`	Update current task
`dream_add_issue`	Add an open issue
`dream_resolve_issue`	Remove a resolved issue
`dream_log_change`	Append to recent changes
`dream_rescan`	Trigger full repository rescan
`dream_observe_preference`	Record a learned user preference
`dream_get_preferences`	Return all preferences by category
`dream_sync_obsidian`	Sync memory to Obsidian vault

MCP resources:

Resource	Content
`dream://memory`	Full `CLAUDE.md` as markdown
`dream://tasks`	`TASKS.md` content
`dream://stack`	Tech stack as JSON

File watcher

dream watch

Watches src/, app/, prisma/, package.json, and other key paths. Debounces 10 seconds after the last change, then classifies what changed (schema, package, API, new feature) and updates only the relevant sections of CLAUDE.md. Obsidian syncs automatically if connected.

For automatic updates on every git commit:

dream init --hooks

Project structure

.dream/
  config.json       # Dream configuration
  state.json        # Last scan time, file hashes, token count
  preferences.json  # Learned preferences with frequency weights
  PREFERENCES.md    # Human-readable preference export

CLAUDE.md           # Primary memory — loaded every Claude session
TASKS.md            # Task tracking
.mcp.json           # MCP server config for Claude Code

Supported stacks

Dream detects out of the box:

Frontend: Next.js (App + Pages Router), React, Vue, Nuxt, SvelteKit, Astro, Remix, Angular, Solid.js

Backend: Express, Fastify, NestJS, Hono, Koa, Elysia, tRPC

Database: Prisma, Drizzle, TypeORM, Mongoose, SQLite, PostgreSQL, MySQL, Redis

Auth: Clerk, NextAuth, Supabase, Passport, Lucia, BetterAuth

Testing: Vitest, Jest, Playwright, Cypress, Testing Library

Styling: Tailwind, MUI, Chakra, Styled Components, Emotion, Radix/shadcn

Other languages: Python (FastAPI, Django, Flask), Go, Rust, Java

License

MIT 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
bin		bin
src		src
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
README.md		README.md
TASKS.md		TASKS.md
logo.svg		logo.svg
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

`DREAM`

What it does

Install

Quick start

The session loop

Commands

Core

Preferences

Obsidian

How memory works

Preference learning

Obsidian integration

MCP integration

File watcher

Project structure

Supported stacks

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

DREAM

What it does

Install

Quick start

The session loop

Commands

Core

Preferences

Obsidian

How memory works

Preference learning

Obsidian integration

MCP integration

File watcher

Project structure

Supported stacks

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`DREAM`

Packages