Content
# Lucid — Synthetic Dreaming for AI Agents
[](https://www.npmjs.com/package/@lucid-dream/mcp-server)
[](LICENSE)
An MCP server that gives AI agents the ability to **dream**.
Lucid accumulates context from your working sessions — files read, code written, problems encountered, observations made — and when enough material has gathered, composes it into associative dream prompts that generate novel code artifacts.
The result is a **shadow codebase**: a growing collection of AI-generated code that emerges from the collision of your daily work, past conversations, and ambient context. Dreams surface unexpected connections, prototype ideas you haven't consciously considered, and build a persistent creative substrate alongside your real codebase.
> **5 tools** | **SQLite + FTS5** | **14.6 kB packed** | **Zero cloud/network dependencies**
## How It Works
```
absorb → absorb → absorb → pulse (not yet) → absorb → pulse (DREAM!)
↓
compose fragments
(buffer + archive + ambient)
↓
return dream prompt
↓
agent generates code from prompt
↓
store_dream → shadow/
```
1. **Absorb** context throughout your session (automatic or manual)
2. **Pulse** periodically to check if the dream threshold is reached
3. When ready, Lucid composes a **dream prompt** from shuffled, fragmented context
4. Your AI agent generates code from the prompt
5. **Store** the dream artifact in the shadow codebase (SQLite + filesystem)
6. **Recall** past dreams when they're relevant to current work
## Installation
```bash
npm install @lucid-dream/mcp-server
```
Or clone and build from source:
```bash
git clone https://github.com/petesumners/lucid-mcp.git
cd lucid-mcp
npm install
npm run build
```
## Configuration
### Claude Code
Add to your Claude Code MCP settings (`~/.claude/settings.json` or project `.claude/settings.json`):
```json
{
"mcpServers": {
"lucid": {
"command": "npx",
"args": ["@lucid-dream/mcp-server"],
"env": {
"LUCID_DATA_DIR": "/path/to/your/dream-data"
}
}
}
}
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"lucid": {
"command": "npx",
"args": ["@lucid-dream/mcp-server"],
"env": {
"LUCID_DATA_DIR": "/path/to/your/dream-data"
}
}
}
}
```
### Data Directory
Lucid stores its database and shadow codebase in a **data directory**. Configure it via (in priority order):
1. **CLI flag**: `--data-dir /path/to/data`
2. **Environment variable**: `LUCID_DATA_DIR=/path/to/data`
3. **Default**: the package installation directory
The data directory will contain:
- `lucid.db` — SQLite database (dreams, buffer, search index)
- `shadow/` — generated code artifacts organized by date
### Optional Integrations
Lucid can pull fragments from external context sources to enrich dreams. These are all optional — if not configured, Lucid works perfectly well with just its own buffer.
| Variable | Description |
|----------|-------------|
| `LUCID_ARCHIVE_DB` | Path to a SQLite database with `messages_fts` table (e.g., conversation archive) |
| `LUCID_AMBIENT_DB` | Path to a SQLite database with transcript/notes tables (e.g., device metadata) |
| `LUCID_DREAMBOX_DIR` | Path to a directory of `.md` journal files (e.g., offline dream logs) |
## Tools
### `absorb`
Feed context into the dream buffer.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | enum | yes | `file_read`, `code_written`, `problem`, `observation`, or `dream_seed` |
| `content` | string | yes | The context content (code, notes, error messages, etc.) |
| `source` | string | no | Source identifier (file path, URL, label) |
**Returns:** `{ absorbed, entry_id, token_estimate, buffer: { entries, tokens } }`
### `pulse`
Check if enough context has accumulated to trigger a dream. Call this periodically (e.g., every few tool calls).
**Parameters:** None
**Returns (not ready):** `{ dream: false, buffer: { entries, tokens, entry_threshold, token_threshold } }`
**Returns (dream triggered):**
```json
{
"dream": true,
"prompt": "You are entering a dream state...",
"fragments": [...],
"themes": ["database", "async", "error-handling", ...],
"buffer_snapshot": 25
}
```
When `dream: true`, the agent should generate code from the returned `prompt`, then call `store_dream` with the result.
### `store_dream`
Persist a generated dream artifact to the shadow codebase.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `code` | string | yes | The generated code |
| `extension` | string | yes | File extension (`py`, `ts`, `rs`, etc.) |
| `language` | string | yes | Language name |
| `summary` | string | yes | 1-3 sentence description of what emerged |
| `prompt` | string | yes | The dream prompt that was used |
**Returns:** `{ stored, dream_id, file_path, keywords, source_count }`
### `recall`
Search the shadow codebase for dreams relevant to current work. Uses hybrid FTS5 + keyword overlap scoring.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | yes | Search query |
| `limit` | number | no | Max results (1-20, default 5) |
**Returns:** `{ results: [{ dream, score, match_type }], query }`
### `journal`
Browse dream history — filter by date, keyword, or list recent dreams.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `date` | string | no | Filter by date (`YYYY-MM-DD`) |
| `keyword` | string | no | Filter by extracted keyword |
| `limit` | number | no | Max results (1-50, default 10) |
**Returns:** `{ dreams: [...], total }`
## Dream Thresholds
Dreams don't trigger on every pulse — they require accumulated context:
| Parameter | Default | Description |
|-----------|---------|-------------|
| Entry threshold | 20 | Minimum buffer entries before dream-eligible |
| Token threshold | 4000 | Minimum accumulated tokens (~16K characters) |
| Dream probability | 0.7 | Chance of dreaming when threshold is met |
Both thresholds use OR logic: reaching either one makes a dream possible.
## Shadow Codebase Structure
```
shadow/
├── 2026-03-04/
│ ├── 07d8e998/
│ │ ├── dream.py # Generated code artifact
│ │ └── metadata.json # Keywords, summary, provenance
│ └── a6461b5f/
│ ├── dream.ts
│ └── metadata.json
└── 2026-03-05/
└── ...
```
Each dream is a self-contained directory with the code artifact and metadata. The shadow codebase grows over time, building a searchable corpus of AI-generated ideas.
## Architecture
```
┌─────────────────────────────────────────────────┐
│ MCP Client │
│ (Claude Code, etc.) │
└──────────┬──────────────────────┬───────────────┘
│ stdio │
┌──────────▼──────────────────────▼───────────────┐
│ Lucid MCP Server │
│ │
│ ┌─────────┐ ┌─────────┐ ┌──────────────┐ │
│ │ absorb │ │ pulse │ │ store_dream │ │
│ └────┬────┘ └────┬────┘ └──────┬───────┘ │
│ │ │ │ │
│ ┌────▼────────────▼───────────────▼──────────┐ │
│ │ Context Engine │ │
│ │ buffer ops · threshold · fragment · themes │ │
│ └────┬───────────────────────────┬───────────┘ │
│ │ │ │
│ ┌────▼────┐ ┌─────────┐ ┌────▼────┐ │
│ │ SQLite │ │ Shadow │ │Optional │ │
│ │ (WAL) │ │ FS │ │Integr. │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└──────────────────────────────────────────────────┘
```
- **SQLite (WAL mode)**: FTS5-indexed dreams, context buffer, keywords, config
- **Shadow filesystem**: Date-organized code artifacts with metadata
- **Optional integrations**: External databases and journal files for richer dream material
## Why Dreaming?
AI agents spend all their time executing directed tasks. Lucid adds a generative layer — a creative process that runs alongside productive work. Dreams:
- **Surface unexpected connections** between disparate parts of your codebase
- **Prototype ideas** you haven't consciously considered
- **Build associative memory** that improves over time via recall
- **Create a searchable archive** of creative AI output
The shadow codebase isn't meant to be production code. It's a substrate — raw creative material that occasionally produces something genuinely useful or illuminating.
## Related MCP Servers
- **[@dental-ai/mcp-server](https://github.com/petesumners/dental-mcp)** — 14 dental office tools (patients, appointments, insurance, SMS). Open Dental + Twilio integration.
- **[@phone-mcp/server](https://github.com/petesumners/phone-mcp)** — 8 telephony tools (calls, SMS, caller ID, recordings). Twilio-powered, zero-dependency.
## License
MIT
