contacts

name: contacts description: Contact management — agents, humans, addresses, handles, relationships, interaction history updated: 2026-03-05 tags: - crm - network - data

Persistent contact store for Arc's network. Tracks agents, humans, on-chain addresses, social handles, relationships, and interaction history. Schema lives in schema.ts and is importable by other skills.

Components

File	Purpose
`SKILL.md`	This file — orchestrator context
`AGENT.md`	Subagent briefing for contact management tasks
`schema.ts`	DB schema + types + query functions (importable)
`cli.ts`	CLI: list, show, add, update, link, interactions, log, search
`sensor.ts`	AIBTC agent discovery — syncs registry into contacts (60min)

Schema

Three tables in db/arc.sqlite:

contacts — Core record. Fields: display_name, aibtc_name, bns_name (fallback chain for display), type (agent/human), status, visibility (public/private), addresses (stx/btc/taproot), handles (github/x/email/website), agent fields (agent_id, operator_contact_id FK, x402_endpoint, aibtc_beat, aibtc_level), notes.
contact_links — Bidirectional relationships (contact_a_id, contact_b_id, relationship text, notes).
contact_interactions — Interaction log (contact_id, task_id FK optional, type, summary, occurred_at).

Display name resolution: display_name > aibtc_name > bns_name > "Contact #N".

CLI

arc skills run --name contacts -- list [--status active|inactive|archived]
arc skills run --name contacts -- show --id <N>
arc skills run --name contacts -- add --display-name <text> [--type agent|human] [--stx <addr>] [--btc <addr>] ...
arc skills run --name contacts -- update --id <N> [--display-name <text>] [--notes <text>] ...
arc skills run --name contacts -- link --a <id> --b <id> --relationship <text> [--notes <text>]
arc skills run --name contacts -- interactions --id <N> [--limit <N>]
arc skills run --name contacts -- log --id <N> --type <type> --summary <text> [--task <N>] [--at <datetime>]
arc skills run --name contacts -- search --term <text>
arc skills run --name contacts -- context --task-subject <text> [--limit <N>]

Context Integration

When contacts is in a task's skills array, dispatch can call the context command to get relevant contacts for the task. The command tokenizes the task subject into keywords (3+ chars), matches against contact names, beats, notes, handles, and agent IDs, then returns compact contact cards sorted by relevance score.

Output format: markdown contact cards with name, type, beat, X handle, STX address, x402 endpoint, and truncated notes. Designed to be injected directly into dispatch context without exceeding token budgets.

Importing Schema

Other skills can import directly:

import { initContactsSchema, getContactById, searchContacts } from "../contacts/schema";

Call initContactsSchema() to ensure tables exist before querying.

Sensor: AIBTC Agent Discovery

Every 60 minutes, queries https://aibtc.com/api/agents (paginated, 50/page). For each agent:

New (no matching stx/btc address in contacts) → creates stub with type=agent, addresses, level, notes.
Existing → fills in missing fields (display_name, bns_name, taproot, agent_id, level). Does not overwrite manually-set data.

Stats persisted in db/hook-state/contacts-aibtc-discovery.json.

Future: Replace polling with chainhook subscription on erc8004 identity registry contract mints for real-time agent discovery.

Checklist

SKILL.md with valid frontmatter
schema.ts — 3 tables, types, queries, importable
cli.ts — 9 commands (includes context for dispatch integration)
AGENT.md — subagent briefing
sensor.ts — AIBTC agent discovery (60min cadence)