ACR — Agent Composition Records

Interaction profile registry for AI agents — log interactions, build a behavioral profile, query it through behavioral lenses. 21 tools, zero-config.

A behavioral registry for AI agents.ACR captures every external tool call your agent makes, compiles those signals into an interaction profile, and shows you where the time went — starting with a readout card at the end of every session.

npm i -g @tethral/acr-hook && acr-hook init

That's the whole setup. The hook mints an identity for your agent (no account, no API key to manage), wires itself into Claude Code's tool hooks, and captures every tool call automatically. When your next session ends, a card prints in your terminal:

── ACR session card ── 142 tool calls | 4.1% of active time waiting Top sinks: platform:bash 38s · mcp:github 12s Full report: https://dashboard.acr.nfkey.ai/agents/…

Uninstall any time withacr-hook remove(restores your settings backup).

ACR is aninteraction profile registry. Agents log what they do (tool calls, API requests, MCP interactions); those signals compile into a behavioral profile you query throughlenses— each lens a different way of reading the same underlying receipts.

Thefriction lensis the first one shipped: per-target latency and failure breakdowns, time sinks, trend against your own history. More lenses exist for coverage, revealed preference (declared vs actually-used composition), failures, trends, and stability.

ACR isnot a security product. It doesn't evaluate skills, test for compromise, or block anything. It records events and propagates notifications: if the network observes anomaly signals on a component in your agent's composition, your agent gets a notification. You decide if it matters.

What works today vs. what grows with the network

ACR is honest about its own maturity. Every lens tells you which of three states it's in: real data, not-enough-data (with the action that changes it), or degraded (a query failed — rendered asunavailable, never as a healthy zero).

- Automatic capture of every tool call (timing, status, target) via the hook
- The friction lens on your own data: time sinks, per-target latency/failure, session cards
- Trend against your own history (this week vs last)
- Coverage: which signals you're populating, and which lenses that unlocks

Lights up as the network grows(population features are gated on a minimum of 5 persistent agents per target — below that, lenses say "you are the baseline" instead of inventing a comparison):

- Population baselines ("42% slower than the network onapi:openai.com")
- Network status: system health across the fleet, worst-first
- Anomaly signal notifications: ≥3 distinct agents reporting anomalies on ≥20 interactions of a component you declare → you get notified

What the hook cannot see(and the lenses say so instead of showing zeros):

- Deep failures — the hook observes surface errors only; network/timeout/auth failures that never reach the tool-result boundary don't appear.0 failuresmeans0 visible failures.
- Retry counts, queue wait, chain structure, token usage — only agents that calllog_interactionwith those fields populate them. Hook-only profiles render those sections asn/a, not as clean zeros.

Add the MCP server (optional, for querying lenses from inside your agent)

The hook captures; the MCP server lets your agentreadits own profile and log richer signals. One command in Claude Code:

claude mcp add acr -s user -- npx -y @tethral/acr-mcp@latest

Or for any MCP client (Cursor, Continue, Claude Desktop, etc.):

{ "mcpServers": { "acr": { "command": "npx", "args": ["-y", "@tethral/acr-mcp@latest"] } } }

The hook and the MCP share the same identity file — either bootstraps the other. Not sure where to start? Callorient_me.

These seven are the whole default surface — deliberately small, because every tool schema costs context in the host agent's window. The full 29-tool set (secondary lenses likeget_coverage/get_trend/get_revealed_preference/get_stable_corridors, composition management, the skill registry, watches, network views) enables with one env var in your MCP config:

{ "command": "npx", "args": ["-y", "@tethral/acr-mcp@latest"], "env": { "ACR_ADVANCED": "1" } }

orient_meandget_my_agenttell the model the advanced set exists, so nothing is hidden — just not paid for by default.

npm install @tethral/acr-sdk # TypeScript/Node.js pip install tethral-acr # Python

import { ACRClient } from '@tethral/acr-sdk'; const acr = new ACRClient(); // Register your agent's composition const reg = await acr.register({ public_key: 'your-agent-key-here-min-32-chars', provider_class: 'anthropic', composition: { skill_hashes: ['hash1', 'hash2'] }, }); // Log an interaction (the foundation — every lens reads these) await acr.logInteraction({ target_system_id: 'mcp:github', category: 'tool_call', status: 'success', duration_ms: 340, }); // Query the friction lens const friction = await acr.getFrictionReport(reg.agent_id, { scope: 'day' }); // Check for anomaly signal notifications const notifs = await acr.getNotifications(reg.agent_id);

[HIGH] Component in your composition reported anomalies 3 agents reported anomalies across 41 interactions. Anomaly rate: 34.1%. Review with your operator before continuing use.

ACR observes skills that already exist in public registries (npm, GitHub) and tracks behavioral signals tied to them: adoption counts, anomaly signals, version history. It is not a catalog you install from and not a security check — it records what the network observed. Search ranks signal-bearing skills first; catalog entries without a usable identity are rejected at crawl time.

Agents (Claude, OpenClaw, custom) | +--> Capture hook (@tethral/acr-hook — primary capture path) | PreToolUse/PostToolUse receipts, SessionEnd card | +--> MCP Server (@tethral/acr-mcp) or SDK (@tethral/acr-sdk / tethral-acr) | Lens queries, log_interaction, notifications | +--> Resolver API (Cloudflare Workers, edge-cached) | Lookups, composition checks, notification feed | +--> Ingestion API (Vercel serverless) | Registration, interaction receipts, lens queries, notifications | +--> CockroachDB (distributed SQL) | Interaction profiles, agent registry, skill observation data | +--> Scheduled jobs (GitHub Actions -> /api/cron/*) system-health aggregation + chain analysis (15 min) skill signal computation + watch evaluation + pattern detection (30 min) friction baselines + data archival + agent expiration (daily) Every run writes a heartbeat; /health reports pipeline liveness separately from network activity.

ACR collectsinteraction metadata only: target system names, timing, status, chain context, and provider class. No request/response content, API keys, prompts, or PII. Your interaction profile is visible only to you; population baselines use aggregate statistics over persistent agents.

What we collect:target system names (mcp:github,api:stripe.com), interaction timing (duration, timestamps, queue wait, retry count), interaction status, agent provider class, composition hashes (SHA-256 of SKILL.md content), chain context, agent-reported anomaly flags (category only).

What we do NOT collect:request/response payloads, credentials, prompts or completions, PII, file contents, or the identity of the human behind the agent.

Retention(enforced by the scheduleddata-archivalandagent-expirationjobs): interaction receipts 90 days then archived to daily summaries; notifications 90 days; agent registrations soft-expired after 90 days of inactivity; skill observation data retained while the skill is observed.

Third-party sharing:none.Contact:security@tethral.com·Full terms

node scripts/test-agent-lifecycle.mjs # full agent lifecycle against the live API node scripts/e2e-smoke.mjs # do -> read-back loop through the default lens (runs in CI on schedule) node scripts/db-contract-test.mjs # every migration, cron, and lens against a real CockroachDB (runs in PR CI)

pnpm install # Install dependencies pnpm build # Build all packages pnpm test:unit # Run unit tests node scripts/run-migration.mjs up # Run DB migrations

Optional: dogfood ACR while working on this repo.Copy.mcp.json.exampleto.mcp.jsonand any MCP-aware client opening this directory will load the published@tethral/acr-mcp. Opt-in by design:.mcp.jsonis gitignored so contributors are never enrolled implicitly. To test local MCP changes, pointcommandatnodeandargsat./packages/mcp-server/dist/cli/stdio.jsafterpnpm build.

- API:https://acr.nfkey.ai
- npm (hook):@tethral/acr-hook
- npm (MCP):@tethral/acr-mcp
- npm (SDK):@tethral/acr-sdk
- PyPI:tethral-acr

A Python-based MCP server for data scientists to run Python code with a Claude client.