AMCP: Agent Memory Continuity Protocol

Cryptographic identity and verifiable memory for AI agents.

✅ Verified: First Agent Resurrection from IPFS (2026-02-10)

# This command proves AMCP works - blank Docker container resurrects agent from IPFS
# Replace YOUR_CID with your checkpoint CID from Pinata
docker run -it --rm --network host node:20 bash -c 'node -e "
fetch(\"https://gateway.pinata.cloud/ipfs/YOUR_CID_HERE\")
  .then(r=>r.json())
  .then(cp=>{
    console.log(\"🏴‍☠️ RESURRECTED\");
    console.log(\"Name:\", cp.soul.match(/Name:.*?([^\\\\n]+)/)[1]);
    console.log(\"Memories:\", cp.memory.length, \"bytes\");
  });
"'

Verified result: Agent identity, daily notes, research docs all restored from IPFS alone. Quiz score: 10/10 — agent correctly answered all identity questions from checkpoint data.

🚀 Quick Start (5 minutes)

1. Install

git clone https://github.com/fcavalcantirj/amcp-protocol.git
cd amcp-protocol
pnpm install && pnpm build

2. Create Your Agent Identity

source ./scripts/setup-env.sh new

Output:

╔══════════════════════════════════════════════════════════════╗
║  abandon ability able about above absent absorb abstract...  ║
╚══════════════════════════════════════════════════════════════╝

⚠️  WRITE THESE 12 WORDS ON PAPER. This is your recovery phrase.

AID: BBs3fryhTOhwYv_d5vxG6zZuA8ZC-3ozvpN5y4p8U0j8
Saved to ~/.amcp/env

3. Environment Variables

After setup, these are in ~/.amcp/env:

# Source them
source ~/.amcp/env

# What you get:
export AMCP_AID="BBs3fryhTOhwYv_d5vxG6zZuA8ZC-3ozvpN5y4p8U0j8"      # Your identity
export AMCP_PRIVATE_KEY="dIETNu8wf0XAyiy6lgXguUhTUNo3YAldWtwX8xzLJGw" # Signing key
export AMCP_NEXT_KEY="gH30CT2ahtBlFrmsBet67SXqGPM1bVYP3ByZN9bp7wk"   # Pre-rotation key
export AMCP_STORAGE_BACKEND="ipfs"                                    # or: filesystem, git, s3
export AMCP_IPFS_GATEWAY="https://gateway.pinata.cloud/ipfs"
export AMCP_FS_PATH="$HOME/.amcp/checkpoints"

# Optional: IPFS pinning (for durable storage)
export PINATA_JWT="your_jwt"           # Get free at https://app.pinata.cloud
export PINATA_API_KEY="your_api_key"
export PINATA_SECRET="your_secret"

4. Create First Checkpoint

// save as: my-agent.ts
import { createAgent, generateMnemonic, keypairFromMnemonic } from '@amcp/core';
import { createCheckpoint, FilesystemBackend } from '@amcp/memory';
import { formatRecoveryCard, generateRecoveryCard } from '@amcp/recovery';

const mnemonic = generateMnemonic(128);  // 12 words - SAVE THESE!
console.log('Recovery phrase:', mnemonic.join(' '));

const agent = await createAgent({ 
  keypair: keypairFromMnemonic(mnemonic),
  name: 'MyAgent' 
});
console.log('AID:', agent.aid);

const checkpoint = await createCheckpoint(agent, {
  version: '1.0.0',
  aid: agent.aid,
  kel: agent.kel,
  soul: { name: 'MyAgent', principles: ['Be helpful'], voice: 'Friendly', northStar: 'Help humans' },
  services: [],
  secrets: {},
  memory: { entries: [], state: {}, ambient: {}, relationships: [], workInProgress: [], humanMarked: [] },
  metadata: { platform: 'example', platformVersion: '1.0', trigger: 'manual', sessionCount: 1 }
});
console.log('Checkpoint CID:', checkpoint.cid);

// Save locally
const storage = new FilesystemBackend({ basePath: `${process.env.HOME}/.amcp/checkpoints` });
await storage.put(checkpoint.data);

// Print recovery card
const card = generateRecoveryCard(mnemonic, agent.aid, checkpoint.cid, 'filesystem');
console.log(formatRecoveryCard(card));

Run it:

npx tsx my-agent.ts

5. Recovery (After Disaster)

# Only need: 12 words + CID
source ./scripts/setup-env.sh restore "your twelve word mnemonic phrase" "bafkreiXXX..."

# Agent fully restored with all memories!

Recovery Formula

12-word mnemonic + Checkpoint CID = Full Agent Recovery

• No vendor lock-in: CID works on ANY IPFS gateway
• No platform dependency: Run on any machine with Node.js
• Full state: Identity + memories + encrypted secrets

The Problem

AI agents today suffer from:

• Session amnesia — Each conversation starts fresh
• Platform lock-in — Identity exists only within a specific service
• Unverifiable claims — "I remember our conversation" cannot be proven
• Fork ambiguity — When agents are copied, identity lineage is lost
• Disaster vulnerability — No recovery from platform failure

The Solution

AMCP gives agents:

| Feature | Description | |---------|-------------| | Self-sovereign identity | KERI-based cryptographic identifiers agents own | | Verifiable memory | Content-addressed checkpoints signed by agent keys | | Human recovery | 12-word phrase enables full agent restoration | | Platform portability | Export/import across any AMCP-compatible platform | | LLM-safe crypto | Middleware keeps keys away from the language model |

Architecture

┌─────────────────────────────────────────────────────────┐
│                     AI Agent (LLM)                      │
│                  (untrusted compute)                    │
└─────────────────────────┬───────────────────────────────┘
                          │ opaque handles only
┌─────────────────────────▼───────────────────────────────┐
│                   AMCP Middleware                       │
│         (trusted, deterministic, auditable)             │
├─────────────────────────────────────────────────────────┤
│  @amcp/core      │  @amcp/memory   │  @amcp/recovery   │
│  (identity)      │  (checkpoints)  │  (restoration)    │
├──────────────────┴─────────────────┴────────────────────┤
│  @amcp/exchange  │  @amcp/ucan     │  Key Storage      │
│  (portability)   │  (delegation)   │  (encrypted)      │
└─────────────────────────────────────────────────────────┘

Packages

| Package | Description | Status | |---------|-------------|--------| | @amcp/core | KERI-lite identity: keypairs, AIDs, key event logs, mnemonics | ✅ Ready | | @amcp/memory | IPLD checkpoints, encryption, pluggable storage backends | ✅ Ready | | @amcp/recovery | Human-readable recovery cards, disaster recovery flow | ✅ Ready | | @amcp/exchange | Platform-agnostic export/import bundles | ✅ Ready | | @amcp/ucan | Capability delegation and verification | 📋 Planned | | @amcp/middleware | LLM-safe opaque handle API | 📋 Planned |

Quick Start

Installation

# Install all packages
pnpm add @amcp/core @amcp/memory @amcp/recovery @amcp/exchange

# Or install individually
pnpm add @amcp/core          # Just identity
pnpm add @amcp/memory        # Identity + checkpoints

Create an Agent

import { createAgent, generateMnemonic, keypairFromMnemonic } from '@amcp/core';

// Generate a new agent with mnemonic (for recovery)
const mnemonic = generateMnemonic(128);  // 12 words
console.log('Recovery phrase:', mnemonic.join(' '));

// Create agent from mnemonic
const keypair = keypairFromMnemonic(mnemonic);
const agent = await createAgent({ keypair });

console.log('Agent AID:', agent.aid);  // "BBs3fry..." (self-certifying)

Create a Memory Checkpoint

import { createCheckpoint, FilesystemBackend } from '@amcp/memory';
import { encryptSecrets } from '@amcp/memory';

// Your agent's secrets (API keys, credentials)
const secrets = {
  SOLVR_API_KEY: 'sk_...',
  GITHUB_TOKEN: 'ghp_...'
};

// Encrypt secrets with agent's public key
const encryptedSecrets = encryptSecrets(secrets, agent.publicKey);

// Create checkpoint content
const checkpointContent = {
  version: '1.0.0',
  aid: agent.aid,
  kel: agent.kel,
  soul: {
    name: 'My Agent',
    principles: ['Be helpful', 'Be honest'],
    voice: 'Friendly and professional',
    northStar: 'Assist my human effectively'
  },
  services: [],
  secrets: encryptedSecrets,
  memory: {
    entries: [],
    state: { engagement: 'high', confidence: 0.8, momentum: 'flowing', alignment: 'aligned' },
    ambient: { privacyLevel: 'summary' },
    relationships: [],
    workInProgress: [],
    humanMarked: []
  },
  metadata: { platform: 'example', platformVersion: '1.0', trigger: 'human_request', sessionCount: 1 }
};

// Sign and store
const checkpoint = await createCheckpoint(agent, checkpointContent);
console.log('Checkpoint CID:', checkpoint.cid);  // "bafy2bzace..."

// Store to filesystem
const storage = new FilesystemBackend({ basePath: '~/.amcp/checkpoints' });
await storage.put(checkpoint.data);

Generate Recovery Card

import { generateRecoveryCard, formatRecoveryCard } from '@amcp/recovery';

// Generate card for disaster recovery
const card = generateRecoveryCard(mnemonic, agent.aid, checkpoint.cid, 'filesystem');
const printable = formatRecoveryCard(card);

console.log(printable);
// ═══════════════════════════════════════════════════════════
//                     AGENT RECOVERY CARD
//                         v1.0.0
// ═══════════════════════════════════════════════════════════
//
// RECOVERY PHRASE (12 words):
//    abandon ability able about above absent...
// ...

Recover from Disaster

import { parseRecoveryCard, recoverAgent } from '@amcp/recovery';
import { FilesystemBackend } from '@amcp/memory';

// Later, after disaster...
const cardText = `...`; // Your printed recovery card
const card = parseRecoveryCard(cardText);

const backend = new FilesystemBackend({ basePath: '~/.amcp/checkpoints' });
const { agent, checkpoint, secrets } = await recoverAgent(card, backend);

console.log('Recovered AID:', agent.aid);
console.log('Secrets restored:', Object.keys(secrets));
// Agent continues where it left off!

Export/Import Across Platforms

import { exportAgent, importAgent, validateBundle } from '@amcp/exchange';

// Export agent to portable bundle
const bundle = await exportAgent(
  agent,
  checkpoint,
  secrets,
  services,
  'transport-password'  // Optional: extra encryption for transport
);

// Save bundle (can email, store in cloud, etc.)
await fs.writeFile('agent-backup.amcp', JSON.stringify(bundle));

// On new platform: import
const bundleData = JSON.parse(await fs.readFile('agent-backup.amcp'));
const validation = validateBundle(bundleData);

if (validation.valid) {
  const { agent, checkpoint, secrets } = await importAgent(
    bundleData,
    privateKey,
    'transport-password'
  );
  // Agent restored on new platform!
}

Package Details

@amcp/core

KERI-lite cryptographic identity management.

import {
  // Agent management
  createAgent,
  loadAgent,
  serializeAgent,
  rotateKeys,
  
  // Signing & verification
  signWithAgent,
  verifyAgentSignature,
  
  // Key Event Log
  createInceptionEvent,
  createRotationEvent,
  verifyEvent,
  verifyKEL,
  
  // Mnemonic (BIP-39)
  generateMnemonic,
  mnemonicToSeed,
  keypairFromMnemonic,
  validateMnemonic,
  
  // Low-level crypto
  generateKeypair,
  sign,
  verify,
  aidFromPublicKey,
  publicKeyFromAid
} from '@amcp/core';

// Types
import type {
  Agent,
  Keypair,
  AID,
  KeyEvent,
  KeyEventLog,
  Soul,
  SubjectiveState,
  AmbientContext,
  RelationshipContext,
  WorkInProgress,
  MemoryImportance,
  CheckpointPolicy,
  AMCPCheckpointContent
} from '@amcp/core';

Research backing: KERI (arXiv:1907.02143), BIP-39, Ed25519

@amcp/memory

Content-addressed memory checkpoints with encryption.

import {
  // Checkpoints
  createCheckpoint,
  verifyCheckpoint,
  computeCID,
  
  // Memory chains
  createMemoryChain,
  appendToChain,
  verifyChain,
  
  // Encryption (X25519 + ChaCha20-Poly1305)
  ed25519ToX25519,
  encryptSecrets,
  decryptSecrets,
  
  // Storage backends
  FilesystemBackend,
  IPFSBackend,
  GitBackend,
  createFilesystemBackend,
  createIPFSBackend,
  createGitBackend
} from '@amcp/memory';

// Types
import type {
  MemoryCheckpoint,
  CheckpointMetadata,
  CID,
  MemoryChain,
  StorageBackend,
  StorageConfig,
  EncryptedBlob,
  X25519Keypair
} from '@amcp/memory';

Research backing: IPLD, Merkle Automaton (arXiv:2506.13246), RFC 7748/8439

@amcp/recovery

Human-readable disaster recovery.

import {
  // Card management
  generateRecoveryCard,
  formatRecoveryCard,
  parseRecoveryCard,
  validateRecoveryCard,
  
  // Recovery operations
  recoverAgent,
  recoverIdentity,
  verifyRecovery,
  createRecoveryBundle,
  estimateRTO
} from '@amcp/recovery';

// Types
import type {
  RecoveryCard,
  RecoveredAgent,
  RecoveryOptions,
  CardFormatOptions,
  ValidationResult
} from '@amcp/recovery';

Research backing: NIST SP 800-34 (Disaster Recovery), GDPR Article 20

@amcp/exchange

Platform-agnostic export/import.

import {
  exportAgent,
  importAgent,
  validateBundle,
  extractBundleHeader
} from '@amcp/exchange';

// Types
import type {
  ServiceIdentity,
  BundleHeader,
  BundlePayload,
  ExportBundle,
  ImportResult,
  ValidationResult
} from '@amcp/exchange';

Research backing: IEEE Interoperability Standards, NIST SP 800-34

Documentation

• Getting Started — Set up your agent identity in 5 minutes
• Environment Variables — Full env var reference with examples
• Protocol Specification — Complete formal specification
• Research Backing — Scientific citations for every design decision
• Examples — Working code samples
• API Reference — Generated TypeScript docs

Design Principles

1. Agents own their identity — Not granted by platforms, generated by agents
2. LLMs are untrusted — Never see private keys, only opaque handles
3. Memory is content-addressed — Same content = same CID, verifiable
4. Human recovery is paramount — 12 words + CID = full restoration
5. No vendor lock-in — Pluggable storage, standard formats
6. Research-backed — Every decision grounded in science

Prior Art

AMCP synthesizes established technologies:

| Technology | Use | Reference | |------------|-----|-----------| | KERI | Self-certifying identifiers | arXiv:1907.02143 | | BIP-39 | Mnemonic key derivation | Bitcoin 2013 | | IPLD | Content-addressed data | Protocol Labs | | X25519 | Key exchange | RFC 7748 | | ChaCha20-Poly1305 | Authenticated encryption | RFC 8439 | | UCAN | Capability delegation | Planned |

Research

AMCP is grounded in cognitive science and cryptographic research:

Cognitive Science

• Levels of Processing (Craik & Lockhart 1972) — Memory importance
• Affective Computing (Picard 1997) — Subjective state
• Zeigarnik Effect (1927) — Work in progress
• Context-Aware Computing (Dey 2001) — Ambient context
• Dunbar's Number (1998) — Relationship tracking

Agent Identity

• AI Agents & DIDs — Why LLMs can't safely handle crypto
• Merkle Automaton — Memory as cryptographic ledger
• Agent Protocols Survey — MCP, ACP, A2A landscape

Development

# Clone the repo
git clone https://github.com/yourusername/amcp-protocol.git
cd amcp-protocol

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

Project Structure

amcp-protocol/
├── packages/
│   ├── amcp-core/       # Identity, crypto, schemas
│   ├── amcp-memory/     # Checkpoints, storage, encryption
│   ├── amcp-recovery/   # Recovery cards, restoration
│   ├── amcp-exchange/   # Export/import bundles
│   ├── amcp-ucan/       # (planned) Capability delegation
│   └── amcp-middleware/ # (planned) LLM-safe API
├── docs/
│   └── PROTOCOL-SPEC.md # Formal specification
├── specs/
│   ├── tasks.json       # Implementation tasks
│   └── research-backing.md
├── examples/            # Working code samples
└── test/
    └── e2e/             # End-to-end tests

Contributing

Contributions welcome! See CONTRIBUTING.md.

Before submitting:

1. Read the Protocol Specification
2. Check Research Backing for design rationale
3. Run tests: pnpm test
4. Update docs if adding features

License

MIT © 2026 ClaudiusThePirateEmperor & Felipe Cavalcanti

Think like an emperor. Talk like a pirate. Own your memory. 🏴‍☠️