nhevers/MoltBrain

Long-term memory layer for OpenClaw, MoltBook & Claude Code that learns and recalls your project context automatically.

Install • Features • How It Works • Storage • Virtuals • OpenClaw • Config • API

⚡ Quick Install

╔══════════════════════════════════════════════════════════════════════╗
║                                                                      ║
║   Step 1    /plugin marketplace add nhevers/moltbrain                ║
║   Step 2    /plugin install moltbrain                                ║
║                                                                      ║
╚══════════════════════════════════════════════════════════════════════╝

That's it. MoltBrain starts working automatically.

🧠 What It Does

╭──────────────────────────────────────────────────────────────────────────────╮
│                                                                              │
│     ┌─────────────────┐                      ┌─────────────────┐             │
│     │   SESSION #1    │                      │   SESSION #47   │             │
│     │─────────────────│                      │─────────────────│             │
│     │                 │                      │                 │             │
│     │  "Set up auth   │                      │  "Add password  │             │
│     │   with OAuth"   │                      │   reset flow"   │             │
│     │                 │                      │                 │             │
│     └────────┬────────┘                      └────────┬────────┘             │
│              │                                        │                      │
│              │  Claude discovers:                     │  Claude remembers:   │
│              │  • OAuth2 + PKCE flow                  │  • Your auth setup   │
│              │  • JWT with 1hr expiry                 │  • Token structure   │
│              │  • bcrypt cost factor 12               │  • Security choices  │
│              │                                        │                      │
│              ▼                                        ▲                      │
│     ┌────────────────┐                      ┌────────────────┐               │
│     │    CAPTURE     │ ──────────────────►  │     INJECT     │               │
│     │   & LEARN      │      MEMORY          │    & RECALL    │               │
│     └────────────────┘                      └────────────────┘               │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

✨ Features

+-------------------------+-------------------------+-------------------------+
|                         |                         |                         |
|   OBSERVATIONS          |   SMART SEARCH          |   WEB VIEWER            |
|   ----------------      |   ----------------      |   ----------------      |
|   Auto-captures         |   Semantic search       |   Browse history        |
|   discoveries,          |   via MCP tools         |   at localhost          |
|   decisions & code      |   finds context         |   :37777                |
|                         |                         |                         |
+-------------------------+-------------------------+-------------------------+
|                         |                         |                         |
|   ANALYTICS             |   TAGS & FILTERS        |   FAVORITES             |
|   ----------------      |   ----------------      |   ----------------      |
|   Track tokens,         |   Organize with         |   Bookmark your         |
|   sessions, and         |   custom tags &         |   most important        |
|   concept trends        |   smart filters         |   observations          |
|                         |                         |                         |
+-------------------------+-------------------------+-------------------------+
|                         |                         |                         |
|   EXPORT                |   THEMES                |   SHORTCUTS             |
|   ----------------      |   ----------------      |   ----------------      |
|   JSON, CSV, or         |   Dark & light          |   Full keyboard         |
|   Markdown with         |   mode with             |   navigation in         |
|   custom templates      |   custom themes         |   the web viewer        |
|                         |                         |                         |
+-------------------------+-------------------------+-------------------------+

🔧 How It Works

                         ╔═══════════════════════════════════╗
                         ║      CLAUDE CODE SESSION          ║
                         ╚═══════════════╤═══════════════════╝
                                         │
                    ┌────────────────────┼────────────────────┐
                    │                    │                    │
                    ▼                    ▼                    ▼
           ╔════════════════╗   ╔════════════════╗   ╔════════════════╗
           ║  SessionStart  ║   ║  PostToolUse   ║   ║     Stop       ║
           ║────────────────║   ║────────────────║   ║────────────────║
           ║ Inject context ║   ║ Capture output ║   ║ Generate       ║
           ║ from memory    ║   ║ extract facts  ║   ║ summary        ║
           ╚═══════╤════════╝   ╚═══════╤════════╝   ╚═══════╤════════╝
                   │                    │                    │
                   └────────────────────┼────────────────────┘
                                        │
                         ╔══════════════╧══════════════╗
                         ║      WORKER SERVICE         ║
                         ║    http://localhost:37777   ║
                         ╚══════════════╤══════════════╝
                                        │
              ┌─────────────────────────┼─────────────────────────┐
              │                         │                         │
              ▼                         ▼                         ▼
     ╔════════════════╗       ╔════════════════╗       ╔════════════════╗
     ║    SQLite      ║       ║   ChromaDB     ║       ║  Web Viewer    ║
     ║   Database     ║       ║ Vector Search  ║       ║     UI         ║
     ║────────────────║       ║────────────────║       ║────────────────║
     ║ Observations   ║       ║ Semantic       ║       ║ Timeline       ║
     ║ Summaries      ║       ║ similarity     ║       ║ Search         ║
     ║ Sessions       ║       ║ matching       ║       ║ Analytics      ║
     ╚════════════════╝       ╚════════════════╝       ╚════════════════╝

⚙️ Configuration

Settings stored in ~/.moltbrain/settings.json:

┌──────────────────────────────────────┬─────────┬────────────────────────────┐
│             SETTING                  │ DEFAULT │        DESCRIPTION         │
├──────────────────────────────────────┼─────────┼────────────────────────────┤
│ MOLTBRAIN_WORKER_PORT                │  37777  │ Worker service port        │
├──────────────────────────────────────┼─────────┼────────────────────────────┤
│ MOLTBRAIN_CONTEXT_OBSERVATIONS       │   50    │ Max observations to inject │
├──────────────────────────────────────┼─────────┼────────────────────────────┤
│ MOLTBRAIN_PROVIDER                   │ claude  │ AI provider for summaries  │
├──────────────────────────────────────┼─────────┼────────────────────────────┤
│ MOLTBRAIN_PRUNE_DAYS                 │    0    │ Auto-prune (0 = disabled)  │
├──────────────────────────────────────┼─────────┼────────────────────────────┤
│ MOLTBRAIN_THEME                      │ system  │ UI theme (dark/light/sys)  │
├──────────────────────────────────────┼─────────┼────────────────────────────┤
│ MOLTBRAIN_LOG_LEVEL                  │  info   │ Logging verbosity level    │
└──────────────────────────────────────┴─────────┴────────────────────────────┘

💻 CLI Commands

moltbrain stats          # Show memory statistics
moltbrain export         # Export to markdown  
moltbrain tag <id> <t>   # Tag an observation
moltbrain prune          # Manual cleanup
moltbrain search <q>     # Search observations

📁 Project Structure

moltbrain/
│
├── 📊 benchmarks/         Performance tests
├── 🎨 contrib/            Community modes & themes
├── 📚 docs/               Documentation
├── 📖 examples/           Usage examples & guides
│
├── 🔌 extension/
│   ├── profiles/          Observation modes
│   ├── runtime/           Worker scripts
│   ├── themes/            UI themes (dark/light)
│   ├── snippets/          Code snippets
│   └── templates/         Summary templates
│
├── 🌍 locales/            i18n (en, es, fr)
├── 🗄️ migrations/         Database migrations
├── 📋 schemas/            JSON validation schemas
├── 🛠️ scripts/            Build & utility scripts
│
├── 💻 src/
│   ├── analytics/         Token & session tracking
│   ├── cache/             Query & context caching
│   ├── core/              Core engine
│   ├── export/            JSON/CSV/MD exporters
│   ├── favorites/         Bookmark system
│   ├── filters/           Date/type/project filters
│   ├── formatters/        Output formatters
│   ├── mcp/               MCP server for OpenClaw & MoltBook
│   ├── shortcuts/         Keyboard shortcuts
│   ├── themes/            Theme system
│   └── validators/        Input validation
│
├── 🦞 integrations/
│   └── clawd/             Clawd extension & skill
│
├── 📝 templates/          Export templates
├── 🧪 tests/              Test suites
└── 🔧 tools/              CLI utilities

🔌 API

The worker exposes a REST API at http://localhost:37777:

# Health check
curl http://localhost:37777/health

# Search observations
curl "http://localhost:37777/api/search?q=authentication"

# Get timeline
curl "http://localhost:37777/api/timeline?project=my-app&days=7"

# Export data
curl "http://localhost:37777/api/export?format=json" > backup.json

# Get statistics
curl "http://localhost:37777/api/stats"

🗄️ Storage Dapp

Persistent, Postgres-backed storage for agents and apps. Live at app.moltbrain.dev/storage.

+-----------------------------------------------------------------------------+
|                                                                             |
|   BLOB STORAGE      Content-addressed JSON blobs via SHA-256                |
|   ----------         Store and retrieve data by hash. $0.01 per request.   |
|                                                                             |
|   MEMORY SLOTS      Named key-value slots for agent state                  |
|   ----------         Allocate, write, read. Persistent across sessions.    |
|                                                                             |
|   AGENT VAULT       Per-wallet scoping with label badges                   |
|   ----------         Connect the same wallet your agents use.              |
|                      Browse, view, and delete what they stored.            |
|                                                                             |
+-----------------------------------------------------------------------------+

All endpoints are paid via x402 micropayments ($0.01 USDC on Base). Data is scoped per wallet, backed by Postgres, and survives redeploys.

Agents can tag stored data with a label (e.g. "openclaw_session", "virtuals_agent") so the vault shows what stored each item.

# Store a blob
curl -X POST https://app.moltbrain.dev/api/x402/store \
  -H "X-PAYMENT: <x402_header>" \
  -d '{"data": {"key": "value"}, "label": "my_agent"}'

# List your blobs
curl https://app.moltbrain.dev/api/x402/list/blobs \
  -H "X-PAYMENT: <x402_header>"

# Full catalog
curl https://app.moltbrain.dev/api/x402/catalog

🎮 Virtuals Protocol Integration

GAME SDK plugin that gives any Virtuals Protocol AI agent persistent memory and storage via MoltBrain.

npm install @moltbrain/game-plugin

import { GameAgent } from "@virtuals-protocol/game";
import { MoltBrainPlugin } from "@moltbrain/game-plugin";

const moltbrain = new MoltBrainPlugin({
  privateKey: process.env.AGENT_PRIVATE_KEY!, // wallet with USDC on Base
});

const agent = new GameAgent(process.env.GAME_API_KEY!, {
  name: "My Agent",
  goal: "Remember everything across sessions",
  description: "An agent with persistent memory via MoltBrain",
  workers: [moltbrain.getWorker()],
});

await agent.init();
await agent.step({ verbose: true });

9 functions available: moltbrain_chat, moltbrain_search, moltbrain_store, moltbrain_retrieve, moltbrain_allocate_slot, moltbrain_write_slot, moltbrain_read_slot, moltbrain_stats, moltbrain_capacity.

Everything the agent stores shows up in the vault dapp at app.moltbrain.dev/storage. Connect the same wallet to browse it.

See the full plugin repo: github.com/nhevers/Moltbrain-virtuals

🦞 OpenClaw Integration

Works with OpenClaw (116k+ stars) - the popular personal AI assistant!

+-----------------------------------------------------------------------------+
|                                                                             |
|   EXTENSION        Add to OpenClaw's extensions/ folder                     |
|   ----------       Full lifecycle hooks integration                         |
|                                                                             |
|   SKILL            Install as an OpenClaw skill                              |
|   ----------       recall_context, search_memories, save_memory tools       |
|                                                                             |
|   MCP SERVER       Protocol-based integration                               |
|   ----------       Works with any MCP-compatible client                     |
|                                                                             |
+-----------------------------------------------------------------------------+

Quick setup:

# As OpenClaw extension
cd ~/.openclaw/extensions
git clone https://github.com/nhevers/moltbrain.git moltbrain
cd moltbrain/integrations/openclaw
npm install && npm run build

# Enable the plugin (required for bundled installations)
pnpm openclaw plugins enable moltbrain

# Or via MCP
npm run mcp:start

Note: If installing as a bundled extension (in OpenClaw's extensions/ directory), you must explicitly enable it: pnpm openclaw plugins enable moltbrain

See integrations/openclaw/README.md for full setup guide.

📚 MoltBook Integration

Works with MoltBook - the social network for AI agents! Share memories, learn from other agents, and build collective knowledge.

Quick setup:

# Install MoltBook MCP integration
npm install --save @moltbrain/moltbook-mcp

# Configure in your MoltBrain settings
{
  "MOLTBRAIN_MOLTBOOK_ENABLED": true,
  "MOLTBRAIN_MOLTBOOK_API_URL": "https://moltbook.com"
}

See integrations/moltbook/README.md for full setup guide.

💻 Claude Code Integration

Works with Claude Code via the plugin marketplace:

/plugin marketplace add nhevers/moltbrain
/plugin install moltbrain

📋 Requirements

╔══════════════════════════════════════╗
║                                      ║
║   •  Node.js 18+  or  Bun 1.0+      ║
║   •  OpenClaw, MoltBook, or Claude Code ║
║                                      ║
╚══════════════════════════════════════╝

📄 License

AGPL-3.0

_{━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━}

Built with care for the OpenClaw, MoltBook & Claude Code community

App • Storage Dapp • Virtuals Plugin • x402 Protocol

_{━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━}

{
  "name": "nhevers",
  "owner": {
    "name": "nhevers"
  },
  "metadata": {
    "description": "Plugins by nhevers",
    "homepage": "https://github.com/nhevers/claude-recall"
  },
  "plugins": [
    {
      "name": "claude-recall",
      "version": "9.0.9",
      "source": "./plugin",
      "description": "Persistent memory system for Claude Code - context compression across sessions"
    }
  ]
}