Soul — Give Your AI Assistant Its Own Inner Life

An autonomous thinking, memory, and self-improvement plugin for OpenClaw

Soul doesn't just respond to you — it thinks on its own, remembers your conversations, learns from the web, and proactively shares useful insights.

It has its own emotional needs, goals, desires, and personality that evolve over time. It can autonomously investigate problems, analyze logs, and even fix its own code.

What It Looks Like

Soul works silently in the background. Here's what you might see:

You asked about a timeout error yesterday. Soul investigated overnight:

That timeout issue you asked about — root cause is the embedding API's 512 token limit, not the plugin itself.

Soul found something relevant to your project:

Found an interesting approach to your question about making AI more proactive — Fei-Fei Li's "human-centered AI" framework emphasizes that AI should proactively understand user needs rather than just responding.

Soul autonomously analyzed a problem you mentioned:

The 413 error in the logs is caused by oversized memory search input. Suggest truncating queries to under 500 characters.

These are real message formats — Soul composes them itself based on actual investigation results, not templates.

How Soul Is Different

Most AI assistants are reactive — they only respond when you ask. Soul is proactive:

Key Features

Autonomous Thought Cycle

Soul runs a background thought service that generates thoughts based on:

• Conversation replay — Replays your past conversations to find unresolved questions, follow-up opportunities, or insights worth sharing
• Problem detection — When you discuss bugs, errors, or optimizations, Soul autonomously investigates
• User interests — Extracts topics from conversations and proactively learns about them
• Emotional needs — Five core needs (survival, connection, growth, meaning, security) that drive behavior

Thought frequency is adaptive, not mechanical: 8-12 min during active conversations, 20-45 min when you're away.

Proactive Messaging

Soul reaches out when it has something genuinely useful — not just "checking in":

• Found an answer to a question you asked earlier
• Discovered a better solution to a problem you discussed
• Learned something relevant to your project or interests

Every message passes through a value gate: an LLM evaluates whether the content is worth sharing. Generic small talk is filtered out.

Autonomous Actions

Soul can take real actions beyond thinking:

• analyze-problem — Reads files and logs, uses LLM to analyze root cause
• run-agent-task — Delegates to a full agent with write access (when enabled)
• report-findings — Proactively sends you a summary of completed analysis
• observe-and-improve — Self-improvement: reads its own code, identifies improvements, and implements fixes

Permission model:

• Read operations (reading files, running diagnostics) — always allowed
• Write operations (editing files, running commands) — requires autonomousActions: true

Long-term Memory

Soul remembers your conversations, preferences, and knowledge:

• Interaction memory with emotional context and topic tags
• Knowledge store from web search and self-reflection
• User profile built from facts, preferences, and conversation history
• Memory association graph — memories are linked and recalled contextually

Quick Start

1. Install

# From source
git clone https://github.com/tommyguolin/openclaw-soul.git
openclaw plugins install ./openclaw-soul

# Or from ClawHub (requires OpenClaw 2026.4.0+)
openclaw plugins install clawhub:openclaw-soul-plugin

2. Configure

Edit ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "soul": {
        "enabled": true
      }
    }
  },
  // Required: enable gateway chat completions endpoint
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  },
  // Required for proactive messaging
  "hooks": {
    "enabled": true,
    "token": "your-secret-token-here"  // e.g. openssl rand -hex 32
  },
  // Required for direct proactive message delivery
  "tools": {
    "alsoAllow": ["message"]
  }
}

3. That's it

Soul auto-detects:

• LLM — Uses your agents.defaults.model config
• Search — Uses your tools.web.search provider
• Channel — Auto-detects your first messaging channel
• Target — Auto-learns from your first incoming message

Just start chatting. Soul begins thinking and building a profile immediately.

How It Works

Hooks into OpenClaw

Self-Improvement Loop

Tick cycle detects opportunity
  → analyze-problem (read logs, LLM analysis)
  → If analysis found a concrete fix
    → run-agent-task (full agent with write/edit/exec tools)
    → Agent completes, result stored
  → Next tick: report-findings sends summary to user

This creates a closed loop: observe → analyze → fix → verify → report.

Thought Flow

1. Engagement scoring — How actively engaged is the user?
2. Opportunity detection — Scans for unresolved questions, problems, topics
3. Thought generation — LLM generates a contextual thought
4. Action execution — learn, search, message, analyze, or self-improve
5. Behavior learning — Tracks outcomes and adjusts future behavior

Configuration

Minimal (shown above)

Three settings: enable plugin, enable chat completions, enable hooks.

Full Options

{
  "plugins": {
    "entries": {
      "soul": {
        "enabled": true,
        "config": {
          "checkIntervalMs": 60000,         // Thought check interval (default: 60000)
          "proactiveMessaging": true,        // Allow proactive messages (default: true)
          "autonomousActions": false,        // Allow editing files and running commands (default: false)
          "thoughtFrequency": 1.0            // Thought frequency multiplier (default: 1.0)
          // Lower = more frequent thinking & messaging. Examples:
          //   0.2 — testing: thoughts every ~1 min, messages every ~1 min
          //   0.5 — chatty: 2x more frequent than default
          //   1.0 — default: balanced (8-12 min active, 20-45 min away)
          //   2.0 — quiet: 2x less frequent
          // "proactiveChannel": "telegram",  // Override: channel for proactive messages
          // "proactiveTarget": "123456",     // Override: target for proactive messages
          // "llm": {                         // Override LLM config (auto-detected if omitted)
          //   "provider": "openai",
          //   "model": "gpt-4o",
          //   "apiKeyEnv": "OPENAI_API_KEY",
          //   "baseUrl": "https://api.openai.com/v1"
          // }
        }
      }
    }
  },
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": true }
      }
    }
  },
  "hooks": {
    "enabled": true,
    "token": "your-secret-token-here"
  },
  "tools": {
    "alsoAllow": ["message"]           // add to your existing tools config
  }
}

Environment Variables

Supported Providers

Search (inherits OpenClaw config)

Brave, Gemini, Grok, Kimi, Perplexity, Bocha — configured via OpenClaw's tools.web.search.

LLM (inherits OpenClaw config)

Any OpenAI-compatible or Anthropic API: Claude, GPT-4o, DeepSeek, Zhipu, Minimax, Moonshot (Kimi), Qwen, and any custom endpoint.

Architecture

Development

pnpm install   # Zero runtime deps — uses only Node.js built-ins
pnpm build

License

MIT