Trident Plugin

Permanent memory for OpenClaw agents. Lossless capture, intelligent routing, semantic recall, and disaster recovery in five tiers.

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

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:

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:

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

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

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.