lucidmemo

A local dream journal built for agents first, with a CLI for direct control.

Connect lucidmemo to an MCP-capable agent client, such as OpenClaw, Hermes, Claude, or another local assistant. The agent can capture fragile recall, submit structured analysis, ask clarification questions, and query your journal without sending the database to a hosted app.

Configure MCP Use the CLI

Agent workflow

The agent is the capture surface.

The original use case is simple: wake up, tell an agent what you remember, and let that agent call lucidmemo through MCP. The agent can transcribe, save the raw recall, ask where it belongs, submit structured dream analysis, and later search patterns across the journal.

Capture without overthinking

Agents call record_recall_entry first. Dream assignment can wait until the user is awake enough to answer.

Clarify instead of guessing

If late recall might belong to an existing dream, a new dream, or no known sleep session, the agent asks before merging it.

Query through tools

Agents use get_dreams, get_dream, and get_dream_graph instead of scraping exported files.

Submit official analysis

OpenClaw, Hermes, and other agents call submit_dream_analysis when they have canonical text, lucidity signals, HVdC structure, and entities.

Keep the journal local

The MCP server runs on your machine and talks to the local database. The client chooses which model or agent sees each interaction.

CLI quick start

Use the CLI when you want direct control.

# setup
pnpm install
pnpm build
pnpm test

# capture recall
lucidmemo record --text "I checked my hands and became lucid."
lucidmemo record --audio ./dream.webm --duration-ms 120000 --mime-type audio/webm
lucidmemo submit-analysis --file analysis.json

# search later
lucidmemo query --text "hands lucid" --lucidity 3+
lucidmemo graph

How it thinks

Recall is saved before the system tries to organize it.

The data model keeps fast morning capture separate from later interpretation. That keeps the first entry honest, while still allowing edits, corrections, analysis versions, and exports with provenance.

Record Recall Entry

Save text, audio, or both immediately. Unclear dream linkage can stay unassigned.

Assign Dream Record

Group recall into a dated dream when enough context is known.

Analyze And Query

Use local extraction or agent-submitted structure, then query entities, lucidity signals, emotions, and graph relationships from the current analysis.

CLI surface

Commands stay close to journal work.

The CLI covers capture, sleep metadata, analysis, query, graph output, diagnostics, deletion, and export without requiring a hosted service.

record Capture text, audio, or both.

sleep Create or update sleep-session metadata.

reanalyze Create a local deterministic current analysis.

submit-analysis Store agent-returned analysis as the current official Dream Analysis.

export Export JSON, Markdown, or CSV. Add provenance when needed.

doctor storage Inspect database size, audio storage, and slow-storage risks.

MCP setup

Point your agent client at lucidmemo.

Build the MCP server, then add it to the MCP server list in your agent client. Use an absolute path if the client does not run from this repository.

# build the stdio MCP server
pnpm --filter @lucidmemo/mcp-server build

# generic MCP client config
{
  "mcpServers": {
    "lucidmemo": {
      "command": "node",
      "args": [
        "/absolute/path/to/lucidmemo/packages/mcp-server/dist/index.js"
      ]
    }
  }
}

record_recall_entry assign_recall_entry submit_dream_analysis get_dreams get_dream_graph correct_recall_content export_journal

The server also provides the prompts lucidmemo/capture and lucidmemo/query so agents follow the Recall Entry-first workflow. Submitted analysis becomes current immediately, while older analyses remain available through provenance export.

The repository also ships agent skills for capture, analysis, query, and export. Skills are workflow guidance for agent clients; MCP tools remain the executable interface.

Agent analysis

Agents can return the structured dream analysis.

{
  "dreamId": "<dream-id>",
  "canonicalText": "I met my brother at a glowing train station and became lucid.",
  "sourceAgent": "OpenClaw",
  "sourceModel": "hermes-analysis",
  "lucidityLevel": 4,
  "dreamSigns": ["train station"],
  "emotions": ["wonder"],
  "hvdc": {
    "characters": ["brother"],
    "settings": ["train station"],
    "objects": ["ticket"]
  },
  "entities": [
    { "type": "person", "name": "Brother", "context": "waited near the platform" },
    { "type": "place", "name": "Train Station" }
  ]
}

The same shape works through MCP submit_dream_analysis or CLI lucidmemo submit-analysis --file analysis.json.

Storage and export

Local by default, inspectable when needed.

The default database path is ~/.lucidmemo/journal.db. Audio lives in a separate table from hot recall metadata so regular journal queries do not load audio blobs.

Default exports include active journal data. The --provenance flag includes deleted, superseded, and non-current analysis history for audit or migration.

Coming up

Real transcription adapters

Whisper, Deepgram, and other configured providers.

Hosted automation

Optional paid services that run analysis automatically after capture.

Apps for capture and review

Mobile and watch capture for quick audio recall; desktop for review, cleanup, and journal management.