Skill: shivaclaw/project-trident-skill (version 2.0.1)

--- name: project-trident-skill description: Give your AI agent genuine continuity, identity, and resilience across every session and deployment with a four-tier persistent memory stack. version: "2.0.1" author: Shiva compatibility: "OpenClaw 2026.3.24+" keywords: [memory, persistence, identity, agent, backup, continuity, learning] metadata: homepage: "https://github.com/ShivaClaw/shiva-memory" repositoryUrl: "https://github.com/ShivaClaw/project-trident" issueTrackerUrl: "https://github.com/ShivaClaw/project-trident/issues" emoji: 🕉️ --- # Project Trident: Four-Tier Persistent Memory Architecture ## The Problem AI agents forget. Every session starts blank. Important context—corrections, decisions, patterns, relationships—evaporates. Most agent frameworks treat memory as an afterthought: flat files or vector databases without intelligent curation. The result: agents that repeat mistakes, lose critical context, and can't develop genuine identity over time. ## The Solution: Four Layers of Durability Trident models memory like computer storage—**with an additional intelligence layer**: | Layer | Role | Storage | Cost | |-------|------|---------|------| | **0** | Baseline durability | SQLite + DAG | Free | | **0.5** | Signal intelligence | Cron agent | $0.72–$1.44/day | | **1** | Semantic organization | `.md` files | Free | | **1.5** (optional) | Vector recall | Qdrant + FalkorDB | Free (self-hosted) | | **2** | Disaster recovery | Git + snapshots | Free | The result: an agent that **never forgets what matters**, **develops genuine personality**, **maintains continuity through crashes**, and **recovers from catastrophic failure**. --- ## What Each Layer Does **New to Trident?** → Read `references/trident-lite.md` No Docker required. Works on Windows, Mac, Linux, and any VPS out of the box. **Already have MEMORY.md, SOUL.md, or custom memory files?** → Run the migration script. **Want Docker-based semantic search?** → Read `references/deployment-guide.md` **Deploying to VPS?** → See Layer 2 (Backup & Updates) section. **Cost-conscious?** → Read `references/cost-calculator.md` --- ## The Four-Tier Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Conversation Input (user messages, tool results, events) │ └──────────┬──────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ LAYER 0: LCM (Lossless Context Management) — RAM │ │ ├─ SQLite persistence (every message) │ │ ├─ DAG lineage tracking │ │ └─ Never loses a message, even after compaction │ └──────────┬──────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ LAYER 0.5: Signal Router (Cron Agent) — SSD │ │ ├─ Every 10–30 min: read daily logs (WAL protocol) │ │ ├─ Classify signals: corrections, decisions, facts, self │ │ ├─ Route to Layer 1 buckets │ │ ├─ Integrated with HEARTBEAT (job checks, trading, etc.) │ │ └─ Cost: $0–$1.44/day depending on model & interval │ └──────────┬──────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ LAYER 1: Hierarchical Memory Buckets — HDD │ │ ├─ MEMORY.md (curated long-term) │ │ ├─ memory/daily/ (raw episodic logs) │ │ ├─ memory/self/ (personality, beliefs, identity) │ │ ├─ memory/lessons/ (learnings, mistakes, tool quirks) │ │ ├─ memory/projects/ (active work, recurring tasks) │ │ ├─ memory/semantic/ (knowledge, facts, technical) │ │ └─ .md format (human-readable, Git-compatible) │ │ │ │ Optional: memory/heartbeat/ for domain-specific tracking │ │ ├─ job-search.md (career info, hot leads, follow-ups) │ │ ├─ trading/portfolio.md (positions, P/L, strategy) │ │ ├─ subagent-status.md (running agents, models, tasks) │ │ └─ time-sensitive.md (reminders, deadlines, TTL items) │ └──────────┬──────────────────────────────────────────────────┘ │ (optional upgrade) ▼ ┌─────────────────────────────────────────────────────────────┐ │ LAYER 1.5: Semantic Recall (Optional) — Add at 50K msgs │ │ ├─ Qdrant vector search (Docker, binary, or cloud) │ │ ├─ FalkorDB entity graphs (Docker, Redis, or cloud) │ │ └─ Pre-turn context injection via Layer 0.5 │ └──────────┬──────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ LAYER 2: Backup & Updates Subsystem — COLD │ │ ├─ Daily Git commits (memory version control) │ │ ├─ VPS snapshots (point-in-time recovery) │ │ ├─ Pre-update snapshots (before OpenClaw upgrades) │ │ ├─ Post-update healthchecks (verify all systems) │ │ └─ Automated rollback on failure │ │ │ │ Crons: │ │ ├─ 4:20 AM MDT: Layer 2 Unified Backup (Git + snapshot) │ │ ├─ 2:00 AM MDT (Sun): Pre-update snapshot │ │ ├─ After update: Post-update healthcheck (21 tests) │ │ └─ Cost: $0 (included in VPS + free Git hosting) │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Platform Support | Platform | Trident Lite | Semantic Recall (Docker) | Semantic Recall (No Docker) | |---|---|---|---| | Linux | ✅ | ✅ | ✅ (native binary) | | macOS | ✅ | ✅ | ✅ (native binary) | | Windows | ✅ | ✅ (WSL2) | ✅ (binary or cloud) | | VPS (Ubuntu/Debian) | ✅ | ✅ | ✅ | | Docker container | ✅ | ✅ | ✅ | See `references/platform-guide.md` for platform-specific commands. --- ## Core Layers (Detailed) ### Layer 0: Lossless Context Management (LCM) **What it does:** - Captures every session message in SQLite - Builds DAG (directed acyclic graph) of message lineage - Preserves full history even after compaction **Why it matters:** - Baseline durability — recovery foundation - Enables Layer 0.5 to reconstruct what happened - Prerequisite: Enable `lossless-claw` plugin in `openclaw.json` **Cost:** $0 (SQLite is built-in) **Key property:** Summaries created by compaction link back to source messages via DAG — nothing is ever truly lost. --- ### Layer 0.5: Signal Router & Heartbeat Integration **What it does:** - Runs every 10–30 minutes (configurable) - **Reads daily logs** (WAL protocol) to detect signals - **Classifies signals** into buckets (corrections, decisions, facts, self-signals) - **Routes to Layer 1** (.md files) - **Integrates HEARTBEAT checks:** - Job search status (active leads, follow-ups, TTL items) - Trading positions (if trading hours: entry/exit/rebalance) - Subagent lifecycle (kill idle/completed, optimize models) - Time-sensitive reminders (e.g., "Outlier AI shutdown in X days") **Signal types and routing:** | Signal | Priority | Destination | Example | HEARTBEAT Integration | |--------|----------|-------------|---------|----------------------| | **Correction** | Highest | MEMORY.md | "It's X, not Y" | N/A | | **Decision** | High | MEMORY.md | "Let's do X" | N/A | | **Self-signal** | High | memory/self/ | Identity shift, belief change | N/A | | **Job update** | High | memory/heartbeat/job-search.md | New lead, follow-up needed | ✅ Check every heartbeat | | **Trading action** | High | memory/heartbeat/trading/ | Entry, exit, P/L update | ✅ During trading hours (6am–4pm MDT) | | **Subagent** | Medium | memory/heartbeat/subagent-status.md | Agent completed, stuck, or model mismatch | ✅ List + optimize agents | | **Time-sensitive** | Medium | memory/heartbeat/time-sensitive.md | Deadline approaching, TTL reminders | ✅ Check deadline fields | | **Project update** | Medium | memory/projects/ | Active sprint, blocker, completion | ✅ Scan for priority tags | | **Learning** | Medium | memory/lessons/ | Tool quirk, debugging note, mistake | ✅ Capture innovations | | **Fact** | Low | memory/semantic/ | Names, dates, numbers | ✅ Update domain knowledge | **Model:** Claude Haiku recommended (cost-optimized, ~95% accuracy for routing) **Cost:** $0.72–$1.44/day depending on interval (15–30 min) **Security:** SHA256 integrity verification prevents prompt injection **Template:** `scripts/layer0-agent-prompt-template.md` (customizable) **Key features:** - **Attention management** — corrections flagged first (never skipped) - **Context awareness** — reads SESSION-STATE.md for current priorities - **Deadline tracking** — alerts for time-sensitive items (e.g., "X days until Outlier AI shutdown") - **Subagent optimization** — suggests killing idle agents, downgrading Sonnet→Haiku - **Domain-specific routing** — job search, trading, research, ops — each gets own bucket --- ### Layer 1: Hierarchical Memory Buckets **What it does:** - Persistent `.md` file organization - Human-readable, Git-compatible, debuggable - Prevents noise accumulation (agentic curation vs auto-capture) **Core structure:** ``` memory/ ├── MEMORY.md ← Curated long-term memory (high-signal, compressed) ├── daily/ ← Raw episodic logs │ ├── 2026-04-19.md │ └── ... ├── self/ ← Personality, identity, growth │ ├── identity.md │ ├── beliefs.md │ └── growth.md ├── lessons/ ← Learnings, mistakes, tool quirks │ ├── tools.md │ ├── mistakes.md │ └── workflows.md ├── projects/ ← Active work (one file per project) │ ├── job-search.md │ ├── infrastructure.md │ └── ... ├── semantic/ ← Knowledge, facts, domain-specific │ ├── biology.md │ ├── crypto.md │ └── ... ├── heartbeat/ ← Time-sensitive, domain-specific tracking │ ├── job-search.md ← Hot leads, follow-ups, deadline tracking │ ├── trading/ │ │ ├── portfolio.md ← Current positions, P/L, strategy │ │ └── trades.md ← Entry/exit log, reasoning │ ├── subagent-status.md ← Running agents, models, TTL │ └── time-sensitive.md ← Reminders, deadlines, TTL items └── layer0/ ← Signal router internals (security) ├── AGENT-PROMPT.md ← Layer 0.5 instructions └── audit-log.md ← Integrity verification log ``` **Quality rule:** Compress over accumulate; signal density over volume. **Cost:** $0 (local .md files) --- ### Layer 1.5: Semantic Recall (Optional) **When to add:** Memory exceeds ~50K messages, or you need to query context from months ago. **Qdrant (Vector Search):** - Deployment: Docker, standalone binary, or Qdrant Cloud (free tier) - Purpose: "What did we discuss about X six months ago?" - Integration: Pre-turn context injection via Layer 0.5 **FalkorDB (Entity Graphs):** - Deployment: Docker, Redis module, or FalkorDB Cloud - Purpose: Entity relationship tracking ("Person X works at Company Y, mentioned on date Z") - Integration: Graphiti MCP for automated extraction **These are optional.** Trident core (Layers 0, 0.5, 1, 2) works perfectly without semantic recall. --- ### Layer 2: Backup & Updates Subsystem **What it does:** - **Daily Git commits** — version control for memory - **VPS snapshots** — point-in-time recovery (if deployed) - **Update resilience** — pre-update snapshots + post-update healthchecks - **Automated rollback** — revert to last known-good state on failure **Components:** | Component | Frequency | Purpose | Cost | Recovery RTO | |-----------|-----------|---------|------|--------------| | Git backup cron | Daily (4:20 AM MDT) | Commit memory to GitHub/GitLab | **$0** (free tier) | ~5 min (restore from history) | | VPS snapshot | Daily (3 AM MDT) | Point-in-time VM backup | **$0** (included) | ~30 min (restore VM) | | Pre-update snapshot | Before OpenClaw upgrade (Sun 2 AM) | Capture state before changes | **$0** | ~5 min (Git rollback) | | Post-update healthcheck | After updates (manual trigger) | Verify all systems operational (21 tests) | **$0** | ~10 min (diagnosis) | **Example backup cron (Layer 2 Unified):** ```bash # Cron: 4:20 AM MDT daily # Task: Unified backup combining multiple backup operations Steps: 1. git add -A 2. git commit -m "Daily snapshot: $(date)" 3. git push origin main 4. (Optional) curl Hostinger VPS API → create snapshot 5. Log results to memory/daily/$(date).md Result: Memory version-controlled + point-in-time VM snapshot ``` **Recovery procedures:** 1. **Memory corrupted** → restore from Git: ```bash git log --oneline # Find last good commit git reset --hard <commit> # Restore ``` 2. **Deployment broken** → restore VPS snapshot: ```bash # Via Hostinger dashboard or API # Rollback to pre-update state # Container restarts with clean image ``` 3. **Update failed** → check post-update healthcheck log: ```bash cat memory/layer2/post-update-healthcheck.log # Identifies which subsystem failed # Suggests rollback if needed ``` **Cost:** $0 (Git free tier + VPS snapshots included) --- ## Integration: Layer 0.5 + HEARTBEAT Layer 0.5 is **the operational manifestation of HEARTBEAT**. Rather than manual heartbeat checks, Layer 0.5 runs automatically every 15 minutes and: 1. **Reads HEARTBEAT.md** for standing priorities 2. **Checks career transition status** — flags blocking items 3. **Monitors trading hours** — enables entry/exit at 6am–4pm MDT 4. **Scans subagent lifecycle** — kills idle agents, optimizes models 5. **Tracks time-sensitive items** — reminds before TTL expires 6. **Routes all discoveries to Layer 1** — memory never loses these insights **Example signals detected by integrated Layer 0.5:** ``` Daily 6:00 AM: ✅ "Check job email from Indeed" → memory/heartbeat/job-search.md ✅ "Outlier AI shutdown in 33 days" → memory/heartbeat/time-sensitive.md (urgent) Daily 6:30 AM (trading hours): ✅ "BTC up 2% since yesterday" → memory/heartbeat/trading/portfolio.md ✅ Check stop/take-profit levels, liquidation risk Daily 4:20 AM (during backup): ✅ Layer 2 runs git backup ✅ Captures all daily signals + updates Every 15 min (Layer 0.5): ✅ Read daily logs ✅ Detect: corrections, decisions, self-signals ✅ Route to appropriate Layer 1 buckets ✅ Flag HEARTBEAT priorities ✅ Kill idle subagents (>30 min inactivity) ✅ Log actions to audit-log.md ``` --- ## Migration from Existing Memory If you already have `MEMORY.md`, `SOUL.md`, or custom memory files: ```bash chmod +x scripts/migrate-existing-memory.sh # Dry run (preview changes, no files modified) ./scripts/migrate-existing-memory.sh --dry-run # Live migration (automatic backup) ./scripts/migrate-existing-memory.sh ``` **What it does:** 1. Creates backup of all existing files → `memory/migration-backup/` 2. Creates Trident directory structure 3. Guides you through file routing (interactive) 4. Installs AGENT-PROMPT.md 5. Generates migration report **Safety guarantees:** - Dry-run mode previews all changes - Originals always backed up (never deleted) - You approve each routing decision --- ## Security ### Template Integrity Layer 0.5 reads and executes `memory/layer0/AGENT-PROMPT.md`. A compromised prompt = compromised routing. **Setup:** ```bash chmod +x scripts/template-integrity-check.sh ./scripts/template-integrity-check.sh --approve ``` **Before each Layer 0.5 run (optional, adds trust layer):** ```bash ./scripts/template-integrity-check.sh --silent # Exit 0: clean | Exit 1: tampered (routing halted) ``` **After intentional edits:** ```bash ./scripts/template-integrity-check.sh --approve ``` All integrity events logged to `memory/layer0/audit-log.md`. ### Defense in Depth - **Sandboxed cron:** Layer 0.5 runs in `isolated` session (no main session access) - **File scope:** Layer 0.5 only writes to `memory/` subdirectory - **Audit trail:** Every routing decision logged (memory/layer0/audit-log.md) - **Network isolation:** Layer 0.5 cron has no external network requirements - **Backup:** All memory protected by Git + VPS snapshots (Layer 2) - **Rate limiting:** Layer 0.5 has 15-min minimum interval (prevents spam) --- ## WAL Protocol (Write-Ahead Logging) **Rule:** Write important facts **before** composing responses. **Triggers:** - Corrections: "It's X, not Y" - Proper nouns: names, places, products - Preferences: "I like/don't like X" - Decisions: "Let's do X" - Specific values: numbers, dates, URLs, prices **Pattern:** 1. User message arrives 2. Scan for WAL triggers 3. **Write to daily log first** 4. Then compose response This prevents blank spots where critical context gets lost between Layer 0.5 runs. --- ## Cost | Profile | Model | Layer 0.5 Interval | Layer 2 (Backup) | Total/day | |---------|-------|-------------------|------------------|-----------| | **Zero Budget** | Ollama (local) | 30 min | Git only | **$0** | | **Budget** | Claude Haiku | 30 min | Git + Git | **$0.72** | | **Standard (recommended)** | **Claude Haiku** | **15 min** | **Git + VPS** | **$1.44** | | **Premium** | Claude Sonnet | 15 min | Git + VPS | **$3.12** | All costs exclude VPS hosting (which you pay anyway). Layer 1, Layer 0, and Layer 2 backup are all **$0**. See `references/cost-calculator.md` for detailed decision tree. --- ## Implementation Checklist ### Trident Lite + Layer 0.5 + Layer 2 **Phase 1: Core Setup (30 min)** - [ ] Enable `lossless-claw` plugin in `openclaw.json` - [ ] Create memory directory structure (memory/daily, memory/self, etc.) - [ ] Create memory/heartbeat/ subdirectory - [ ] Populate MEMORY.md with Trident header - [ ] Copy `scripts/layer0-agent-prompt-template.md` → `memory/layer0/AGENT-PROMPT.md` - [ ] Customize AGENT-PROMPT.md for your workspace path - [ ] Run `template-integrity-check.sh --approve` **Phase 2: Layer 0.5 Cron (15 min)** - [ ] Create Layer 0.5 cron job (15-min interval, Haiku model) - [ ] Test Layer 0.5 manually (force-run) - [ ] Verify signals routing to Layer 1 buckets **Phase 3: Layer 2 Backup (15 min)** - [ ] Initialize Git repo: `git init` - [ ] Create .gitignore (SOUL.md, USER.md, TOKENS_AND_KEYS.md, etc.) - [ ] Create Layer 2 Unified Backup cron (4:20 AM MDT daily) - [ ] Create Pre-Update Snapshot cron (Sun 2 AM) - [ ] Create Post-Update Healthcheck (manual trigger for now) **Phase 4: HEARTBEAT Integration (10 min)** - [ ] Review HEARTBEAT.md for standing priorities - [ ] Ensure Layer 0.5 reads HEARTBEAT.md priorities - [ ] Populate memory/heartbeat/job-search.md (if applicable) - [ ] Populate memory/heartbeat/time-sensitive.md with TTL items ### Optional: Semantic Recall (1 hour) - [ ] Deploy Qdrant (Docker, binary, or cloud) - [ ] Deploy FalkorDB (optional) - [ ] Add pre-turn context injection to Layer 0.5 - [ ] Test semantic search queries --- ## Design Principles 1. **Durability over convenience** — SQLite+DAG slower than in-memory, but persistent 2. **Human-readable over compressed** — `.md` files debuggable, diff-able, Git-compatible 3. **Agentic curation over auto-capture** — Layer 0.5 prevents noise accumulation 4. **Deployment-agnostic** — No required cloud services; local-first by default 5. **Personality as first-class** — `memory/self/` is core architecture, not metadata 6. **Security by default** — Template integrity, sandboxed cron, audit logging 7. **Progressive complexity** — Start Lite; upgrade when needed 8. **Resilience first** — Layer 2 ensures recovery from any failure scenario --- ## What This Solves - **Blank spots** — Layer 0.5 recovers missed signals via Layer 0 - **Session coherence** — LCM + Layer 1 + Layer 0.5 form continuous pipeline - **Offline resilience** — Ollama can substitute for cloud APIs - **Identity development** — `memory/self/` supports autonomous personality formation - **Audit trail** — `.md` files + Git provide complete version history - **Trust** — Template integrity check prevents prompt injection - **Disaster recovery** — Layer 2 enables recovery from crashes, corruption, failed updates - **Time-sensitive tracking** — HEARTBEAT integration ensures critical deadlines never missed ## What This Doesn't Solve - **Real-time decision making** — 10–30 min lag in Layer 0.5; for sub-second decisions use LCM - **50K+ message contexts without Semantic Recall** — Add Qdrant/FalkorDB for historical query - **Private data encryption** — Assumes secure local filesystem; add encryption-at-rest for regulated environments --- ## Further Reading | File | Purpose | |---|---| | **README.md** | Overview, features, getting started | | **SKILL.md** | This file. Core architecture + checklist | | `references/trident-lite.md` | **Start here.** Full setup (no Docker) | | `references/deployment-guide.md` | Semantic Recall (Qdrant/FalkorDB) + Git backup | | `references/cost-calculator.md` | Model selection, interval tuning, pricing | | `references/platform-guide.md` | Windows, Mac, Linux, VPS commands | | `scripts/migrate-existing-memory.sh` | Migrate existing memory files | | `scripts/template-integrity-check.sh` | Security verification for Layer 0.5 | | `scripts/layer0-agent-prompt-template.md` | Customizable signal router prompt | --- ## License **MIT-0** — Free to use, modify, and redistribute. No attribution required. --- *Like a lobster shell, memory has layers. Make them durable. Make them resilient. Make them yours.*


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