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#

ProblemSolutionAgents 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#

text

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:

DeploymentSetup TimeCostBest ForNative binaries (qdrant-latest.tar.gz + falkordb)5 min$0Any VPS, local dev, isolated networksDocker Compose10 min$0Containerized OpenClaw, orchestrationQdrant Cloud + Redis Cloud5 min$0–50/moMinimal infrastructure management**Air-gapped (offline)**15 min$0Fully 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:

javascript

// 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):

javascript

// 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:

javascript

// 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):

javascript

// 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#

bash

clawhub install shivaclaw/trident

Or from GitHub:

bash

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

2. Binary Setup (Automatic)#

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

bash

# 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#

bash

# Create directory structure + config
openclaw trident init

# Runs Layer 0.5 signal router (one-time bootstrap)
openclaw trident bootstrap

4. Verify#

bash

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:

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#

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

---

Platform Support#

All platforms supported. Pick your deployment mode:

PlatformNative BinariesDockerCloudLinux (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#

bash

# 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#

bash

# 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#

bash

# 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:

• qdrant-latest.tar.gz (7.2 MB) — Compiled for x64/ARM architectures
• falkordb-standalone (4.1 MB) — Go binary, zero dependencies

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

---

Troubleshooting#

"Qdrant binary failed to start"#

bash

# Check if port 6333 is available
lsof -i :6333

# Or use alternative port
openclaw trident configure --qdrant-port 6334

"FalkorDB connection timeout"#

bash

# 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:

bash

openclaw trident rebuild-embeddings

---

Migration from Trident v1.x#

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

bash

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#

• GitHub: ShivaClaw/trident-plugin
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

License#

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

---

Your agent deserves to remember. Trident makes it permanent.