🦞 Give OpenClaw superpowered memory with one command
Install Now
Documentation

OpenClaw Integration Guide

How Onelist solves common AI memory problems and enables efficient, hierarchical memory for OpenClaw.

Note: OpenClaw was previously known as Moltbot and Clawdbot.

Problems Onelist Solves

Current AI memory systems, including OpenClaw's file-based approach, suffer from several key issues:

Problem Impact Onelist Solution
Flat file storage Poor retrieval, no relationships Structured DB with tags, links, metadata
Token inefficiency $11 for "Hi" (full context) Hierarchical loading, summaries first
No proactive retrieval LLMs forget to use tools Pre-loading pipeline
Compaction failures Bloated, unreliable Structured compaction with archival
No decay mechanism Noise overwhelms signal Relevance scoring with decay
Security vulnerabilities Unencrypted local files E2EE (AES-256-GCM)
No versioning Lost context, no audit Full representation history

Installation

Run Onelist alongside OpenClaw with bidirectional file sync. Files remain the source of truth - if Onelist is unavailable, OpenClaw falls back to native file operations.

What You Get

Required Components

  • Onelist Core (Phoenix API)
  • PostgreSQL with pgvector
  • Bidirectional file sync layer

Optional Components

  • Onelist Web (LiveView UI)
  • River agent (GTD, proactive coaching)
  • Other agents (Reader, Librarian, etc.)

Option A: Docker Compose (Recommended)

# Download and configure
curl -sSL https://onelist.my/install/docker-compose.yml -o docker-compose.yml
curl -sSL https://onelist.my/install/.env.example -o .env
nano .env  # Set POSTGRES_PASSWORD, SECRET_KEY_BASE, OPENCLAW_MEMORY_DIR
# Start everything
docker compose up -d
curl http://localhost:4000/health  # Verify

Option B: Native Installation

# Run the install script
curl -sSL https://onelist.my/install.sh | bash -s -- \
  --postgres-port 5433 \
  --onelist-port 4000 \
  --with-openclaw \
  --enable-web \
  --no-agents
# The script will:
# 1. Install PostgreSQL 16 with pgvector on port 5433
# 2. Install Erlang/Elixir
# 3. Download and build Onelist
# 4. Create systemd services
# 5. Configure OpenClaw integration

Configure Optional Components

# In your .env file:
# Required
DATABASE_URL=ecto://onelist:password@localhost:5433/onelist_prod
SECRET_KEY_BASE=your-secret-key-base
OPENCLAW_MEMORY_DIR=/home/user/.openclaw/workspace/memory

# Optional components (all default to false for minimal install)
ENABLE_WEB=true           # Enable Onelist Web UI at localhost:4000
ENABLE_AGENTS=false       # Enable background agents
ENABLE_RIVER=false        # Enable River AI assistant

# If enabling agents
OPENAI_API_KEY=sk-...     # Or other LLM provider

Key guarantee: Files are ALWAYS the source of truth. If Onelist fails or is removed, OpenClaw works exactly as before using native file operations.

Memory Hierarchy Pattern

Onelist implements a four-layer memory hierarchy, conceptualized as "bed/sheet/clothes/pillow":

Layer 1: FOUNDATIONAL ("The Bed")
  entry_type: 'core_memory'
  tags: ['memory:foundational']
  Examples: User name, timezone, critical rules
  Lifespan: Permanent
  Loading: ALWAYS in context (~200-500 tokens)

Layer 2: PROFILE ("The Sheet")
  entry_type: 'preference', 'behavioral_pattern'
  tags: ['memory:profile']
  Examples: Communication style, work patterns
  Lifespan: Evolves over time
  Loading: Pre-loaded by topic (~300-800 tokens)

Layer 3: EPISODIC ("The Clothes")
  entry_type: 'memory', 'conversation_summary'
  tags: ['memory:episodic', 'session:{id}']
  Examples: Recent conversations, open threads
  Lifespan: Days to weeks (then compacted)
  Loading: Recency + relevance search (~500-2000 tokens)

Layer 4: TASK-SPECIFIC ("The Pillow")
  entry_type: 'derived_insight', 'working_memory'
  tags: ['memory:working']
  Examples: Synthesized answers, research findings
  Lifespan: Minutes to hours
  Loading: Generated on-demand (~200-500 tokens)

TOTAL BUDGET: ~1,200-3,800 tokens
(vs. unbounded in naive approaches)

Implementation with Onelist API

# Store a foundational memory (always loaded)
client.entries.create(
    entry_type="core_memory",
    title="User timezone",
    content="User is in Pacific Time (UTC-8)",
    tags=["memory:foundational", "permanent"],
    metadata={"immutable": True}
)

# Store a profile memory (topic-based loading)
client.entries.create(
    entry_type="preference",
    title="Prefers concise responses",
    content="User has indicated they prefer...",
    tags=["memory:profile", "communication"],
    metadata={
        "confidence": 0.85,
        "last_observed": "2026-01-28",
        "observation_count": 12
    }
)

# Store an episodic memory (recent context)
client.entries.create(
    entry_type="memory",
    title="Discussion about API design",
    content="We discussed REST vs GraphQL...",
    tags=["memory:episodic", "session:abc123", "topic:api"],
    metadata={
        "session_id": "abc123",
        "channel": "slack"
    }
)

Token Optimization

The key to cost-effective AI memory is using multiple representations of the same content:

Summary Representation

2-3 sentences, key facts only

~50 tokens

Full Markdown

Complete content for deep retrieval

~500+ tokens

Structured JSON

Key-value pairs for programmatic access

~100 tokens

Embedding Vector

For semantic search (not text tokens)

0 context tokens

Cost Savings Example

For a simple "Hi" message with 100 memories:

  • Naive approach: 100 x 500 tokens = 50,000 tokens (~$0.50/request)
  • Summary-first: 100 x 50 tokens = 5,000 tokens (~$0.05/request)
  • 10x cost reduction

Next Steps