Moltbot Integration Guide

Problems Onelist Solves

Current AI memory systems, including Moltbot'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 Moltbot with bidirectional file sync. Files remain the source of truth - if Onelist is unavailable, Moltbot 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, MOLTBOT_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-moltbot \
  --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 Moltbot 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
MOLTBOT_MEMORY_DIR=/home/user/moltbot/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, Moltbot 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

Summary-First Pattern

# BAD: Load full content (expensive)
memories = client.entries.search(
    query=query,
    representation="markdown"
)
context = "\n".join([m.content for m in memories])  # 10,000+ tokens!

# GOOD: Load summaries first (cheap)
memories = client.entries.search(
    query=query,
    representation="summary",
    limit=20
)
context = "\n".join([m.content for m in memories])  # ~1,000 tokens

# Only fetch full content when specifically needed:
if need_detail:
    full = client.entries.get(id, representation="markdown")

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

Proactive Memory Retrieval

LLMs frequently fail to call memory search tools when needed. Onelist solves this with a pre-loading pipeline:

User Message Arrives
        |
        v
+----------------------------------------+
|  STEP 1: Intent Classification         |
|  (fast, cheap model - <50ms)           |
|  - Classify: question/task/social      |
|  - Extract: people, projects, dates    |
|  - Estimate: relevant topics           |
+----------------------------------------+
        |
        v
+----------------------------------------+
|  STEP 2: Parallel Memory Retrieval     |
|  (100-200ms)                           |
|  - Foundational memories (always)      |
|  - Semantic search for topics          |
|  - Entity-specific memories            |
|  - Recent session context              |
+----------------------------------------+
        |
        v
+----------------------------------------+
|  STEP 3: Context Assembly              |
|  - Rank by relevance to query          |
|  - Select top-k within token budget    |
|  - Use summaries unless detail needed  |
+----------------------------------------+
        |
        v
+----------------------------------------+
|  STEP 4: LLM Invocation                |
|  System prompt + Pre-loaded context    |
|  (Memory tool still available backup)  |
+----------------------------------------+

Target latency: 200-400ms for steps 1-3

Intent-Based Retrieval Rules

Intent	Retrieval Strategy
Question about past	Semantic search + temporal filter
Task request	Recent context + related projects
Person mentioned	All memories tagged with person
Follow-up	Current session + parent thread
Scheduling	Calendar entries + preferences

Memory Compaction

Without compaction, 100 daily interactions becomes 36,500 entries per year. Onelist provides structured compaction:

Daily Compaction

Memories 7+ days old are grouped by session/topic, summarized, and linked to originals.

Weekly Digests

Daily summaries are combined into weekly digests with pattern identification.

Monthly Insights

Enduring insights extracted to Profile layer. Behavioral patterns updated.

Result: 98.5% Reduction

Before: 36,500 entries (one year)
After: ~530 searchable entries
Original content preserved in archives, accessible when needed

Migration from MEMORY.md

If you have existing memory files, the file sync layer automatically imports them when Onelist starts:

# The file watcher automatically syncs all .md files in your memory directory
# Just point MOLTBOT_MEMORY_DIR to your existing files

# Or manually trigger a full re-sync:
curl -X POST http://localhost:4000/api/v1/sync/rescan

# The importer will:
# 1. Parse all .md files in your memory directory
# 2. Extract facts, preferences, and episodes
# 3. Classify into memory hierarchy layers
# 4. Create vector embeddings for hybrid search
# 5. Files remain source of truth (bidirectional sync)

Implementation Checklist

Install via Docker Compose or install script
Set MOLTBOT_MEMORY_DIR to your memory directory
Verify file sync is working (check /api/v1/sync/status)
Point Moltbot to local Onelist API (http://localhost:4000/api/v1)
(Optional) Enable Web UI: ENABLE_WEB=true
(Optional) Enable agents: ENABLE_AGENTS=true, ENABLE_RIVER=true
(Optional) Enable cloud sync backup ($3/mo)