OpenLucid
A marketing world model for merchants β make marketing data findable, understandable, and usable for AI, agents, and MCP apps.
Ask AI about OpenLucid
Powered by Claude Β· Grounded in docs
I know everything about OpenLucid. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π§ OpenLucid β Marketing World Model for AI
English | δΈζ
Structure your marketing data so AI can find it, understand it, and put it to work.
The way most marketing tools store data β fragments of text in 10 different SaaS products, raw files in cloud drives, brand rules buried in PDFs β makes them invisible to AI. OpenLucid is a self-hosted layer that pulls all of it together, structures it, and exposes it through three first-class interfaces: MCP for AI agents, REST API for automation, and a Web UI for marketing teams.
The same brand knowledge that powers your Web UI directly powers Claude Code, Cursor, OpenClaw, and any custom agent β without copy-paste.
β If OpenLucid helps you, please give us a star β it really helps the project grow.
β¨ Why OpenLucid
- π§ AI-readable by design β Knowledge, audiences, scenarios, brand rules, assets β every field is structured, scored, and tagged. Not raw files and free text.
- π MCP-first β External agents are the brain. OpenLucid contributes the prompt discipline + the data layer; Claude / GPT / your-own-LLM stays in charge of reasoning.
- π‘οΈ Server-enforced rules β Things like merchant defaulting and source-of-truth conflicts are guarded server-side, not by hoping the agent reads instructions.
- βοΈ Self-hosted, single-tenant β Your data, your DB, your model keys. Two containers, no Redis, no message queue.
- π Three interfaces, one source of truth β Web UI, REST API, MCP, and a CLI. Add an offer in any of them β the others see it instantly.
π§© Core Modules
| Module | What it does |
|---|---|
| π§ Knowledge Base | Structured merchant knowledge: selling points, audience insights, usage scenarios, FAQs, objection handling. Manual or AI-inferred. |
| π Asset Library | Upload images, videos, documents. AI auto-extracts metadata, tags, scores. Filter by content-form (unboxing/review/tutorial) or campaign-type (flash sale/BOGO). |
| π― Strategy Units | Define audience Γ scenario Γ goal Γ channel combos to focus content direction. |
| π¨ Brand Kit | Logo, brand voice, colors, fonts, persona presets β guardrails that keep all output on-brand. |
| π‘ Topic Studio | Generate multi-platform topic plans grounded in your KB and assets. |
| βοΈ Script Writer / Content Studio | Produce short-video scripts or social copy with platform Γ persona Γ structure presets. |
| π¬ Video Generation | Turn a script into a digital-human video via Chanjing / Jogg (avatar + voice + aspect + B-roll + captions). |
| π Creations Library | Every finished piece (post / script / email / hook) auto-saved for reuse, comparison, and agent referral. |
| β KB Q&A | AI-powered Q&A that cites your knowledge base without fabricating. |
π Plug In Your Agent
Three interfaces, pick what fits β they all read and write the same data:
| Interface | For | How |
|---|---|---|
| MCP Server | Claude Code, Cursor, OpenClaw, AI IDEs | Connect via MCP protocol; AI reads your marketing data directly |
| RESTful API | Custom agents, automation | Full API with interactive docs at /docs |
| CLI Tool | Agent scripting, ops queries | Standalone Python script over HTTP, zero project deps |
| Web UI | Marketing teams | Visual UI for managing knowledge, assets, brand kits, topics |
π Quick Start
Prerequisites: Docker and Docker Compose installed and running.
git clone https://github.com/agidesigner/OpenLucid.git
cd OpenLucid/docker
cp .env.example .env
docker compose up -d
Once started, open http://localhost :
- First visit lands on the setup page β create your admin account
- Go to Settings to configure your LLM (any OpenAI-compatible API)
- Create your first product / offer and start planning
- (Optional) Install the CLI so AI agents can query your marketing data:
bash tools/install.sh openlucid setup
π‘ Only 2 containers (PostgreSQL + App). No Redis, no message queue, no extra dependencies.
π€ Connecting AI Agents
OpenLucid is built MCP-first. After running bash tools/install.sh, the OpenLucid skill is registered globally so any agent in any project directory discovers it automatically:
| Agent | Skill installed at |
|---|---|
| Claude Code | ~/.claude/skills/openlucid/SKILL.md |
| Cursor | ~/.cursor/skills/openlucid/SKILL.md |
| Codex / OpenHands | ~/.agents/skills/openlucid/SKILL.md |
Now ask your agent things like:
- "List all merchants and offers for my workspace"
- "Import this product URL into OpenLucid and infer the knowledge base"
- "What are the key selling points of [product]?"
- "Draft a Xiaohongshu post for [product] using its brand voice"
The agent uses the OpenLucid MCP to read structured data, calls the LLM to reason, and writes the result back via add_knowledge_item / save_creation β all under your data sovereignty.
π οΈ Common Commands
Run from the docker/ directory:
docker compose up -d # Start
docker compose down # Stop
docker compose restart # Restart
docker compose logs -f app # View logs
docker compose ps # Check status
π§ Configuration
All settings are managed in docker/.env (template at docker/.env.example):
| Variable | Default | Description |
|---|---|---|
DB_USER | openlucid | Database username |
DB_PASSWORD | openlucid | Database password (change in production!) |
DB_NAME | openlucid | Database name |
APP_PORT | 80 | Port exposed on host |
SECRET_KEY | change-me-in-production | JWT secret (change in production!) |
LOG_LEVEL | INFO | Log level |
LLM configuration lives in the Web UI (Settings β LLM) β supports multiple models, scene-based routing, visual switching.
β FAQ
Q: Why "Marketing World Model"? A new marketing app needs structured ground-truth about products, brand voice, audiences, and assets to reason well. OpenLucid is that ground-truth layer β designed to be queried and updated by AI agents, not just humans.
Q: Do I need a specific LLM? No. OpenLucid speaks the OpenAI Chat Completions API; any compatible LLM works (Claude, GPT, DeepSeek, Qwen, Gemini, Ollama, your own). You configure model + key in the Web UI.
Q: Does it talk to MCP clients other than Claude Code?
Yes. Anything that speaks MCP (Cursor, OpenClaw, custom clients) connects via the same /mcp endpoint. Tool list, prompts, and resources are identical across clients.
Q: How is data stored?
PostgreSQL 16 in your own container. No SaaS, no third-party vector DB, no telemetry. Asset files live on the host disk under uploads/.
Q: Can I run it offline / behind a VPN? Yes β once dependencies are installed, the only outbound traffic is to your configured LLM endpoint (and optional video provider Chanjing/Jogg if you use Video Generation).
Q: I forgot my admin password / lost access to my email / need to provision the first admin from a script.
See the Self-Hosting Operations Guide β there's a direct-DB CLI (docker compose exec app python -m app.cli ...) that bypasses email and HTTP entirely for these recovery cases.
Q: Can I customize the writing rules per platform (WeChat / blog / xiaohongshu / ...) or per persona / narrative-structure?
Yes β every platform / persona / narrative-structure / content-form / campaign-type prompt ships as a markdown file you can edit. The shipped defaults stay in git, your customizations live in a docker volume that survives git pull. See SELF_HOSTING.md#customizing-content-generation-prompts.
π οΈ Tech Stack
| Layer | Technology |
|---|---|
| Backend | Python 3.11 Β· FastAPI Β· SQLAlchemy 2.0 (async) Β· Alembic |
| Database | PostgreSQL 16 |
| Frontend | HTML Β· Tailwind CSS Β· Alpine.js (no build step) |
| AI | OpenAI SDK (compatible with any OpenAI-format LLM API) |
| Deployment | Docker Compose |
π¬ Community
Find me on π / Twitter β I share notes on building OpenLucid, marketing AI patterns, and self-hosted agent setups:
Or reach out at ajin@jogg.ai for partnership / commercial inquiries.
π’ Feedback & Support
- π Found a bug β open an Issue
- π‘ Feature idea β open a discussion or feature request
- β Liked it? β Star this repo so more people find it!
π License
OpenLucid is available under a modified Apache License 2.0 with additional conditions for multi-tenant use and branding. See LICENSE for details.
