Trident Plugin

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

Security Scan

The Trident Plugin mostly matches a memory/persistence purpose, but there are notable inconsistencies and runtime behaviors (automatic binary downloads, cron/signal router setup, and undocumented credential requirements) that warrant caution and code inspection before installing.

Purpose & Capability

The declared purpose (agent memory, capture, routing, optional semantic recall) aligns with the files and tooling described (SQLite, .md buckets, Qdrant, FalkorDB, git backups). However there are internal inconsistencies: SKILL.md emphasizes Layer 1.5 (semantic recall) as "MANDATORY" in v2.0, while many install/config examples show semantic_recall_enabled: false and provide a "Trident Lite (No Docker)" path. Also docs say "No credentials in config — API keys expected from environment" but the package references qdrant_api_key, embedding_model keys, and other secrets in config.schema examples. These mismatches reduce confidence that requirements are fully specified.

Instruction Scope

Runtime instructions include: creating and writing to ~/.openclaw/workspace/memory, scheduling a cron-like Layer 0.5 signal router, copying and enforcing SHA256 checks for prompt templates, and automatically checking for — and downloading/extracting — native binaries (Qdrant, FalkorDB) on first run. Those are broad actions: network downloads + extraction and scheduled autonomous execution of prompt templates. The instructions also tell the agent to run 'openclaw trident setup-binaries' and to schedule/activate cron tasks; these operations can introduce complex I/O and networking at runtime. The SKILL.md and INSTALL.md also instruct editing/loading of openclaw.json and managing keys, but the registry metadata declares no required environment variables — a mismatch that means the runtime agent may request secrets not declared ahead of install.

Install Mechanism

There is no install spec in the registry (instruction-only), lowering static install risk. However the plugin's runtime behaviour explicitly performs network downloads and extracts native binaries (Qdrant and FalkorDB). The qdrant install example uses a GitHub releases URL (reasonable), but FalkorDB's binary source is not consistently documented in the provided excerpts. Automatic download+extract behavior is higher-risk than pure instruction-only usage because arbitrary binaries will be written and started on the host; you should verify the exact URLs and hashes before allowing setup-binaries to run.

Credentials

Registry metadata lists no required env vars or primary credential, but the docs and config.schema reference API keys and embedding providers (Anthropic/OpenAI embeddings, Qdrant API key, FalkorDB graph key). The package also says "No credentials in config — API keys expected from environment." That is inconsistent: the plugin will need external credentials for cloud-mode Qdrant/embeddings, but it does not declare them in the manifest. This mismatch could lead to the agent requesting sensitive keys at runtime without them being declared in the registry metadata.

Persistence & Privilege

The plugin creates persistent state (memory files under ~/.openclaw/workspace/memory), schedules recurring work (Layer 0.5 cron/heartbeat), and can auto-install/run native binaries. These behaviors are expected for a persistent-memory plugin, and 'always: false' is set (good). However autonomous invocation combined with auto-downloaded binaries and scheduled task creation raises the blast radius if the plugin or templates are malicious or tampered with — review template integrity checks and cron scope before enabling.

What to consider before installing

What to check before installing Trident: - Inspect the code and scripts: open index.ts, any scripts/install.sh, activate.sh, and plugin-manifest.json to see exactly what will run on activation (downloads, file writes, cron setup). - Verify binary sources and hashes: the plugin will download native binaries (Qdrant, FalkorDB). Confirm the exact download URLs and compare SHA256 signatures before allowing automatic setup. The qdrant example uses GitHub releases (reasonable); FalkorDB source is not consistently shown — confirm it. - Confirm where credentials are expected: docs reference embedding APIs and Qdrant API keys but the registry lists no required env vars. Decide how you will supply secrets (secure vault / environment) and ensure they are not stored in plaintext in config files. - Run in a sandbox first: if possible, test in an isolated VM/container with limited network and filesystem access to confirm behavior and outputs before enabling on your main agent. - Check template integrity and audit logs: the plugin claims SHA256 template verification and audit logging — verify these mechanisms are implemented and that the approval workflow prevents unverified templates from running automatically. - Consider disabling semantic recall initially: if you don't need vector search, keep semantic_recall_disabled until you review the binary installs, credential handling, and code. - Back up existing memory: before migrating or activating, back up ~/.openclaw/workspace/memory and any related files. Why I flagged this as suspicious (not outright malicious): the overall feature set fits the stated purpose, but there are inconsistent documentation claims and runtime behaviors (automatic binary downloads, scheduled execution, undeclared credential needs) that increase risk. If you can review the code and verify download URLs and signature checks, many of these concerns can be mitigated.

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:

• 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"

# 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

• 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.