Trident Plugin

Trident Plugin: Memory Tools for OpenClaw Agents

Trident is a five-tier memory system that gives your agent genuine continuity, identity, and semantic recall—with zero vendor lock-in.

Why Your Agent Needs This

| Problem | Solution | |---------|----------| | Agents forget. Each session starts blank. | Layer 0 (SQLite+DAG) captures every message. Nothing lost. | | No continuity. Context evaporates between sessions. | Layer 1 (.md buckets) provides persistent personality and decisions. | | Can't find old context. Memory is unstructured noise. | Layer 1.5 (Qdrant + FalkorDB) enables semantic search across months. | | Fragile. One file corruption = total loss. | Layer 2 (Git + snapshots) provides disaster recovery. | | Vendor lock-in. Trapped with one service. | All layers work offline. Self-hosted or cloud. Your choice. |

The Five-Tier Architecture

LAYER 0:   Lossless capture (SQLite + DAG)
LAYER 0.5: Signal routing (Cron agent, every 15 min)
LAYER 1:   Hierarchical memory (.md files)
LAYER 1.5: Semantic recall (Qdrant + FalkorDB) ← MANDATORY
LAYER 2:   Disaster recovery (Git + snapshots)

Layer 1.5: Why Semantic Recall Is Mandatory

Trident v2.0 makes semantic recall standard, not optional.

Why?

1. Agents with >30K messages cannot efficiently search flat .md files 2. Vector search (Qdrant) + entity graphs (FalkorDB) are the state-of-the-art for agent context retrieval 3. Self-hosted binaries (not Docker) work on ANY OpenClaw instance 4. Cost is zero if you use local binaries; $0–50/mo if you prefer cloud

Deployment Options

You don't need Docker. Pick one:

| Deployment | Setup Time | Cost | Best For | |-----------|-----------|------|----------| | Native binaries (qdrant-latest.tar.gz + falkordb) | 5 min | $0 | Any VPS, local dev, isolated networks | | Docker Compose | 10 min | $0 | Containerized OpenClaw, orchestration | | Qdrant Cloud + Redis Cloud | 5 min | $0–50/mo | Minimal infrastructure management | | Air-gapped (offline) | 15 min | $0 | Fully offline agents |

Installation is automatic. On first run, Trident checks for Qdrant/FalkorDB binaries. If missing, it downloads them.

Four Tools Included

1. Memory Search

Full-text and regex search across all memory:

// Full-text search (recommended)
memory_search({
  query: "job search OR hiring",
  mode: "full_text",
  scope: "messages",  // "messages", "summaries", or "both"
  limit: 50
})
// Regex search
memory_search({
  query: "^\\[lesson\\].*database",
  mode: "regex",
  scope: "both"
})

2. Memory Expand

Expand compacted conversation summaries (LCM):

// By summary ID
memory_expand({
  summary_ids: ["sum_aab3cd29ed348405", "sum_9afa42a01acf640f"],
  max_depth: 3,
  include_messages: true
})
// Or search-first, then expand top results
memory_expand({
  query: "infrastructure outage",
  max_depth: 2,
  token_cap: 4000
})

3. Memory Update

Append to daily episodic logs or update projects:

// Add to today's daily log
memory_update({
  entry: "Deployed Trident v2.0 to production",
  section: "## Milestones",
  tag: "[project]"
})
// Update a project file
memory_update({
  file: "memory/projects/job-search.md",
  entry: "Batch 5: Applied to Genentech, Synthego, Inscripta",
  section: "## Applications",
  tag: "[action]"
})

4. Memory Recall

Answer questions using memory context (uses Qdrant + vector embeddings):

// Retrieve relevant context + answer
memory_recall({
  prompt: "What was the job search status as of last week?",
  similarity_threshold: 0.75,
  max_tokens: 2000,
  include_sources: true  // Return which docs matched
})

Installation & Setup

1. Install the Plugin

clawhub install shivaclaw/trident

Or from GitHub:

clawhub install https://github.com/ShivaClaw/trident-plugin

2. Binary Setup (Automatic)

On first run, Trident checks for Qdrant and FalkorDB binaries:

# Manual setup (if you want to pre-stage binaries):
openclaw trident setup-binaries
This will download and extract:
- qdrant-latest (Qdrant vector database)
- falkordb (FalkorDB graph database)

3. Initialize Memory Tiers

# Create directory structure + config
openclaw trident init
Runs Layer 0.5 signal router (one-time bootstrap)
openclaw trident bootstrap

4. Verify

openclaw trident status
Output:
✅ Layer 0: LCM (SQLite) — operational
✅ Layer 0.5: Signal Router — ready
✅ Layer 1: Hierarchical memory — 47 .md files
✅ Layer 1.5: Qdrant @ localhost:6333 — 1,247 vectors indexed
✅ Layer 1.5: FalkorDB @ localhost:6379 — 342 entities
✅ Layer 2: Git backup — last commit 2h ago

Configuration

Edit ~/.openclaw/workspace/openclaw.json:

{
  "plugins": {
    "trident": {
      "enabled": true,
      "storage_path": "~/.openclaw/workspace/memory",
      
      "layer0": {
        "enabled": true,
        "sqlite_path": "~/.openclaw/workspace/memory/layer0/lossless.db"
      },
      
      "layer0_5": {
        "enabled": true,
        "model": "anthropic/claude-haiku-4-5",
        "interval_minutes": 15,
        "heartbeat_enabled": true,
        "template_sha256_verify": true
      },
      
      "layer1": {
        "enabled": true,
        "hierarchy": {
          "memory": "MEMORY.md",
          "daily": "memory/daily/",
          "self": "memory/self/",
          "lessons": "memory/lessons/",
          "projects": "memory/projects/"
        }
      },
      
      "layer1_5": {
        "enabled": true,
        "qdrant": {
          "mode": "binary",  // "binary", "docker", or "cloud"
          "host": "localhost",
          "port": 6333,
          "binary_path": "~/.openclaw/workspace/memory/layer1_5/qdrant",
          "cloud_url": null
        },
        "falkordb": {
          "mode": "binary",  // "binary", "docker", "redis", or "cloud"
          "host": "localhost",
          "port": 6379,
          "binary_path": "~/.openclaw/workspace/memory/layer1_5/falkordb",
          "cloud_url": null
        },
        "embedding_model": "text-embedding-3-small",
        "batch_size": 100
      },
      
      "layer2": {
        "enabled": true,
        "git": {
          "enabled": true,
          "remote": "https://github.com/YOUR_USERNAME/memory.git",
          "commit_interval_hours": 24
        },
        "snapshots": {
          "enabled": true,
          "path": "~/.openclaw/workspace/memory/snapshots"
        }
      }
    }
  }
}

Cost Breakdown

| Component | Deployment | Cost | |-----------|-----------|------| | Layer 0 (SQLite) | Local | $0 | | Layer 0.5 (Cron) | Local | $0.72–$1.44/day (Haiku) or $0 (Ollama) | | Layer 1 (.md files) | Local | $0 | | Layer 1.5 (Qdrant + FalkorDB) | Native binary | $0 | | Layer 1.5 (Docker) | Docker | $0 | | Layer 1.5 (Cloud) | Qdrant Cloud + Redis Cloud | $20–50/month | | Layer 2 (Git) | GitHub free tier | $0 | | Layer 2 (Snapshots) | VPS | $0 (included) | | TOTAL (self-hosted) | | $0.72–$1.44/day | | TOTAL (cloud) | | $20–50/month |

Platform Support

All platforms supported. Pick your deployment mode:

| Platform | Native Binaries | Docker | Cloud | |----------|-----------------|--------|-------| | Linux (Ubuntu/Debian) | ✅ | ✅ | ✅ | | macOS (Intel/ARM) | ✅ | ✅ | ✅ | | Windows (WSL2) | ✅ | ✅ | ✅ | | VPS (Hostinger, DigitalOcean, AWS) | ✅ | ✅ | ✅ | | Docker container | ✅ | ✅ | ✅ | | Air-gapped (offline) | ✅ | ✅ | ❌ |

Quick Examples

Example 1: Search Memory for Job Context

# In your agent's conversation:
> "What were my last 5 applications?"
Agent uses memory_search internally:
await memory_search({
  query: "application OR applied",
  scope: "messages",
  limit: 50
})
Returns: 7 matching messages from memory/daily/, memory/projects/job-search.md, MEMORY.md

Example 2: Semantic Recall During a Conversation

# Agent context is running low. Layer 0.5 injects relevant memory:
await memory_recall({
  prompt: "What is the current job search strategy?",
  max_tokens: 1500
})
Qdrant searches vectorized memory, FalkorDB retrieves related entities
Returns: 3–5 most relevant context chunks + sources

Example 3: Continuous Memory Updates

# Every heartbeat, Layer 0.5 routes signals:
await memory_update({
  file: "memory/heartbeat/job-search.md",
  entry: "New lead: Synthego Senior Scientist, $140k, strong match",
  tag: "[opportunity]"
})

Architecture Deep-Dive

Layer 1.5: Semantic Recall (How It Works)

1. Embedding pipeline: Every message in Layer 1 is vectorized via text-embedding-3-small 2. Qdrant indexing: Vectors stored in HNSW index for fast similarity search 3. FalkorDB graphs: Entities extracted (names, projects, dates) and linked as graph nodes 4. Pre-turn injection: Before agent turn, query Qdrant for top-K relevant context, inject into system prompt 5. Citation: memory_recall returns sources (file paths, line numbers) for transparency

Binary Distribution

Trident ships Qdrant and FalkorDB as pre-compiled binaries:

On install, binaries are extracted to ~/.openclaw/workspace/memory/layer1_5/. They start automatically on plugin initialization.

Troubleshooting

"Qdrant binary failed to start"

# Check if port 6333 is available
lsof -i :6333
Or use alternative port
openclaw trident configure --qdrant-port 6334

"FalkorDB connection timeout"

# Restart the database
openclaw trident restart-falkordb
Or switch to cloud
openclaw trident configure --falkordb-mode=cloud --falkordb-cloud-url=...

"Memory search is slow"

Qdrant index not built. Rebuild:

openclaw trident rebuild-embeddings

Migration from Trident v1.x

If you're upgrading from v1.x (without Layer 1.5):

openclaw trident migrate v1-to-v2
This will:
1. Download and install Qdrant + FalkorDB binaries
2. Build initial vector embeddings from Layer 1 memory
3. Verify all data integrity
4. Enable Layer 1.5 in config

Zero data loss. All existing memory is preserved and indexed.

Support

License

MIT-0 — Free to use, modify, and redistribute. No attribution required.

*Your agent deserves to remember. Trident makes it permanent.*

Edit ~/.openclaw/workspace/openclaw.json:

{
  "plugins": {
    "trident": {
      "enabled": true,
      "storage_path": "~/.openclaw/workspace/memory",
      
      "layer0": {
        "enabled": true,
        "sqlite_path": "~/.openclaw/workspace/memory/layer0/lossless.db"
      },
      
      "layer0_5": {
        "enabled": true,
        "model": "anthropic/claude-haiku-4-5",
        "interval_minutes": 15,
        "heartbeat_enabled": true,
        "template_sha256_verify": true
      },
      
      "layer1": {
        "enabled": true,
        "hierarchy": {
          "memory": "MEMORY.md",
          "daily": "memory/daily/",
          "self": "memory/self/",
          "lessons": "memory/lessons/",
          "projects": "memory/projects/"
        }
      },
      
      "layer1_5": {
        "enabled": true,
        "qdrant": {
          "mode": "binary",  // "binary", "docker", or "cloud"
          "host": "localhost",
          "port": 6333,
          "binary_path": "~/.openclaw/workspace/memory/layer1_5/qdrant",
          "cloud_url": null
        },
        "falkordb": {
          "mode": "binary",  // "binary", "docker", "redis", or "cloud"
          "host": "localhost",
          "port": 6379,
          "binary_path": "~/.openclaw/workspace/memory/layer1_5/falkordb",
          "cloud_url": null
        },
        "embedding_model": "text-embedding-3-small",
        "batch_size": 100
      },
      
      "layer2": {
        "enabled": true,
        "git": {
          "enabled": true,
          "remote": "https://github.com/YOUR_USERNAME/memory.git",
          "commit_interval_hours": 24
        },
        "snapshots": {
          "enabled": true,
          "path": "~/.openclaw/workspace/memory/snapshots"
        }
      }
    }
  }
}

"Qdrant binary failed to start"

# Check if port 6333 is available
lsof -i :6333
Or use alternative port
openclaw trident configure --qdrant-port 6334

"FalkorDB connection timeout"

# Restart the database
openclaw trident restart-falkordb
Or switch to cloud
openclaw trident configure --falkordb-mode=cloud --falkordb-cloud-url=...

"Memory search is slow"

Qdrant index not built. Rebuild:

openclaw trident rebuild-embeddings