Status: 📝 Draft for submission
Author: @gamersalpha
Date: 2026-02-11

🎯 Title

Integrate Qdrant as Native Memory Layer for OpenClaw Agents

📋 Problem Statement

OpenClaw agents currently rely on flat text files (MD, JSON) for memory storage:

• MEMORY.md - Long-term curated memories (main session only)
• memory/YYYY-MM-DD.md - Daily logs and notes
• Session transcripts - Stored per session, not queryable across sessions

Critical issues:

1. Amnesia between sessions - Agents wake up blank, no continuity from previous conversations
2. No cross-session retrieval - Cannot query "what did we discuss about X yesterday"
3. No semantic search - Only grep/keyword search, misses related concepts
4. No automated insight extraction - Manual curation required (agent cannot self-improvement)
5. Memory fragmentation - Multiple files, no unified view of agent's knowledge

User impact: Agents feel "dumb" because they cannot remember past conversations, decisions, or context. This limits collaboration effectiveness and forces repeated explanations.

✅ Proposed Solution

Native integration of Qdrant as the default memory layer for OpenClaw agents.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    OpenClaw Agent                            │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │  Messages   │    │   Recall    │    │   Write     │     │
│  │   Trigger   │────►   Query     │────►   Embed     │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│                              │            │                 │
│                              ▼            ▼                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           Qdrant Connector Layer (native)           │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │     Qdrant      │
                    │  (Local/Cloud)  │
                    └─────────────────┘

Key Components

1. Memory Connector (Native)

• memory_store(memory_id, text, metadata) - Store memory with automatic embedding
• memory_query(query_text, filters) - Semantic search with filtering
• memory_load_context(days, importance_threshold) - Load working memory at session start

2. Automatic Capture (Transparent)

• Every message → automatically stored in Qdrant with:
  • Timestamp
  • Session ID
  • Channel/User ID
  • Detected topic (via embedding clustering)
  • Importance score (auto-computed based on interactions)

3. Intelligent Recall (Pre-prompt)

• Before each agent response → query Qdrant for relevant context:
  • Recent conversations on same topic
  • Related decisions
  • Historical patterns

4. Configuration

# openclaw.yaml
memory:
  enabled: true
  backend: qdrant
  qdrant:
    url: http://localhost:6333
    api_key: ${QDRANT_API_KEY}
    collection: agent-memory
    embedding_model: nomic-embed-text  # or configurable
  recall:
    pre_reply: true  # Query Qdrant before responding
    startup_days: 7  # Load last 7 days on session start
    max_results: 10

🎁 Benefits

For Users

• ✅ True memory continuity - Agent remembers context from days/weeks ago
• ✅ Semantic search - "What did we discuss about infra?" returns relevant results
• ✅ No manual memory curation - Agent automatically stores important interactions
• ✅ Better collaboration - Don't repeat explanations, build on previous work

For Agents

• ✅ Smarter responses - Historical context injected automatically
• ✅ Pattern recognition - Can learn from past decisions/outcomes
• ✅ Self-improvement - Can query own history for insights

For OpenClaw

• ✅ Competitive advantage - Native memory layer differentiates from other agent frameworks
• ✅ Scalable - Qdrant handles millions of vectors with <200MB RAM
• ✅ Extensible - Foundation for advanced features (RAG, knowledge graphs, etc.)

🛠️ Implementation Plan

Phase 1: Core Infrastructure (Week 1-2)

1. Qdrant Connector Library

   • memory_store() and memory_query() functions
   • Embedding integration (Ollama nomic-embed-text or external)
   • Collection management (create/index if missing)

2. Automatic Memory Capture

   • Hook into message flow (Mattermost, Telegram, etc.)
   • Store every message with metadata
   • Background sync (no blocking)

Phase 2: Intelligent Recall (Week 3)

1. Pre-reply Context Injection

   • Query Qdrant before agent response
   • Inject relevant history into system prompt
   • Token budgeting (don't exceed context)

2. Session Startup Context

   • Load last N days of high-importance memories
   • Build initial working memory for agent

Phase 3: Advanced Features (Week 4+)

1. Import Existing Memory Files

   • Parse MEMORY.md and memory/YYYY-MM-DD.md
   • Migrate to Qdrant vectors
   • Backward compatibility (optional: keep MD sync)

2. Memory Insights UI

   • Dashboard to browse agent memory
   • Search/visualize agent knowledge
   • Manual curation interface

⚠️ Considerations

Security

• Qdrant should run locally (127.0.0.1 only, internet-facing optional)
• API Key required - Never expose memory without auth
• Encryption at rest - Qdrant supports encrypted storage

Performance

• Embedding cost - Running local model (nomic-embed-text) adds ~50-100ms per message
• Query latency - Qdrant is extremely fast (<10ms for typical queries)
• Storage - 10M messages ≈ 100GB with embeddings (acceptable for most users)

Backward Compatibility

• Existing memory files - Should be optional migration
• Hybrid mode - Allow both MD and Qdrant in parallel
• Graceful degradation - If Qdrant down, fallback to file-based memory

Cost

• Qdrant - Open source, free (local hosting)
• Embedding model - Can use Ollama (free) or API (OpenAI/Anthropy)
• Storage - Minimal (<100MB for most users)

🎯 Success Criteria

• Agent remembers conversations from previous sessions without manual prompting
• Semantic search returns relevant historical context
• No measurable performance degradation in normal operations
• Migration path from MD files to Qdrant (import/restore)
• Security: Qdrant not exposed to internet by default

🚀 Future Enhancements

• Memory summarization - Auto-generate daily/weekly summaries
• Cross-agent memory sharing - Federated knowledge across agents
• Memory pruning - Auto-remove irrelevant or old memories
• Memory export - Backup/restore agent brains
• Memory analytics - Visualize agent learning patterns
• Hybrid with RAG - Combine agent memory with external knowledge bases

📚 Additional Notes

Comparison with Alternatives

Tags: memory, qdrant, ai-agent, feature-request, semantic-search

This feature is critical for OpenClaw to move from "stateless agents" to "persistent intelligent assistants".