Quick Start

npm install -g @lucid-agent/cli
cd your-project
lucid init

That's it. Lucid will scan your project, build an initial memory, and run its first analysis in under two minutes.

What is Lucid?

Most AI coding tools forget everything between sessions. You spend the first ten minutes of every conversation re-explaining your project, your conventions, your ongoing work. Lucid fixes this.

Lucid runs as a lightweight background daemon that watches your codebase for meaningful changes, thinks about them using the model of your choice, and remembers what it learns in a persistent, growing memory. It catches bugs you missed, spots patterns across commits, and delivers insights to your desktop, Slack, or Discord — only when they matter.

Lucid brings always-on background intelligence to every developer — with any model provider, fully open source.

How It Works

                    ┌─────────────────────────────────┐
                    │          LUCID DAEMON            │
                    │                                  │
  File changes ───▶ │  WATCH ──▶ TICK ──▶ DREAM      │
  Git events   ───▶ │           (cheap)   (thorough)  │
                    │                        │         │
                    │                   ┌────┴────┐    │
                    │                   │ MEMORY  │    │
                    │                   │ 3-Layer │    │
                    │                   └────┬────┘    │
                    │                        │         │
                    │                     NOTIFY ─────▶│──▶ Desktop / Slack / Discord
                    └─────────────────────────────────┘

1. Watch — Monitors file system events and git hooks. Debounces noise.
2. Tick — A cheap, fast model call (~$0.0001) decides: "Is this worth waking up for?"
3. Dream — If yes, a thorough analysis runs: code review, issue detection, memory consolidation.
4. Remember — Findings persist in a 3-layer memory system that grows smarter over time.
5. Notify — Actionable insights delivered through your preferred channel.

The key insight: cheap ticks, expensive dreams. Background monitoring costs nearly nothing. Real analysis only happens when it matters.

Features (Phase 1 — Shipping Now)

• Always-on daemon — Runs in the background, checking for changes every 60 seconds
• Persistent memory — LUCID.md index survives across sessions, grows with your project
• Budget controls — Daily spend caps, per-dream cost tracking, transparent pricing
• Desktop notifications — Native alerts for high-priority insights
• Git-aware — Understands branches, commits, merges, and conflicts
• First-run magic — Install to first insight in under 2 minutes
• Memory search — lucid recall to search across all logs and memory

New in v0.2

• Multi-model — OpenAI (GPT-4o), Google (Gemini), and local models via Ollama
• Full 3-layer memory — Topic files + SQLite archive with FTS5 full-text search
• Slack & Discord — Webhook notifications with priority-based routing
• Cross-layer consolidation — Automatic deduplication, contradiction resolution, pruning

Coming Soon

• Lucid Cloud — Hosted daemon, GitHub App, team memory (Phase 4)

CLI Commands

# Setup
lucid init                        # Interactive setup in your repo
lucid init --provider anthropic   # Non-interactive with provider flag

# Daemon
lucid start                       # Start the background daemon
lucid start --foreground          # Run in foreground (for debugging)
lucid stop                        # Stop the daemon
lucid status                      # Show daemon state and memory stats

# Analysis
lucid dream                       # Force a dream cycle now
lucid dream --focus "auth,api"    # Dream with specific focus areas

# Memory
lucid recall "authentication"     # Search memory for a topic
lucid recall --recent             # Show recent insights
lucid memory                      # Show the current LUCID.md index
lucid memory --stats              # Memory size, topic count, etc.

# Activity
lucid log                         # Show today's activity
lucid log --yesterday             # Yesterday's activity
lucid log --week                  # This week's summary

# Configuration
lucid config                      # Show current config
lucid config set models.dream "openai:gpt-4o"

Configuration

Create a lucid.toml in your project root (generated by lucid init):

[models]
tick = "anthropic:claude-haiku"      # Cheap and fast for tick checks
dream = "anthropic:claude-sonnet"    # Thorough for dream analysis
max_daily_spend = 5.00               # Hard budget cap in USD

[daemon]
tick_interval_seconds = 60           # How often to check for changes
consolidate_every = 5                # Consolidate memory every N dreams

[notifications]
desktop = true                       # Native desktop notifications
# [notifications.slack]
# webhook_url = "https://hooks.slack.com/services/..."
# min_priority = "medium"            # low, medium, high, critical
# [notifications.discord]
# webhook_url = "https://discord.com/api/webhooks/..."
# min_priority = "medium"

[watch]
ignore = [
  "node_modules/**",
  "dist/**",
  ".lucid/**",
  "*.lock",
]

API keys are read from environment variables (never stored in config):

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=...
# Ollama: no key needed, just run `ollama serve`

Supported Models

| Provider | Tick Model | Dream Model | Status | |----------|-----------|-------------|--------| | Anthropic | Claude Haiku | Claude Sonnet | Available | | OpenAI | GPT-4o Mini | GPT-4o | Available | | Google | Gemini Flash | Gemini Pro | Available | | Ollama | Any local model | Any local model | Available |

Architecture

Lucid uses a 3-layer memory system inspired by how production-grade agent architectures manage context:

Layer 1: LUCID.md — A lightweight markdown index at your project root. Always loaded, always current. Under 4KB. Contains pointers to deeper knowledge.

Layer 2: Topic Files — Focused deep-dives stored in .lucid/topics/. Created and pruned by the dream engine. Loaded only when relevant.

Layer 3: Session Archive — Full dream transcripts in SQLite with full-text search. Never loaded into model context directly — queried when historical context is needed.

The tick evaluator is the critical cost-control mechanism. On every interval, it makes a tiny model call (<600 tokens total) to decide if a full dream is warranted. This keeps background costs under $2/day while ensuring nothing important is missed.

The Memory File

LUCID.md lives at your project root and is the shared knowledge your team's AI has about the codebase:

# Lucid Memory Index

## Project
- TypeScript monorepo, Next.js frontend + Express API, PostgreSQL
- Auth: NextAuth with Google OAuth, session-based
- Deploy: Vercel (frontend) + Railway (API)

## Active Concerns
- [topic:auth-migration] Migrating from session to JWT — in progress
- [topic:perf-issues] API response times degraded after analytics middleware

## Patterns Observed
- Team tends to skip error handling in API routes — flag in reviews
- Database queries in /api/users are N+1 — suggested fix on 2026-03-28

## Recent Dreams
- 2026-03-31 02:14 — Reviewed feat/jwt-auth, found token expiry not handled
- 2026-03-30 18:30 — Consolidated memory, pruned 3 stale topics

LUCID.md is committed to your repo — it's shared project knowledge. The .lucid/ directory (logs, topics, database) is gitignored.

Roadmap

Phase 1: Core MVP (Complete)

• [x] CLI skeleton — 9 commands (init, start, stop, status, dream, log, recall, memory, config)
• [x] Background daemon — detached process, PID management, Unix socket IPC, graceful shutdown
• [x] File watcher — chokidar-based with debouncing and configurable ignore patterns
• [x] Git hooks — post-commit, post-checkout, post-merge event capture
• [x] Tick evaluator — cheap model call (<600 tokens) to gate expensive dreams
• [x] Dream engine — full code analysis with budget gating and insight validation
• [x] Layer 1 memory — LUCID.md with section-aware merge, 4KB enforcement, mtime caching
• [x] Anthropic provider — Claude Haiku (tick) + Claude Sonnet (dream) with retry + backoff
• [x] Desktop notifications — node-notifier integration
• [x] Daily activity log — append-only markdown logs with dream summaries
• [x] Cost tracking — per-dream cost estimation, daily budget cap
• [x] Configuration — TOML config with env var overrides, Zod validation
• [x] Landing page — single index.html, spec-compliant design, CSS terminal animation
• [x] Text-based recall — search across LUCID.md + log history

Phase 2: Memory & Multi-Model (Complete)

• [x] OpenAI provider (GPT-4o-mini tick, GPT-4o dream)
• [x] Google provider (Gemini Flash tick, Gemini Pro dream)
• [x] Ollama provider (local models, zero API cost)
• [x] Layer 2 topic files — .lucid/topics/ with on-demand loading
• [x] Layer 3 session archive — SQLite + FTS5 full-text search
• [x] Memory consolidation — contradiction resolution, deduplication, pruning

Phase 3: Integrations (Complete)

• [x] Slack notifications (webhook-based with Block Kit formatting)
• [x] Discord notifications (webhook-based with embeds)
• [x] Priority-based notification routing (configurable per channel)

Phase 4: Lucid Cloud (Future)

• [ ] Semantic recall — embedding-based memory search
• [ ] GitHub App for webhook integration
• [ ] Hosted daemon infrastructure
• [ ] Web dashboard for memory browsing
• [ ] Team memory — shared insights across developers
• [ ] Waitlist → beta invites flow

Development

git clone https://github.com/jnoble157/lucid.git
cd lucid
npm install
npm run build
npm run test

See AGENTS.md for architecture decisions, coding standards, and file-specific guidance.

See docs/STATUS.md for detailed implementation status and what's needed for each phase.

Contributing

Contributions welcome! Here's how:

1. Fork the repo and create a branch (feat/my-feature or fix/my-bug)
2. Follow the coding standards in AGENTS.md — strict TypeScript, no any, max 300 lines per file
3. Add tests for new functionality
4. Run npm run build && npm test before submitting
5. Open a PR with a clear description

Priority areas for contribution:

• Semantic recall — embedding-based memory search (needs EmbeddingProvider design)
• GitHub webhooks (src/notify/github-webhook.ts) — cloud version foundation
• Integration tests — CLI commands, daemon socket, git hooks

Support

If Lucid is useful to you, consider supporting development:

License

MIT