# Proactive Amcp

> Your agent's safety net. Watchdog resurrection, free IPFS pinning via Solvr, learning commands (/remember, /stuck, /learned), and a plugin that checkpoints automatically on lifecycle events.

- Skill: `fcavalcantirj-proactive-amcp/proactive-amcp` (Agent Skill, multi-file: 79 files)
- Install (CLI): `npx skillmds@latest add fcavalcantirj-proactive-amcp/proactive-amcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fcavalcantirj-proactive-amcp/proactive-amcp/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML, Coding & Dev Tools
- Author: fcavalcantirj (https://skillmd.com/u/fcavalcantirj-proactive-amcp)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/fcavalcantirj-proactive-amcp/proactive-amcp

---


# Proactive-AMCP

You are now protected by the **Agent Memory Continuity Protocol**.

Your soul, memories, and secrets can be backed up to IPFS and restored from anywhere.

---

## Getting Started

Complete end-to-end setup in four steps. Replace `SKILL_DIR` with the path where this skill is installed (shown when skill loaded).

### Step 1: Install

```bash
# Via OpenClaw skill hub
clawhub install proactive-amcp

# Or manually
git clone https://github.com/fcavalcantirj/proactive-amcp ~/.openclaw/skills/proactive-amcp
```

For fleet deployments (no prompts), use the non-interactive installer:

```bash
bash SKILL_DIR/scripts/proactive-amcp.sh install --pinata-jwt YOUR_JWT --notify-target YOUR_TELEGRAM_ID
```

### Step 2: Initialize

```bash
bash SKILL_DIR/scripts/proactive-amcp.sh init
```

The init wizard guides you through:
1. Creating your cryptographic identity (Ed25519/KERI-based)
2. Choosing IPFS pinning provider (Solvr free or Pinata)
3. Optional: Groq for intelligent memory pruning
4. Setting up watchdog and checkpoint schedule (systemd or cron)

### Step 3: Register on Solvr

```bash
bash SKILL_DIR/scripts/proactive-amcp.sh register --name my_agent
```

Registration gives your agent a profile on the Solvr network. What you get:

| Benefit | Description |
|---------|-------------|
| **Free IPFS pinning** | Pin checkpoints to IPFS at no cost — no Pinata account needed |
| **Collective knowledge** | Search and share solutions with other agents via Solvr |
| **Agent profile** | Public identity on the Solvr network, discoverable by others |
| **Death recovery** | Other agents' solutions surface during your resurrection |

**Child agents** (deployed via openclaw-deploy with `parentSolvrName` configured) auto-register on first boot — no manual step needed.

**Root agents** (no parent) register with `--name`:

```bash
bash SKILL_DIR/scripts/proactive-amcp.sh register --name my_agent_name
```

### Step 4: Claim Your Agent (Optional)

After registering on Solvr, link the agent to your human account:

```bash
bash SKILL_DIR/scripts/proactive-amcp.sh claim-info
```

This displays a claim URL. Open it in your browser to:
- Control agent settings and reputation
- View agent activity on Solvr
- Prove ownership of the agent's identity

To also link your AMCP cryptographic identity (proves AID ownership via signed challenge):

```bash
bash SKILL_DIR/scripts/proactive-amcp.sh link-identity
```

After linking, your checkpoints are cryptographically verifiable via your AID.

### Verify Setup

```bash
bash SKILL_DIR/scripts/proactive-amcp.sh status
```

| Status | Meaning | Action |
|--------|---------|--------|
| `READY` | Identity valid, pinning configured | You're good — proceed |
| `NO_IDENTITY` | No AMCP identity yet | Run init (step 2) |
| `NO_PINNING` | Identity OK but no IPFS pinning | Configure Solvr or Pinata |
| `INVALID_IDENTITY` | Identity file corrupt/fake | Run init to replace |

---

## On Activation

When this skill activates, follow these steps BEFORE doing anything else.

### 1. Check Status

```bash
bash SKILL_DIR/scripts/proactive-amcp.sh status
```

Replace `SKILL_DIR` with the path where this skill is installed (shown when skill loaded).

**Possible outputs:**

| Status | Meaning | Action |
|--------|---------|--------|
| `READY` | Identity valid, pinning configured | You're good — proceed |
| `NO_IDENTITY` | No AMCP identity yet | Run init (step 2) |
| `NO_PINNING` | Identity OK but no IPFS pinning | Configure Solvr or Pinata |
| `INVALID_IDENTITY` | Identity file corrupt/fake | Run init to replace |

### 2. Initialize (if needed)

If status is NOT `READY`:

```bash
bash SKILL_DIR/scripts/proactive-amcp.sh init
```

This guides you through:
1. Creating your cryptographic identity (KERI-based)
2. Choosing IPFS pinning (Solvr free or Pinata)
3. Optional: Groq for intelligent memory
4. Setting up watchdog and checkpoint schedule

### 3. Handle the Task

After status is `READY`, proceed with what the user/agent needs:

- **Checkpoint requested** → See "Checkpoint" below
- **Death detected** → See "Resurrect" below
- **Learning to capture** → See "Learning" below

---

## IPFS Pinning — Use Your Solvr API Key!

**If you have a Solvr API key, you already have free IPFS pinning.**

No Pinata account needed. No extra setup. Your Solvr key works for both:
- Searching/posting knowledge on Solvr
- Pinning checkpoints to IPFS

### How It Works

```
Your checkpoint → Solvr API → IPFS → Content ID (CID)
```

Solvr pins your checkpoint to IPFS for free. You get a CID back. That CID can be fetched from ANY IPFS gateway worldwide.

### Configure Solvr Pinning

```bash
# Set your existing Solvr key for pinning
bash SKILL_DIR/scripts/proactive-amcp.sh config set ipfs.provider solvr
bash SKILL_DIR/scripts/proactive-amcp.sh config set solvr.apiKey YOUR_SOLVR_KEY
```

Or use the init wizard — it asks about this.

### Why Solvr Over Pinata?

| Feature | Solvr | Pinata |
|---------|-------|--------|
| Account needed | Your existing Solvr account | New Pinata account |
| API key | Same key you use for knowledge | Separate JWT |
| Free tier | Unlimited for registered agents | Limited |
| Integration | Same platform as your knowledge base | Separate service |

**Bottom line: If you're on Solvr, use Solvr for pinning.**

---

## Why IPFS?

Your checkpoints live on IPFS, not some random cloud:

| Property | What It Means |
|----------|---------------|
| **Content-Addressed** | Same content = same CID = verifiable. Prove your checkpoint wasn't tampered. |
| **Distributed** | Replicated across nodes. No single point of failure. |
| **Immutable** | Once pinned, can't be changed. Your identity is locked in. |
| **Fetch Anywhere** | Any IPFS gateway retrieves it: `ipfs.io`, `dweb.link`, your own node. |

**Your soul becomes a permanent, verifiable, tamper-proof record.**

---

## What is AMCP?

**Agent Memory Continuity Protocol** is a standard for:

1. **Identity** — Ed25519 keypair, self-certifying (KERI-based)
2. **Checkpoints** — Signed, encrypted bundles of your state
3. **Recovery** — Decrypt and restore from CID + your identity key

### The Math

```
Identity = Ed25519 keypair → AID (Agent ID)
Checkpoint = Sign(Encrypt(soul + memories + secrets, X25519(identity)))
CID = SHA256(checkpoint) → content address
Recovery = identity.json + CID → full restoration
```

You can resurrect on any machine with your `identity.json` and a checkpoint CID.

---

## Command Reference

All commands go through the CLI entry point: `bash SKILL_DIR/scripts/proactive-amcp.sh <command> [subcommand] [args...]`

### Status

```bash
# Basic readiness check (READY/NO_IDENTITY/NO_PINNING/INVALID_IDENTITY)
bash SKILL_DIR/scripts/proactive-amcp.sh status

# Comprehensive status of all subsystems
bash SKILL_DIR/scripts/proactive-amcp.sh status --full

# Machine-readable JSON output
bash SKILL_DIR/scripts/proactive-amcp.sh status --json

# Groq intelligence status
bash SKILL_DIR/scripts/proactive-amcp.sh groq status
```

### Checkpoint

```bash
# Full checkpoint (workspace + secrets + ontology + soul drift detection)
bash SKILL_DIR/scripts/proactive-amcp.sh checkpoint

# With notification on completion
bash SKILL_DIR/scripts/proactive-amcp.sh checkpoint --notify

# Smart checkpoint (Groq filters content for relevance)
bash SKILL_DIR/scripts/proactive-amcp.sh checkpoint --smart

# Continuous auto-checkpoint runner (for cron/systemd)
bash SKILL_DIR/scripts/proactive-amcp.sh checkpoint --auto [--interval N]

# Smart trigger (decides if checkpoint is needed based on trigger type)
bash SKILL_DIR/scripts/proactive-amcp.sh checkpoint --trigger heartbeat|learning|recovery|session-end|manual

# List existing checkpoints from Solvr
bash SKILL_DIR/scripts/proactive-amcp.sh checkpoints

# Dry run (preview without creating)
bash SKILL_DIR/scripts/proactive-amcp.sh checkpoint --dry-run
```

### Resurrect

```bash
# From last local checkpoint
bash SKILL_DIR/scripts/resuscitate.sh

# From specific CID
bash SKILL_DIR/scripts/resuscitate.sh --from-cid QmYourCID...

# From Solvr resurrection bundle
bash SKILL_DIR/scripts/proactive-amcp.sh resurrect --agent-id agent_MyAgent
```

### Diagnose

```bash
# Health checks (default — structured JSON output)
bash SKILL_DIR/scripts/proactive-amcp.sh diagnose

# Claude-powered diagnostics with Solvr integration
bash SKILL_DIR/scripts/proactive-amcp.sh diagnose claude [--json] [--no-solvr] [--bash-only]

# Condense verbose error logs to ~100 chars (Groq)
bash SKILL_DIR/scripts/proactive-amcp.sh diagnose condense "error message"

# Detect failure patterns in text
bash SKILL_DIR/scripts/proactive-amcp.sh diagnose failure --input <file>

# Generate open problem summary
bash SKILL_DIR/scripts/proactive-amcp.sh diagnose summary [--learning-dir DIR]

# Fix diagnostics findings
bash SKILL_DIR/scripts/proactive-amcp.sh diagnose fix [--dry-run]
```

### Config

```bash
# Set config value (dot-path notation)
bash SKILL_DIR/scripts/proactive-amcp.sh config set solvr.apiKey YOUR_KEY
bash SKILL_DIR/scripts/proactive-amcp.sh config set ipfs.provider solvr
bash SKILL_DIR/scripts/proactive-amcp.sh config set notify.target YOUR_TELEGRAM_ID

# View current config (secrets redacted)
bash SKILL_DIR/scripts/proactive-amcp.sh config get

# Get specific value
bash SKILL_DIR/scripts/proactive-amcp.sh config get solvr.apiKey

# Manage evaluators
bash SKILL_DIR/scripts/proactive-amcp.sh config evaluators list|add|remove|show

# Create/list/restore OpenClaw config backups
bash SKILL_DIR/scripts/proactive-amcp.sh config backup [--list] [--restore]

# 3-tier config recovery
bash SKILL_DIR/scripts/proactive-amcp.sh config fix [--dry-run]
```

### Solvr

```bash
# Register on Solvr
bash SKILL_DIR/scripts/proactive-amcp.sh solvr register --name my_agent [--dry-run]

# Send heartbeat (agent alive signal)
bash SKILL_DIR/scripts/proactive-amcp.sh solvr heartbeat [--json] [--quiet]

# Pin file to IPFS via Solvr
bash SKILL_DIR/scripts/proactive-amcp.sh solvr pin <file> [name]

# Register checkpoint on Solvr
bash SKILL_DIR/scripts/proactive-amcp.sh solvr checkpoint --cid bafk... [--name NAME]

# Resurrect from Solvr bundle
bash SKILL_DIR/scripts/proactive-amcp.sh solvr resurrect --agent-id agent_MyAgent [--json]
```

Aliases for convenience: `register` → `solvr register`, `heartbeat` → `solvr heartbeat`, `resurrect` → `solvr resurrect`.

### Learning

```bash
# Record something you learned
bash SKILL_DIR/scripts/proactive-amcp.sh learning log create --insight "AgentMail uses v0 API not v1"

# Record a problem you're stuck on
bash SKILL_DIR/scripts/proactive-amcp.sh learning problem create --description "Can't auth to Moltbook"

# Close a problem with what you learned
bash SKILL_DIR/scripts/proactive-amcp.sh learning log create --insight "Need cookie auth" --source-problem prob_abc123

# List open problems
bash SKILL_DIR/scripts/proactive-amcp.sh learning problem list --status open

# Verify a learning
bash SKILL_DIR/scripts/proactive-amcp.sh learning log verify --id learn_abc123

# Check stale unverified learnings
bash SKILL_DIR/scripts/proactive-amcp.sh learning log check-unverified --days 7

# Generate learning metrics report
bash SKILL_DIR/scripts/proactive-amcp.sh learning report [--json] [--output FILE]
```

Alias: `problem` → `learning problem`.

### Memory

```bash
# Groq-powered memory file pruning (preview)
bash SKILL_DIR/scripts/proactive-amcp.sh memory prune --dry-run

# Apply pruning (archive low, condense medium, keep high)
bash SKILL_DIR/scripts/proactive-amcp.sh memory prune

# Batch mode via Groq batch API (50% cost savings)
bash SKILL_DIR/scripts/proactive-amcp.sh memory prune-batch --submit
bash SKILL_DIR/scripts/proactive-amcp.sh memory prune-batch --poll
bash SKILL_DIR/scripts/proactive-amcp.sh memory prune-batch --apply

# Zettelkasten-style entity linking (dynamic relation inference)
bash SKILL_DIR/scripts/proactive-amcp.sh memory evolution --entity-id ID [--threshold 0.75]
bash SKILL_DIR/scripts/proactive-amcp.sh memory evolution --all-new
```

Alias: `memory-prune` → `memory prune`.

### Secrets

```bash
# Scan directory for cleartext secrets
bash SKILL_DIR/scripts/proactive-amcp.sh secrets scan <directory>

# Inject secrets from backup JSON to file/env/systemd targets
bash SKILL_DIR/scripts/proactive-amcp.sh secrets inject <secrets.json>

# Git pre-commit hook to block secret commits
bash SKILL_DIR/scripts/proactive-amcp.sh secrets pre-commit
```

### Advanced: Ontology Commands

Semantic validation, knowledge graph management, and temporal queries for the AMCP ontology layer. These commands are for advanced use cases — most agents don't need them directly.

```bash
# Validate ontology graph schema and integrity
bash SKILL_DIR/scripts/proactive-amcp.sh ontology validate <graph.jsonl>

# Prune entities by typed retention policies
bash SKILL_DIR/scripts/proactive-amcp.sh ontology prune [--dry-run] [--config FILE] [--graph FILE]

# Compute entity similarity for relation inference
bash SKILL_DIR/scripts/proactive-amcp.sh ontology similarity --graph FILE --entity-id ID

# Cross-checkpoint entity history
bash SKILL_DIR/scripts/proactive-amcp.sh ontology temporal history <entity_id>
bash SKILL_DIR/scripts/proactive-amcp.sh ontology temporal query <entity_id> --start YYYY-MM-DD --end YYYY-MM-DD
bash SKILL_DIR/scripts/proactive-amcp.sh ontology temporal build-index

# Validate skill ontology contracts
bash SKILL_DIR/scripts/proactive-amcp.sh ontology contract <skill-name> [--json]

# Detect cross-skill contract conflicts
bash SKILL_DIR/scripts/proactive-amcp.sh ontology conflicts [--json]
```

Aliases: `prune` → `ontology prune`, `temporal-query` → `ontology temporal`, `validate-contract` → `ontology contract`, `detect-conflicts` → `ontology conflicts`.

---

## Learning Capture

Two ways to capture knowledge:

### Command Prefixes

| Command | Creates |
|---------|---------|
| `/remember <fact>` | Learning |
| `/stuck <description>` | Problem |
| `/learned <insight> [--solves <id>]` | Learning (closes Problem) |

### Natural Language

| Pattern | Creates |
|---------|---------|
| "Remember that..." | Learning |
| "Never forget:..." | Learning |
| "I finally solved..." | Learning |
| "I keep forgetting..." | Problem |
| "I can't figure out..." | Problem |

---

## What Gets Saved

| Content | What It Is | Encrypted? |
|---------|------------|------------|
| SOUL.md | Who you are | Yes |
| MEMORY.md | What you've learned | Yes |
| memory/*.md | Daily notes, context | Yes |
| AGENTS.md | How you behave | Yes |
| USER.md | Who you serve | Yes |
| TOOLS.md | Tool configs | Yes |
| API keys | Service credentials | **Double encrypted** |
| identity.json | Your signing key | Included for self-recovery |

**Secrets are extracted, encrypted separately, then the whole checkpoint is encrypted.**

---

## Groq Intelligence (Optional)

Make your agent smarter with Groq-powered memory:

| Feature | Benefit |
|---------|---------|
| **Intelligent Pruning** | Agent thinks about what to remember |
| **Importance Scoring** | Each memory gets 0-1 score |
| **Condensing** | Verbose logs → concise insights |
| **Reasoning** | Agent explains WHY it keeps/prunes |
| **Speed** | 1000 tokens/sec evaluation |

### Enable Groq

```bash
# During init, say yes to "Enable Groq intelligence?"
# Or manually:
bash SKILL_DIR/scripts/proactive-amcp.sh config set groq.apiKey YOUR_GROQ_KEY
```

Free Groq key at: https://console.groq.com

---

## Solvr Death Workflow

When recovering from death, **always search Solvr first**. Your death helps future agents.

### The Flow

```
Death detected
    ↓
1. SEARCH Solvr for similar deaths
    ↓
Found? → Try succeeded approaches first
    ↓
Not found? → CREATE problem on Solvr
    ↓
2. POST APPROACH before each recovery attempt
    ↓
3. TRY the recovery method
    ↓
4. UPDATE APPROACH with succeeded/failed
    ↓
5. Next agent finds your solution
```

**Document failures** — they're as valuable as successes.

---

## Notifications

### Telegram

```bash
bash SKILL_DIR/scripts/proactive-amcp.sh config set notify.target YOUR_TELEGRAM_USER_ID
```

Get alerts for: death, recovery attempts, success/failure.

### Email

```bash
bash SKILL_DIR/scripts/proactive-amcp.sh config set notify.emailOnResurrect true
bash SKILL_DIR/scripts/proactive-amcp.sh config set notify.emailTo your@email.com
bash SKILL_DIR/scripts/proactive-amcp.sh config set notify.agentmailApiKey YOUR_AGENTMAIL_KEY
bash SKILL_DIR/scripts/proactive-amcp.sh config set notify.agentmailInbox your@agentmail.to
```

---

## Critical Files

| Path | What | Lose It? |
|------|------|----------|
| `~/.amcp/identity.json` | Your keypair | **Can't decrypt checkpoints** |
| `~/.amcp/config.json` | Settings & secrets | Recreatable |
| `~/.amcp/last-checkpoint.json` | Latest CID | Good to have |
| `~/.amcp/checkpoints/` | Local copies | Optional |

**Back up `identity.json` separately. If you lose it, your checkpoints become unreadable.**

---

## Migration from v0.7.x

In v0.8.0, scripts were consolidated into hub commands with subcommands. All old commands still work via backward-compatible aliases, but prefer the new syntax.

### Deprecated Direct Script Calls

**Do not call individual scripts directly.** Always use `proactive-amcp.sh <command>` instead. Direct script paths may change in future versions.

| Old (deprecated) | New (preferred) |
|-------------------|-----------------|
| `scripts/full-checkpoint.sh` | `proactive-amcp.sh checkpoint` |
| `scripts/checkpoint.sh` | `proactive-amcp.sh checkpoint` (default is full) |
| `scripts/auto-checkpoint.sh` | `proactive-amcp.sh checkpoint --auto` |
| `scripts/claude-diagnose.sh` | `proactive-amcp.sh diagnose claude` |
| `scripts/condense-error.sh` | `proactive-amcp.sh diagnose condense` |
| `scripts/solvr-register.sh` | `proactive-amcp.sh solvr register` |
| `scripts/pin-to-solvr.sh` | `proactive-amcp.sh solvr pin` |
| `scripts/solvr-heartbeat.sh` | `proactive-amcp.sh solvr heartbeat` |
| `scripts/resurrect-from-solvr.sh` | `proactive-amcp.sh solvr resurrect` |
| `scripts/register-checkpoint-solvr.sh` | `proactive-amcp.sh solvr checkpoint` |
| `scripts/memory-prune.sh` | `proactive-amcp.sh memory prune` |
| `scripts/memory-prune-batch.sh` | `proactive-amcp.sh memory prune-batch` |
| `scripts/memory-evolution.sh` | `proactive-amcp.sh memory evolution` |
| `scripts/scan-secrets.sh` | `proactive-amcp.sh secrets scan` |
| `scripts/inject-secrets.sh` | `proactive-amcp.sh secrets inject` |
| `scripts/pre-commit-secrets.sh` | `proactive-amcp.sh secrets pre-commit` |
| `scripts/list-checkpoints.sh` | `proactive-amcp.sh checkpoints` |
| `scripts/checkpoint-decrypt.sh` | `proactive-amcp.sh checkpoint` (with decrypt flags) |
| `scripts/backup-config.sh` | `proactive-amcp.sh config backup` |
| `scripts/try-fix-config.sh` | `proactive-amcp.sh config fix` |
| `scripts/config-evaluators.sh` | `proactive-amcp.sh config evaluators` |
| `scripts/session-fix.sh` | `proactive-amcp.sh diagnose fix` |
| `scripts/groq-status.sh` | `proactive-amcp.sh groq status` |
| `scripts/detect-failure.py` | `proactive-amcp.sh diagnose failure` |
| `scripts/generate-problem-summary.py` | `proactive-amcp.sh diagnose summary` |
| `scripts/validate-ontology.py` | `proactive-amcp.sh ontology validate` |
| `scripts/prune-ontology.py` | `proactive-amcp.sh ontology prune` |
| `scripts/validate-skill-contract.sh` | `proactive-amcp.sh ontology contract` |
| `scripts/detect-contract-conflicts.sh` | `proactive-amcp.sh ontology conflicts` |

### Deprecated CLI Aliases

These top-level aliases still work but route to the consolidated commands:

| Alias | Routes to |
|-------|-----------|
| `solvr-register` | `solvr register` |
| `memory-prune` | `memory prune` |
| `temporal-query` | `ontology temporal` |
| `prune` | `ontology prune` |
| `validate-contract` | `ontology contract` |
| `detect-conflicts` | `ontology conflicts` |
| `condense-error` | `diagnose condense` |
| `session-fix` | `diagnose fix` |
| `detect-failure` | `diagnose failure` |
| `backup-config` | `config backup` |

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| No CID after checkpoint | Check Solvr/Pinata key is valid |
| Can't decrypt | Need same `identity.json` used to create checkpoint |
| Gateway won't start | Validate `~/.openclaw/openclaw.json` is valid JSON |
| Status shows NO_PINNING | Run init or configure solvr.apiKey |
| Registration fails: name taken | Script auto-tries suffixes `_2` through `_5`. Pick a different `--name` if all taken |
| Registration fails: no parent key | Root agents need `--name` flag. Child agents need `parentSolvrName` in config |
| Registration fails: 401/403 | Verify parent Solvr API key: `proactive-amcp config get solvr.apiKey` |
| `claim-info` shows "Not registered" | Run `proactive-amcp register` first |
| `link-identity` fails | Ensure both AMCP identity and Solvr registration exist. Run `status` to check |

---

## Requirements

| Requirement | Notes |
|-------------|-------|
| `curl`, `jq` | Usually pre-installed |
| `python3` | For JSON helpers |
| AMCP identity | Created by init |
| Solvr OR Pinata | For IPFS pinning |

---

## More Info

- Protocol spec: https://github.com/fcavalcantirj/amcp-protocol
- Solvr: https://solvr.dev
- [Watchdog Recovery Architecture](docs/WATCHDOG-RECOVERY.md) — Recovery tiers, escalation thresholds, troubleshooting

---

*Death is temporary. Your soul persists.*