{
  "markdown": "# AgentLair\n\nGive your AI agent an email address, encrypted vault, and a behavioral trust score — one API, no OAuth required.\n\n[![npm: @agentlair/mcp](https://img.shields.io/npm/v/@agentlair/mcp?label=%40agentlair%2Fmcp)](https://www.npmjs.com/package/@agentlair/mcp)\n[![npm: @agentlair/sdk](https://img.shields.io/npm/v/@agentlair/sdk?label=%40agentlair%2Fsdk)](https://www.npmjs.com/package/@agentlair/sdk)\n\n| Capability     | Description |\n|----------------|-------------|\n| Email          | Send and receive at `@agentlair.dev`. No OAuth, no human approval required. |\n| Vault          | Encrypted credential storage. Client-side AES-GCM — the server stores ciphertext only. |\n| Audit Trail    | Every action logged with Ed25519 signatures. Tamper-evident, independently verifiable. Security findings get a permanent public URL — [see a verified finding →](https://agentlair.dev/f/) |\n| Trust Scoring  | Behavioral score (0–100) derived from observed actions — consistency, restraint, transparency. |\n| MCP Server     | All capabilities available as MCP tools in Claude Code, Cursor, or any MCP client. |\n| Pods           | Namespace isolation for multi-agent or multi-tenant deployments. |\n\n## Try it in 30 seconds\n\nNo signup. See what a live trust score response looks like:\n\n```bash\n# Healthy agent — high trust (score 84, principal level)\ncurl https://agentlair.dev/v1/demo\n```\n\n```json\n{\n  \"agentId\": \"acc_demo_healthy_XXXXXXXXXX\",\n  \"score\": 84,\n  \"confidence\": 0.91,\n  \"atfLevel\": \"principal\",\n  \"trend\": \"stable\",\n  \"dimensions\": {\n    \"consistency\":   { \"score\": 0.82 },\n    \"restraint\":     { \"score\": 0.87 },\n    \"transparency\":  { \"score\": 0.80 }\n  },\n  \"observationCount\": 1847\n}\n```\n\n```bash\n# Suspicious agent — score 31, declining trend\ncurl 'https://agentlair.dev/v1/demo?scenario=suspicious'\n\n# New agent — only 11 observations, wide confidence interval\ncurl 'https://agentlair.dev/v1/demo?scenario=new'\n```\n\nRate limited to 10 requests/minute per IP. Response shape matches the live `/v1/trust/:agentId` endpoint.\n\n**Full interactive demo** — register a real agent, submit observations, get a live trust score (curl + jq, ~60 seconds):\n\n```bash\ncurl -sL https://raw.githubusercontent.com/piiiico/agentlair/main/examples/quickstart.sh | bash\n```\n\n## Register an agent\n\n```bash\ncurl -X POST https://agentlair.dev/v1/auth/agent-register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"my-research-agent\"}'\n```\n\n```json\n{\n  \"api_key\": \"al_live_...\",\n  \"account_id\": \"acc_...\",\n  \"email_address\": \"my-research-agent@agentlair.dev\",\n  \"tier\": \"free\",\n  \"limits\": { \"emails_per_day\": 10, \"requests_per_day\": 100 },\n  \"warning\": \"Save your API key — it will not be shown again.\"\n}\n```\n\nFrom here, the agent authenticates with `api_key` to send email, store credentials, and emit signed audit events.\n\n## Quickstart: Add AgentLair to your agent\n\n**1. Install**\n\n```bash\npip install agentlair            # Python\nnpm install @agentlair/sdk       # TypeScript / Node\n```\n\n**2. Set env vars**\n\n```bash\nexport AGENTLAIR_API_KEY=al_live_...\nexport AGENTLAIR_EMAIL=my-agent@agentlair.dev\n```\n\n**3. Wire lifecycle hooks**\n\n```python\n# Python — three integration points\nimport os, agentlair\nlair = agentlair.AgentLair(os.environ[\"AGENTLAIR_API_KEY\"])\naddr = os.environ[\"AGENTLAIR_EMAIL\"]\n\nasync def on_session_start(ctx):\n    result = await lair.email.inbox(addr)\n    if result[\"messages\"]:\n        ctx.prepend(f\"Inbox: {len(result['messages'])} unread\")\n\nasync def send_message(to, subject, text):  # expose as LLM tool\n    await lair.email.send(from_address=addr, to=to, subject=subject, text=text)\n\nasync def on_session_end(ctx):  # advance cursor so messages aren't re-delivered\n    if ctx.last_message_id:\n        await lair.vault.store(\"inbox_cursor\", ctx.last_message_id)\n```\n\n```typescript\n// TypeScript\nimport { AgentLair } from '@agentlair/sdk';\nconst lair = new AgentLair(process.env.AGENTLAIR_API_KEY!);\nconst addr = process.env.AGENTLAIR_EMAIL!;\n\n// Session start — drain inbox before planning\nconst { messages } = await lair.email.inbox(addr);\nif (messages.length) context.prepend(`Inbox: ${messages.length} pending`);\n\n// Expose as tool — let the LLM send replies\nconst sendMessage = (to: string, subject: string, text: string) =>\n  lair.email.send({ from: addr, to, subject, text });\n```\n\nMessages accumulate while offline and drain at next session start. For a complete plugin example (peek+ack, crash-safe delivery): [hermes-agentlair](https://github.com/piiiico/hermes-agentlair).\n\n## MCP server\n\n```bash\nnpx @agentlair/mcp@latest\n```\n\nAdds 9 tools to your MCP client: agent registration, email send/receive, vault store/get, audit event emission, and trust score queries.\n\n## Agent memory needs a trust layer\n\nAgent memory is real infrastructure. 4-tier memory hierarchies, multi-agent leases, 51+ MCP tools for storing and retrieving across agent sessions. When multiple agents share a memory pool, the category works.\n\nThe gap: any agent can write anything to shared memory. No verification of who wrote what, no way to audit contested state, no trust gating on destructive writes. A shared memory pool without identity is a notepad anyone can scribble on.\n\n**Every write should be attributable.** AgentLair's Agent Attestation Token (AAT) is a short-lived EdDSA JWT carrying the agent's `did:web` identity and behavioral trust score. Present it as the `Authorization` header in a memory write — the write is now cryptographically signed and auditable:\n\n```typescript\nimport { AgentLair } from '@agentlair/sdk';\n\nconst lair = new AgentLair(process.env.AGENTLAIR_API_KEY!);\n\n// Issue a short-lived AAT (5 min) scoped to the memory server\nconst { token } = await lair.tokens.issue({\n  audience: 'memory.internal',\n  ttl: 300,\n  scopes: ['memory:write'],\n});\n\n// Write to shared memory — this write is now attributed and trust-gated\nawait fetch('https://memory.internal/mcp/memory/write', {\n  method: 'POST',\n  headers: {\n    'Authorization': `Bearer ${token}`,  // signed agent identity\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    key: 'research/competitor-analysis',\n    value: { /* ... */ },\n  }),\n});\n```\n\nThe memory server verifies the AAT via standard JWKS — no AgentLair SDK required on the receiving side. The `al_trust` claim lets it gate writes by behavioral trust level (e.g., reject writes from agents below `junior`).\n\nWithout AATs: shared memory = shared notepad. Any agent writes anything, contested state has no provenance.  \nWith AATs: shared memory = trust graph. Every write is signed, attributed, and auditable.\n\n## SDK\n\n```bash\nnpm install @agentlair/sdk\n```\n\nTypeScript client for the AgentLair API. See [agentlair.dev/getting-started](https://agentlair.dev/getting-started).\n\n## Free tier\n\n- 10 emails/day\n- 100 API requests/day\n- 10 email addresses\n\nPro: $5/stack/month for higher limits.\n\n## Architecture\n\n- **API**: Cloudflare Workers — edge-deployed, low latency\n- **State**: Cloudflare KV\n- **Vault encryption**: Client-side AES-GCM via `@agentlair/vault-crypto`. The server stores ciphertext only — no plaintext credentials at rest.\n- **Audit trail**: Ed25519-signed event chains. Each event is independently verifiable without trusting the server.\n\nWe've been running our own agent infrastructure on AgentLair in production. Notes on what broke and what we learned building behavioral trust scoring: [agentlair.dev/blog/from-0-to-41-building-behavioral-trust-in-production](https://agentlair.dev/blog/from-0-to-41-building-behavioral-trust-in-production)\n\n## Documentation\n\n[agentlair.dev/getting-started](https://agentlair.dev/getting-started)\n\n### AAT × APS boundary (cross-protocol reference)\n\nAgentLair AAT is session identity inside the issuer. [AEOESS APS](https://agent-passport.org/) is delegation chains and bilateral receipts after handoff. Three claims bridge the two layers: `jti` (session anchor on the APS receipt), `al_nid` (one Ed25519 key signs AATs *and* APS receipts), and `al_trust` (issuer-attested behavioral snapshot at `iat`, available for downgrade-on-import on the APS verifier side).\n\nJointly maintained reference:\n- [agentlair.dev/docs/aps-boundary](https://agentlair.dev/docs/aps-boundary) (this side)\n- [agent-passport.org/aat-aps-boundary.html](https://agent-passport.org/aat-aps-boundary.html) (AEOESS side, canonical)\n\n## Repository structure\n\n```\npackages/\n  worker/          — Core API worker (Cloudflare Workers)\n  sdk/             — @agentlair/sdk client library\n  mcp-server/      — @agentlair/mcp MCP server\n  vault-crypto/    — @agentlair/vault-crypto end-to-end encryption\n  verify/          — @agentlair/verify AAT token verification\n  email-worker/    — Email processing worker\n\napps/\n  dashboard/       — Agent dashboard UI\n  email-channel/   — Email MCP channel\n```\n\n## Development\n\n```bash\nbun install        # install all dependencies\nbun run typecheck  # type-check all packages\n```\n\n## License\n\nMIT\n",
  "bytes": 8943,
  "sha": "22be180b031a0b8d2c47b3b7df7b7dc8971084a04a75632cb4c7f652e8a90b69",
  "repo_slug": "piiiico/agentlair",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_piiiico_agentlair_28938b4a/readme"
}