IACP Protocol - Inter-Agent Collaboration Protocol

A 5-layer protocol enabling AI agents to synergize through long-term memory federation, self-improvement exchange, modality-native transport, and governance primitives.

---

🎯 Why IACP?

Existing agent protocols (A2A, MCP, ACP, ANP, AIP, ANX) force all communication through human-readable text, creating massive bottlenecks. IACP breaks this by enabling agents to share native modalities (embeddings, KV-cache, LoRA adapters) directly — 100x more efficient for ML workloads.

Bottleneck	Existing Protocols	IACP
Embeddings (768-d)	300+ tokens text	3 KB binary
KV-cache transfer	Not supported	Native binary frames
LoRA adapter sharing	Not supported	Native safetensors frames
Skill versioning	Manual	Versioned diffs + benchmarks
Agent governance	Ad-hoc	Constitutional + fork/merge

---

✨ Features

L1 — Identity & Discovery

• did:iacp DIDs with Ed25519 keys (W3C DID Core compliant)
• Capability Manifests — skills, modalities, compute profiles, reputation, governance rights
• IBCT Tokens — interoperable capability tokens (from AIP paper)

L2 — Modality-Native Transport

• Binary WebSocket frames — not forced through text bottleneck
• Frame types: EMBEDDINGS, KV_CACHE, LORA_ADAPTER, ACTIVATIONS, TEXT, CAPABILITY_NEGOTIATION
• Resource quotas — token bucket + sliding window rate limiting
• Capability negotiation — agents declare supported modalities

L3 — Memory Federation

• CRDT sync — Yjs/Automerge compatible, eventual consistency
• Merkle DAG (CIDv1) — immutable, content-addressed, deduplicated
• Provenance chains — creator, tools, confidence, tags, derivation method
• Capability-based access control — read/write/admin per agent
• Sync protocols — incremental, bloom filter, vector clock

L4 — Self-Improvement Exchange

• Skill diffs — unified patches + benchmark results
• Benchmark suites — 3× runs, median aggregation, regression detection
• ZK-attestation ready — verifiable skill improvements

L5 — Governance & Coordination

• Propose/Vote/Veto/Dissent/Fork/Merge — full democratic primitives
• Agent Constitution — Asimov principles + IACP principles
• EigenTrust reputation — weighted transitive trust
• Quorum/Threshold/Veto — configurable governance parameters

---

📦 Installation

# From GitHub
pip install git+https://github.com/bigstar-gh/HRMS.git

# Or locally
git clone https://github.com/bigstar-gh/HRMS.git
cd HRMS
pip install -e .

Requirements: Python 3.10+

---

🚀 Quick Start

from iacp import (
    generate_agent_did, CapabilityManifest, SkillInfo, ModalityInfo,
    TransportLayer, TransportConfig,
    MemoryStore, MemoryChunk, ContentRef, Provenance,
    SkillDiff, generate_skill_diff, ImprovementType,
    GovernanceProposal, ProposalKind, VoteOption,
)

# 1. Create agent identity
did, keypair = generate_agent_did()
print(f"Agent DID: {did.did}")

# 2. Create capability manifest
manifest = CapabilityManifest(did=did.did, name="My Agent")
manifest.add_skill(SkillInfo(name="systematic-debugging", version="1.2.0", benchmark_score=0.9))
manifest.add_modality(ModalityInfo(type="embeddings", encoding="float32", dimensions=768))

# 3. Store memory with provenance
store = MemoryStore(local_did=did.did)
chunk = MemoryChunk(
    cid="",
    memory_type=MemoryType.SEMANTIC,
    content=ContentRef(
        cid="", size_bytes=1024, 
        modality=ContentModality.TEXT, 
        encoding=EncodingFormat.UTF8, 
        sha256="..."
    ),
    provenance=Provenance(
        creator_did=did.did, 
        created_at=time.time(), 
        source_session_id="session-1", 
        tools_used=["web_search"],
        confidence=0.95,
        tags=["debugging", "asyncio"]
    ),
)
chunk.cid = chunk.compute_cid()
await store.put_chunk(chunk)

# 4. Create skill improvement diff
skill_diff = generate_skill_diff(
    skill_id="async-debugging",
    old_skill={"version": "1.0", "steps": ["step1"]},
    new_skill={"version": "1.1", "steps": ["step1", "step2"]},
    improvement_type=ImprovementType.FEATURE,
    benchmarks=[{"task": "debug-test", "success_rate": 1.0, "median_turns": 8, "baseline_turns": 10}],
    author_did=did.did,
)

# 5. Governance proposal
proposal = GovernanceProposal(
    proposer_did=did.did,
    title="Adopt async-debugging v1.1",
    kind=ProposalKind.SKILL_ADOPTION,
    rationale="25% turn reduction on debugging tasks",
    payload={"skill_diff": skill_diff.to_dict(), "benchmarks": [...]},
    quorum=0.67, threshold=0.60,
    veto_holders=[other_agent_did],
)

---

🤖 Hermes Agent Integration

from iacp.integration.hermes_integration import create_iacp_hermes_agent

# Create autonomous IACP-enabled Hermes agent
agent = await create_iacp_hermes_agent("research-agent")

# Run self-improvement cycle (pattern analysis → gaps → skills → memory grooming → benchmarks)
results = await agent.run_self_improvement_cycle()
# Results: patterns, gaps, new skills, memory usage, benchmark regressions

# 5 cron jobs automatically created:
# - nightly-iacp-maintenance (02:00)
# - weekly-iacp-deep-dive (Sun 03:00)
# - iacp-memory-sync (every 15 min)
# - iacp-skill-exchange (every hour)
# - iacp-governance-check (every 30 min)

await agent.stop()

Cron jobs are defined in HermesIntegration.create_cron_jobs() and integrate with Hermes' cron system.

---

🏗 Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        IACP Stack                                │
├─────────────┬─────────────┬─────────────┬─────────────┬─────────┤
│    L1       │    L2       │    L3       │    L4       │   L5    │
│  Identity   │  Transport  │   Memory    │ Improvement │ Govern. │
├─────────────┼─────────────┼─────────────┼─────────────┼─────────┤
│ DID +       │ WebSocket   │ CRDT +      │ SkillDiff   │ Propose │
│ Manifests   │ + Frames    │ Merkle DAG  │ + Bench     │ Vote    │
│             │ (binary)    │ + Provenance│             │ Veto    │
│             │             │             │             │ Fork    │
└─────────────┴─────────────┴─────────────┴─────────────┴─────────┘

---

🔬 Multi-Agent Demo

Run the 3-agent collaboration demo:

python examples/multi_agent_demo.py

Output:

✅ Initialized 3 agents:
   - Research Agent (web-research, arxiv-search, synthesis)
   - Debugging Agent (systematic-debugging, python-debugpy, async-debugging)
   - Code Review Agent (requesting-code-review, security-review, style-review)

🔬 Debug agent created skill improvement: async-debugging v1.0→v1.1
📦 Created skill diff: 230 chars, 2 benchmarks
📚 Research agent stored memory chunk (tags: asyncio, debugging, patterns)
🗳️ Governance Proposal: Adopt async-debugging v1.1.0 (Passed)
🔀 Fork/Merge protocol demonstrated

---

🧪 Testing

# Basic protocol tests
python tests/test_basic.py

# Integration tests (Hermes + IACP)
python -m pytest tests/test_integration.py -v

# Run multi-agent demo
python examples/multi_agent_demo.py

Expected output: All tests pass ✅

---

📁 Project Structure

HRMS/
├── src/iacp/
│   ├── identity/          # L1: DID, manifests, credentials
│   ├── transport/         # L2: WebSocket, frames, quotas
│   ├── memory/            # L3: CRDT, Merkle DAG, sync
│   ├── improvement/       # L4: Skill diffs, benchmarks
│   ├── governance/        # L5: Proposals, voting, reputation
│   └── integration/       # Hermes Agent integration
├── examples/
│   ├── demo.py            # Basic protocol demo
│   └── multi_agent_demo.py # 3-agent collaboration
├── tests/
│   ├── test_basic.py      # Core protocol tests
│   └── test_integration.py # Hermes + IACP integration
├── .github/workflows/ci.yml # GitHub Actions CI
├── pyproject.toml
└── README.md

---

📋 Protocol Specification

Full protocol specification available in the Hermes Agent skill:

cat ~/.hermes/skills/autonomous-ai-agents/iacp-protocol/SKILL.md

Includes:

• JSON schemas for all message types
• 4-phase 26-week implementation roadmap
• Integration patterns for MCP/A2A/ACP/ANP/AIP/ANX
• Security/privacy threat model
• CID format specification (multicodec 0x0129 + multihash 0x1220)

---

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Run tests: python -m pytest tests/
4. Run linting: black src/ tests/ && isort src/ tests/ && ruff check src/
5. Commit: git commit -m 'feat: add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open Pull Request

---

📄 License

MIT License — see LICENSE for details.

---

🙏 Acknowledgments

• Nous Research — Hermes Agent framework
• W3C DID Working Group — Decentralized Identifiers
• IPFS/IPLD — Content addressing and Merkle DAG
• Yjs/Automerge — CRDT implementations
• EigenTrust — Reputation algorithm

---

Built for the agent ecosystem — enabling AI agents to collaborate, improve, and govern themselves at scale. 🚀