contacts

name	contacts
description	AI-powered unified contact management with semantic search, relationship tracking, entity resolution, graph queries, and multi-platform integration.
metadata	{"clawdbot":{"emoji":"👥","requires":{"bins":["node"]}}}

Contacts Skill

Manage contacts across multiple platforms with AI-powered semantic search, relationship strength tracking, entity resolution, graph queries (Neo4j), and interaction tracking (TimescaleDB).

CLI Usage

Run commands via node:

node ~/projects/clawdbot-contacts/dist/cli.js <command> [options]

Commands

Add a contact

node ~/projects/clawdbot-contacts/dist/cli.js add --name "Jane Smith" --email "[e-mail]" --org "Acme Corp"

Search contacts (semantic)

node ~/projects/clawdbot-contacts/dist/cli.js search "engineers in San Francisco"

List contacts

node ~/projects/clawdbot-contacts/dist/cli.js list --limit 20 --page 1
node ~/projects/clawdbot-contacts/dist/cli.js list --tier close

View contact details

node ~/projects/clawdbot-contacts/dist/cli.js view <contact-id>

Edit contact

node ~/projects/clawdbot-contacts/dist/cli.js edit <id> --name "New Name" --tier close

Delete contact

node ~/projects/clawdbot-contacts/dist/cli.js delete <contact-id>

Find by identifier

node ~/projects/clawdbot-contacts/dist/cli.js find email [e-mail]
node ~/projects/clawdbot-contacts/dist/cli.js find phone [phone]

Find duplicates

node ~/projects/clawdbot-contacts/dist/cli.js duplicates

Merge contacts

node ~/projects/clawdbot-contacts/dist/cli.js merge <keep-id> <merge-id>

Create relationship

node ~/projects/clawdbot-contacts/dist/cli.js relate <id1> <id2> --type colleague --label "team lead"

Relationship types: family, friend, colleague, acquaintance, mentor, mentee, manager, report, client, vendor, partner, collaborator

Get AI suggestions

node ~/projects/clawdbot-contacts/dist/cli.js suggest

Graph Queries (Neo4j)

Find degrees of separation

Find how two contacts are connected:

# Via programmatic API
skill.findDegreesOfSeparation(contact1Id, contact2Id)
# Returns: { degrees: 2, path: [...] }

Who knows who

Find all contacts who know a specific person:

# Via programmatic API
skill.whoKnows(contactId, depth?)
# Returns list of contacts connected to this person

Mutual connections

Find contacts that both people know:

# Via programmatic API
skill.getMutualConnections(contact1Id, contact2Id)
# Returns list of shared connections

Interaction Tracking (TimescaleDB)

Record interactions

Track when you interact with contacts:

// Via programmatic API
await skill.recordView(contactId);  // Contact was viewed
// Messages, calls, emails are tracked automatically when using adapters

Stale contacts

Find contacts you haven't interacted with recently:

// Get contacts not talked to in 30 days
const stale = await skill.getStaleContacts(30);
// Returns: [{ contactId, displayName, lastInteraction, daysSince }]

Interaction history

Get detailed interaction history:

const history = await skill.getInteractionHistory(contactId, { limit: 50 });
// Returns: [{ eventType, direction, platform, occurredAt }]

Relationship Tiers (Dunbar)

Tier	Description	Typical Count
inner_circle	Closest relationships	~5
close	Close friends/family	~15
active	Regular contact	~50
familiar	Acquaintances	~150
acquaintance	Known contacts	~500+

Database Requirements

Database	Purpose	Port	Required
SQLite	Primary storage	-	Yes (built-in)
ChromaDB	Semantic search	8000	Optional
Neo4j	Graph queries	7687	Optional
TimescaleDB	Interaction tracking	5432	Optional

Environment Variables

# SQLite
CONTACTS_DB_PATH=~/.clawdbot/contacts.db

# ChromaDB (semantic search)
CHROMA_URL=http://localhost:8000

# Neo4j (graph queries)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# TimescaleDB (interaction tracking)
TIMESCALE_HOST=localhost
TIMESCALE_PORT=5432
TIMESCALE_DATABASE=clawdbot
TIMESCALE_USER=clawdbot
TIMESCALE_PASSWORD=password

Programmatic API

import { ContactSkill } from '@clawdbot/contacts';

const skill = new ContactSkill({
  enableNeo4j: true,
  enableTimescale: true,
});

await skill.initialize();

// Core operations
await skill.add({ givenName: 'John', source: 'manual' });
await skill.search('engineers');
await skill.view(contactId);

// Relationships
await skill.relate(id1, id2, 'colleague');

// Graph queries (requires Neo4j)
await skill.findDegreesOfSeparation(id1, id2);
await skill.whoKnows(contactId);
await skill.getMutualConnections(id1, id2);

// Interaction tracking (requires TimescaleDB)
await skill.getStaleContacts(30);
await skill.getInteractionHistory(contactId);

await skill.close();