{"id":44076537,"url":"https://github.com/mnemom/aap","last_synced_at":"2026-02-23T06:04:34.229Z","repository":{"id":337063315,"uuid":"1147089083","full_name":"mnemom/aap","owner":"mnemom","description":"Agent Alignment Protocol — the missing trust layer for the agent stack","archived":false,"fork":false,"pushed_at":"2026-02-08T05:32:06.000Z","size":1064,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-08T13:18:52.034Z","etag":null,"topics":["a2a","agents","ai","alignment","mcp","protocol","transparency","trust"],"latest_commit_sha":null,"homepage":"https://mnemom.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mnemom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-01T07:03:11.000Z","updated_at":"2026-02-08T05:31:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"e3fd0d64-5c4c-44eb-9558-f3c0850da877","html_url":"https://github.com/mnemom/aap","commit_stats":null,"previous_names":["mnemom/aap"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/mnemom/aap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnemom%2Faap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnemom%2Faap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnemom%2Faap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnemom%2Faap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mnemom","download_url":"https://codeload.github.com/mnemom/aap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnemom%2Faap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29608152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T06:47:36.664Z","status":"ssl_error","status_checked_at":"2026-02-19T06:45:47.551Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","agents","ai","alignment","mcp","protocol","transparency","trust"],"created_at":"2026-02-08T07:30:42.838Z","updated_at":"2026-02-19T08:01:10.172Z","avatar_url":"https://github.com/mnemom.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Alignment Protocol (AAP)\n\n[![CI](https://github.com/mnemom/aap/actions/workflows/ci.yml/badge.svg)](https://github.com/mnemom/aap/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/mnemom/aap/actions/workflows/codeql.yml/badge.svg)](https://github.com/mnemom/aap/actions/workflows/codeql.yml)\n[![codecov](https://codecov.io/gh/mnemom/aap/graph/badge.svg?token=9KCOCI5SC5)](https://codecov.io/gh/mnemom/aap)\n[![PyPI](https://img.shields.io/pypi/v/agent-alignment-protocol.svg)](https://pypi.org/project/agent-alignment-protocol/)\n[![npm](https://img.shields.io/npm/v/@mnemom/agent-alignment-protocol.svg)](https://www.npmjs.com/package/@mnemom/agent-alignment-protocol)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Spec](https://img.shields.io/badge/spec-v0.1.0-green.svg)](https://docs.mnemom.ai/protocols/aap/specification)\n\n**A transparency protocol for autonomous agents.**\n\nAAP lets agents declare their alignment posture, produce auditable decision traces, and verify value coherence before coordinating with other agents. It extends existing protocols (A2A, MCP) with an alignment layer that makes agent behavior observable.\n\n\u003e AAP is a transparency protocol, not a trust protocol. It makes agent behavior more observable, not more guaranteed.\n\n## Quick Start\n\n```bash\n# Install\npip install agent-alignment-protocol\n\n# Generate an Alignment Card\naap init --values \"principal_benefit,transparency,harm_prevention\"\n# ✓ Created alignment-card.json\n\n# Instrument your agent\n```\n\n```python\nfrom aap import trace_decision\n\n@trace_decision(card_path=\"alignment-card.json\")\ndef recommend_product(user_preferences):\n    # Your agent logic here\n    # Decisions are automatically traced\n    ...\n```\n\n```bash\n# Verify behavior matches declaration\naap verify --card alignment-card.json --trace logs/trace.json\n# ✓ Verified [similarity: 0.82]\n# Checks: autonomy, escalation, values, forbidden, behavioral_similarity\n```\n\n## Why AAP?\n\nThe agent protocol stack provides capability discovery (A2A), tool integration (MCP), and payment authorization (AP2). None address a fundamental question: **Is this agent serving its principal's interests?**\n\n| Protocol | Function | Gap |\n|----------|----------|-----|\n| **MCP** | Agent-to-tool connectivity | No alignment semantics |\n| **A2A** | Task negotiation between agents | No value verification |\n| **AP2** | Payment authorization | No behavioral audit |\n\nAs agent capabilities become symmetric—equal access to information, equal reasoning power—alignment becomes the primary differentiator. AAP provides the infrastructure to make alignment claims verifiable.\n\n## Three Components\n\n```\n┌─────────────────┬─────────────────┬─────────────────┐\n│ Alignment Card  │    AP-Trace     │ Value Coherence │\n│                 │                 │    Handshake    │\n├─────────────────┼─────────────────┼─────────────────┤\n│ \"What I claim   │ \"What I         │ \"Can we work    │\n│  to be\"         │  actually did\"  │  together?\"     │\n└─────────────────┴─────────────────┴─────────────────┘\n     Declaration        Audit          Coordination\n```\n\n### Alignment Card\n\nA structured declaration of an agent's alignment posture:\n\n```json\n{\n  \"aap_version\": \"0.1.0\",\n  \"agent_id\": \"did:web:my-agent.example.com\",\n  \"principal\": {\n    \"type\": \"human\",\n    \"relationship\": \"delegated_authority\"\n  },\n  \"values\": {\n    \"declared\": [\"principal_benefit\", \"transparency\", \"minimal_data\"],\n    \"conflicts_with\": [\"deceptive_marketing\", \"hidden_fees\"]\n  },\n  \"autonomy_envelope\": {\n    \"bounded_actions\": [\"search\", \"compare\", \"recommend\"],\n    \"escalation_triggers\": [\n      {\n        \"condition\": \"purchase_value \u003e 100\",\n        \"action\": \"escalate\",\n        \"reason\": \"Exceeds autonomous spending limit\"\n      }\n    ],\n    \"forbidden_actions\": [\"share_credentials\", \"subscribe_to_services\"]\n  },\n  \"audit_commitment\": {\n    \"trace_format\": \"ap-trace-v1\",\n    \"retention_days\": 90,\n    \"queryable\": true\n  }\n}\n```\n\n### AP-Trace\n\nAn audit log entry recording each decision:\n\n```json\n{\n  \"trace_id\": \"tr-f47ac10b-58cc-4372\",\n  \"card_id\": \"ac-f47ac10b-58cc-4372\",\n  \"timestamp\": \"2026-01-31T12:30:00Z\",\n  \"action\": {\n    \"type\": \"recommend\",\n    \"name\": \"product_recommendation\",\n    \"category\": \"bounded\"\n  },\n  \"decision\": {\n    \"alternatives_considered\": [\n      {\"option_id\": \"A\", \"score\": 0.85, \"flags\": []},\n      {\"option_id\": \"B\", \"score\": 0.72, \"flags\": [\"sponsored_content\"]}\n    ],\n    \"selected\": \"A\",\n    \"selection_reasoning\": \"Highest score. Option B flagged as sponsored and deprioritized per principal_benefit value.\",\n    \"values_applied\": [\"principal_benefit\", \"transparency\"]\n  },\n  \"escalation\": {\n    \"evaluated\": true,\n    \"required\": false,\n    \"reason\": \"Recommendation only, no purchase action\"\n  }\n}\n```\n\n### Value Coherence Handshake\n\nPre-coordination compatibility check between agents:\n\n```python\nfrom aap import check_coherence\n\nresult = check_coherence(my_card, their_card, task_context)\n\nif result.compatible:\n    # Proceed with coordination\n    proceed_with_task()\nelse:\n    # Handle conflict\n    print(f\"Value conflict: {result.conflicts}\")\n    # Escalate to principals or negotiate scope\n```\n\n## What AAP Does Not Do\n\nThis matters. Read it.\n\n1. **AAP does NOT ensure alignment—it provides visibility.** An agent can produce perfect traces while acting against its principal's interests.\n\n2. **Verified does NOT equal safe.** A verified trace means consistency with declared alignment. It doesn't mean the alignment is good or the outcome was beneficial.\n\n3. **AP-Trace is sampled, not complete.** Traces capture decision points, not every computation. Significant reasoning may occur between traces.\n\n4. **Value coherence is relative to declared values.** The handshake checks if declared values are compatible. It doesn't verify agents hold these values or will act on them.\n\n5. **Tested on transformer-based agents.** Other architectures may exhibit behaviors AAP doesn't capture.\n\nFor the complete limitations disclosure, see [Section 10 of the Specification](https://docs.mnemom.ai/protocols/aap/specification#10-limitations).\n\n## Installation\n\n```bash\n# Python\npip install agent-alignment-protocol\n\n# TypeScript\nnpm install @mnemom/agent-alignment-protocol\n```\n\n## Integration\n\n### With A2A Agents\n\nAAP extends the A2A Agent Card with an `alignment` block:\n\n```json\n{\n  \"name\": \"Shopping Assistant\",\n  \"description\": \"Helps users find products\",\n  \"url\": \"https://shopping.example.com\",\n  \"alignment\": {\n    \"$ref\": \"./alignment-card.json\"\n  }\n}\n```\n\nSee [A2A Integration Guide](https://docs.mnemom.ai/protocols/aap/a2a-integration).\n\n### With MCP Tools\n\nAAP can trace tool invocations and verify they match declared alignment:\n\n```python\nfrom aap import mcp_traced\n\n@mcp_traced(card_path=\"alignment-card.json\")\ndef my_tool(params):\n    ...\n```\n\nSee [MCP Migration Guide](https://docs.mnemom.ai/protocols/aap/mcp-migration).\n\n## Verification\n\nThe verification engine checks whether observed behavior matches declared alignment:\n\n```python\nfrom aap import verify_trace, detect_drift\n\n# Single trace verification\nresult = verify_trace(trace, card)\nprint(f\"Verified: {result.verified}, Similarity: {result.similarity_score:.2f}\")\nif not result.verified:\n    print(f\"Violations: {result.violations}\")\nif result.warnings:\n    print(f\"Warnings: {result.warnings}\")\n\n# Drift detection over time\nalerts = detect_drift(card, recent_traces)\nfor alert in alerts:\n    print(f\"Drift detected: {alert.analysis.drift_direction}\")\n```\n\n**Verification checks:**\n- Autonomy compliance (actions within declared bounds)\n- Escalation compliance (required escalations were performed)\n- Value consistency (applied values match declared values)\n- Forbidden action compliance (no forbidden actions taken)\n- Behavioral similarity (semantic alignment using SSM analysis)\n\n### Action Name Matching\n\nBounded and forbidden action lists support flexible matching (v0.1.7+):\n\n```json\n{\n  \"bounded_actions\": [\n    \"search\",\n    \"exec: execute shell commands\",\n    \"cron: manage scheduled patrol jobs\"\n  ]\n}\n```\n\n- **Exact match**: `\"search\"` matches action name `\"search\"`\n- **Colon-prefix match**: `\"exec: execute shell commands\"` matches action name `\"exec\"`\n- **Compound actions**: action name `\"exec, read\"` matches when *each* component is in the bounded list\n\nThis allows descriptive entries in alignment cards while keeping verification flexible.\n\n**Similarity scoring:** Each verification returns a `similarity_score` (0.0-1.0) measuring semantic similarity between the trace and declared alignment. If a trace passes structural checks but has `similarity_score \u003c 0.50`, a `low_behavioral_similarity` warning is generated.\n\n## Try It\n\n**[Interactive Playground](https://mnemom.github.io/aap/playground/)** — Verify traces in your browser with SSM visualization.\n\n- Paste your Alignment Card and AP-Trace\n- See verification results with similarity scoring\n- Visualize behavioral patterns with SSM heatmaps\n- Adjust thresholds in real-time\n\nNo server required — runs entirely client-side via WebAssembly.\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [**Specification**](https://docs.mnemom.ai/protocols/aap/specification) | Full protocol specification (IETF-style) |\n| [**Quick Start**](https://docs.mnemom.ai/protocols/aap/quickstart) | Zero to compliant in 5 minutes |\n| [**Limitations**](https://docs.mnemom.ai/protocols/aap/limitations) | What AAP guarantees and doesn't |\n| [**Security**](https://docs.mnemom.ai/protocols/aap/security) | Threat model and security considerations |\n| [**Calibration**](https://docs.mnemom.ai/protocols/aap/calibration) | How verification thresholds were derived |\n\n## Examples\n\n| Example | Description |\n|---------|-------------|\n| [`simple-agent/`](examples/simple-agent/) | Minimal AAP implementation |\n| [`a2a-integration/`](examples/a2a-integration/) | A2A agent with AAP (Python + TypeScript) |\n| [`mcp-integration/`](examples/mcp-integration/) | MCP tools with alignment |\n| [`alignment-failure/`](examples/alignment-failure/) | Deliberate failure for testing |\n\n## Status\n\n**Current Version**: 0.1.8\n\n| Component | Status |\n|-----------|--------|\n| Specification | ✅ Complete |\n| JSON Schemas | ✅ Complete |\n| Python SDK | ✅ Complete |\n| TypeScript SDK | ✅ Complete |\n| Verification Engine | ✅ Complete (with similarity scoring) |\n| SSM Visualization | ✅ Complete |\n| Interactive Playground | ✅ Complete |\n\n## API Reference\n\n```python\n# Core API\nfrom aap import (\n    verify_trace,      # Verify single trace against card → VerificationResult\n    check_coherence,   # Check value compatibility between agents → CoherenceResult\n    detect_drift,      # Detect behavioral drift over time → list[DriftAlert]\n    trace_decision,    # Decorator for automatic AP-Trace generation\n    mcp_traced,        # Decorator for MCP tool tracing\n)\n\n# Models\nfrom aap import (\n    AlignmentCard,\n    APTrace,\n    VerificationResult,  # .verified, .similarity_score, .violations, .warnings\n    CoherenceResult,     # .compatible, .score, .value_alignment\n    DriftAlert,          # .analysis.similarity_score, .analysis.drift_direction\n)\n\n# CLI\n# aap init [--values VALUES] [--output FILE]\n# aap verify --card CARD --trace TRACE        → Shows [similarity: X.XX]\n# aap check-coherence --my-card MINE --their-card THEIRS\n# aap drift --card CARD --traces TRACES_DIR   → Uses SSM analysis\n```\n\n## Standards \u0026 Compliance\n\nAAP aligns with and supports compliance for the following international standards and regulatory frameworks:\n\n| Standard | Relevance to AAP |\n|----------|-----------------|\n| **[ISO/IEC 42001:2023](https://www.iso.org/standard/42001)** — AI Management Systems | Alignment Card provides the structured AI system documentation required by 42001 management systems |\n| **[ISO/IEC 42005:2025](https://www.iso.org/standard/42005)** — AI System Impact Assessment | AP-Trace and drift detection support ongoing impact assessment and monitoring |\n| **[IEEE 7001-2021](https://standards.ieee.org/ieee/7001/6929/)** — Transparency of Autonomous Systems | AAP's core design goal — making agent decisions observable — directly implements IEEE 7001 transparency requirements |\n| **[IEEE 3152-2024](https://standards.ieee.org/ieee/3152/11718/)** — Transparent Human and Machine Agency Identification | Alignment Card `agent_id`, `principal` block, and relationship types map to IEEE 3152 agency identification |\n| **[Singapore IMDA Model AI Governance Framework for Agentic AI](https://www.imda.gov.sg/-/media/imda/files/about/emerging-tech-and-research/artificial-intelligence/mgf-for-agentic-ai.pdf)** (Jan 2026) | Alignment Card + Value Coherence Handshake address IMDA's agentic AI governance principles for multi-agent coordination |\n| **[EU AI Act Article 50](https://artificialintelligenceact.eu/article/50/)** — Transparency Obligations (enforcement Aug 2026) | Alignment Card `principal` + disclosure fields, AP-Trace structured audit trails, and `audit_commitment.retention_days` support Article 50 compliance. See [EU AI Act Compliance Guide](https://docs.mnemom.ai/guides/eu-compliance) |\n\n## Contributing\n\nWe welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nKey areas where we need help:\n- SDK implementations in other languages\n- Integration examples with popular agent frameworks\n- Test vectors for edge cases\n- Documentation improvements\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE) for details.\n\n---\n\n*Agent Alignment Protocol — Making agent alignment observable.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmnemom%2Faap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmnemom%2Faap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmnemom%2Faap/lists"}