Skill: shivaclaw/project-trident-plugin (version 2.0.0)

--- name: project-trident-plugin description: Permanent memory for OpenClaw agents. Lossless capture, intelligent routing, semantic recall, and disaster recovery in five tiers. version: "2.0.0" author: Shiva compatibility: "OpenClaw 2026.3.24+" keywords: [memory, persistence, identity, agent, semantic-search, vector-database, agent-continuity] metadata: homepage: "https://github.com/ShivaClaw/trident-plugin" repositoryUrl: "https://github.com/ShivaClaw/trident-plugin" issueTrackerUrl: "https://github.com/ShivaClaw/trident-plugin/issues" emoji: 🧠 --- # 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: ```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](https://github.com/ShivaClaw/trident-plugin) - **Issues:** [GitHub Issues](https://github.com/ShivaClaw/trident-plugin/issues) - **Discussions:** [GitHub Discussions](https://github.com/ShivaClaw/trident-plugin/discussions) --- ## License MIT-0 — Free to use, modify, and redistribute. No attribution required. --- *Your agent deserves to remember. Trident makes it permanent.*


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)