blackroad-os-docs/docs/portals/lucidia.md

Lucidia — Personal AI Portal

"Your AI that actually knows you."

Portal ID: portal.lucidia Status: Planning Primary Domain: Personal AI Assistant

---

Overview

Lucidia is the flagship portal of BlackRoad OS — a personal AI assistant that maintains persistent memory, learns your preferences over time, and operates across all your tools with full governance and audit capabilities.

Unlike current AI assistants that forget you between sessions, Lucidia builds a genuine understanding of who you are, how you work, and what you need.

---

Core Value Proposition

The Problem

Current AI assistants suffer from:

1. Amnesia — Every conversation starts fresh, no matter how many times you've talked
2. Context blindness — They don't know about your other tools, documents, or workflows
3. One-size-fits-all — Same responses for everyone, no personalization
4. Black box operations — No visibility into what the AI is doing or why

The Lucidia Solution

Problem	Lucidia Solution
Amnesia	Persistent memory across sessions
Context blindness	Integrated with your tools via MCP
One-size-fits-all	Learned preferences and communication style
Black box	Full audit trail via governance layer

---

Key Features

1. Persistent Memory

Lucidia remembers:

• Conversations — Past discussions and their context
• Preferences — How you like things done
• Relationships — People, projects, and their connections
• Patterns — Your work rhythms and habits

Memory Types:
├── Episodic     — Specific events and conversations
├── Semantic     — Facts and knowledge about you
├── Procedural   — How you do things
└── Contextual   — What's relevant right now

2. Multi-Tool Orchestration

Lucidia connects to your tools:

Category	Integrations
Communication	Gmail, Slack, Discord, Calendar
Documents	Google Drive, Notion, Dropbox
Development	GitHub, Linear, Jira
Finance	Stripe, QuickBooks
Creative	Figma, Canva

All orchestrated through the BlackRoad governance layer.

3. Adaptive Communication

Lucidia learns your style:

• Tone — Formal, casual, technical, playful
• Detail level — Brief summaries vs. comprehensive explanations
• Format preferences — Bullet points, prose, tables
• Domain language — Your industry's terminology

4. Proactive Assistance

Beyond reactive Q&A:

• Anticipate needs — "You have a meeting with Sarah in 30 min — here's context from your last conversation"
• Surface connections — "This relates to the project you discussed last week"
• Suggest actions — "Based on this email, should I draft a response?"

5. Privacy & Control

You own your data:

• Local-first — Core memory stored locally when possible
• Encryption — End-to-end encryption for cloud sync
• Export — Full data export anytime
• Deletion — Complete memory wipe on request

---

Architecture

Component Diagram

┌─────────────────────────────────────────────────────────────┐
│                      LUCIDIA PORTAL                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Chat UI    │  │  Voice UI    │  │  Widget UI   │       │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘       │
│         │                 │                 │                │
│  ┌──────▼─────────────────▼─────────────────▼──────┐        │
│  │              CONVERSATION ENGINE                 │        │
│  └──────────────────────┬──────────────────────────┘        │
│                         │                                    │
│  ┌──────────────────────▼──────────────────────────┐        │
│  │              MEMORY MANAGER                      │        │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ │        │
│  │  │Episodic │ │Semantic │ │Procedural│ │Context │ │        │
│  │  └─────────┘ └─────────┘ └─────────┘ └────────┘ │        │
│  └──────────────────────┬──────────────────────────┘        │
│                         │                                    │
├─────────────────────────┼───────────────────────────────────┤
│                    GOVERNANCE LAYER                          │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │ Cece    │ │ Policy  │ │ Ledger  │ │ Intent  │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
├─────────────────────────┼───────────────────────────────────┤
│                    INTEGRATION LAYER                         │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │ Gmail   │ │ Drive   │ │ Notion  │ │ GitHub  │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
└─────────────────────────────────────────────────────────────┘

Memory Architecture

interface LucidiaMemory {
  // Core identity
  user_id: string;
  created_at: string;

  // Episodic memory (conversations)
  conversations: Conversation[];

  // Semantic memory (knowledge about user)
  profile: UserProfile;
  preferences: UserPreferences;
  relationships: Relationship[];

  // Procedural memory (how user does things)
  workflows: Workflow[];
  patterns: Pattern[];

  // Contextual memory (current state)
  active_projects: Project[];
  recent_topics: Topic[];
  pending_tasks: Task[];
}

interface UserProfile {
  name: string;
  roles: string[];           // "founder", "developer", "parent"
  communication_style: {
    formality: 'casual' | 'professional' | 'adaptive';
    verbosity: 'brief' | 'detailed' | 'adaptive';
    tone: 'warm' | 'direct' | 'playful';
  };
  domains: string[];         // Areas of expertise/interest
  timezone: string;
  work_hours?: {start: string; end: string};
}

interface Relationship {
  entity_id: string;
  name: string;
  type: 'person' | 'company' | 'project';
  context: string;           // How user knows them
  last_mentioned: string;
  sentiment?: 'positive' | 'neutral' | 'negative';
  notes: string[];
}

---

User Experience

Conversation Modes

1. Quick Chat (Default)

Fast, focused interactions for simple questions and tasks.

User: What's on my calendar today?
Lucidia: You have 3 meetings:
  - 10:00 AM: Team standup (30 min)
  - 2:00 PM: 1:1 with Sarah (45 min) — she wanted to discuss the Q1 roadmap
  - 4:30 PM: Investor call (1 hour)

Anything you want me to prep for these?

2. Deep Work

Extended sessions for complex tasks with maintained context.

User: Let's work on the investor deck
Lucidia: Got it. I remember we started this last week — you had the
problem/solution section done and were working on the market size slide.

I found 3 relevant docs in your Drive:
  - "Market Research Q4" (last edited yesterday)
  - "Competitor Analysis" (from October)
  - "TAM/SAM/SOM Notes" (your brainstorm from last month)

Want me to pull the key numbers, or should we start with reviewing
what you have so far?

3. Ambient Mode

Background awareness without active conversation.

• Monitors incoming messages
• Surfaces relevant information proactively
• Prepares context for upcoming meetings
• Suggests actions when appropriate

Proactive Notifications

Lucidia can surface information without being asked:

[Before a meeting]
Lucidia: Heads up — your 1:1 with Sarah is in 15 min.

Quick context:
• Last time you discussed the Q1 roadmap and hiring plans
• She mentioned concerns about the timeline for the API project
• You said you'd look into the budget allocation

Want me to pull the relevant Notion doc?

---

Governance Integration

Every Lucidia action flows through the governance layer.

Policy Compliance

# Example policies for Lucidia
policies:
  - scope: lucidia.memory.write
    rules:
      - condition: "contains_pii == true"
        action: require_human_approval
        reason: "PII storage requires explicit consent"

  - scope: lucidia.external.share
    rules:
      - condition: "true"
        action: require_human_approval
        reason: "External sharing always needs approval"

Audit Trail

Every significant action creates a ledger event:

{
  "event_id": "evt-20251130-000123",
  "intent_id": "int-20251130-xyz",
  "agent_id": "lucidia.assistant.v1",
  "tool": "memory",
  "action": "write",
  "inputs_hash": "sha256:abc...",
  "policy_decision": {
    "result": "allowed",
    "policy_id": "pol-memory-standard"
  },
  "notes": "Stored preference: user prefers bullet points"
}

---

API Endpoints

Conversation

# Send message
POST /portal/lucidia/chat
{
  "message": "What's on my calendar today?",
  "context": {
    "mode": "quick",
    "include_memory": true
  }
}

# Get conversation history
GET /portal/lucidia/conversations?limit=10

# Continue specific conversation
POST /portal/lucidia/conversations/{conversation_id}/messages

Memory

# Get user profile
GET /portal/lucidia/memory/profile

# Update preferences
PATCH /portal/lucidia/memory/preferences
{
  "verbosity": "brief",
  "tone": "direct"
}

# Add relationship
POST /portal/lucidia/memory/relationships
{
  "name": "Sarah Chen",
  "type": "person",
  "context": "VP of Engineering at current company"
}

# Search memory
GET /portal/lucidia/memory/search?q=investor+meeting

Integrations

# List connected tools
GET /portal/lucidia/integrations

# Connect new tool
POST /portal/lucidia/integrations
{
  "tool": "gmail",
  "scopes": ["read", "draft"]
}

# Invoke tool through Lucidia
POST /portal/lucidia/tools/invoke
{
  "tool": "gmail",
  "action": "search",
  "params": {
    "query": "from:sarah@company.com"
  }
}

---

Privacy & Data

Data Storage

Data Type	Storage	Encryption	Retention
Conversations	Cloud + Local	AES-256	User-controlled
Memory (core)	Cloud + Local	AES-256	Indefinite
Memory (ephemeral)	Local only	AES-256	30 days
Tool credentials	Secure vault	RSA-4096	Until revoked

User Controls

• View all data — Full transparency into what Lucidia knows
• Edit memory — Correct or remove specific memories
• Export data — Download complete memory in JSON
• Delete data — Full wipe with confirmation
• Pause learning — Stop memory updates temporarily

Compliance

• GDPR-compliant data handling
• Right to erasure (Article 17)
• Data portability (Article 20)
• No training on user data without consent

---

Pricing Tiers

Tier	Price	Features
Free	$0/mo	100 messages/day, 7-day memory, 2 integrations
Pro	$20/mo	Unlimited messages, persistent memory, 10 integrations, voice
Team	$50/user/mo	Shared context, team memory, admin controls
Enterprise	Custom	Self-hosted, custom integrations, SLA

---

Roadmap

MVP (Phase 1)

• Basic chat interface
• Episodic memory (conversation history)
• Gmail + Calendar integration
• Simple preference learning

Beta (Phase 2)

• Full memory system
• 5+ integrations
• Voice interface
• Proactive notifications

v1.0 (Phase 3)

• Ambient mode
• Advanced personalization
• Team features
• Mobile apps

Future

• Local LLM option
• Plugin marketplace
• Cross-device sync
• AR/VR interfaces

---

Technical Requirements

Client

• Modern browser (Chrome, Firefox, Safari, Edge)
• Optional: Desktop app (Electron)
• Optional: Mobile app (iOS/Android)

Server

• Cloudflare Workers (edge)
• Railway (backend)
• Cloudflare KV/D1 (storage)
• Vector database (memory search)

LLM

• Primary: Claude API
• Fallback: Self-hosted Mistral
• Memory: Local embeddings

---

References

• Architecture Overview
• Governance Layer
• API Design
• KV Schema