# Contacts

> AI-powered unified contact management with semantic search, relationship tracking, entity resolution, graph queries, and multi-platform integration.

- Skill: `kimasplund/contacts` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add kimasplund/contacts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kimasplund/contacts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: kimasplund (https://skillmd.com/u/kimasplund)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kimasplund/contacts

---


# 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:
```bash
node ~/projects/clawdbot-contacts/dist/cli.js <command> [options]
```

## Commands

### Add a contact
```bash
node ~/projects/clawdbot-contacts/dist/cli.js add --name "Jane Smith" --email "jane@acme.com" --org "Acme Corp"
```

### Search contacts (semantic)
```bash
node ~/projects/clawdbot-contacts/dist/cli.js search "engineers in San Francisco"
```

### List contacts
```bash
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
```bash
node ~/projects/clawdbot-contacts/dist/cli.js view <contact-id>
```

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

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

### Find by identifier
```bash
node ~/projects/clawdbot-contacts/dist/cli.js find email jane@example.com
node ~/projects/clawdbot-contacts/dist/cli.js find phone +1234567890
```

### Find duplicates
```bash
node ~/projects/clawdbot-contacts/dist/cli.js duplicates
```

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

### Create relationship
```bash
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
```bash
node ~/projects/clawdbot-contacts/dist/cli.js suggest
```

## Graph Queries (Neo4j)

### Find degrees of separation
Find how two contacts are connected:
```bash
# Via programmatic API
skill.findDegreesOfSeparation(contact1Id, contact2Id)
# Returns: { degrees: 2, path: [...] }
```

### Who knows who
Find all contacts who know a specific person:
```bash
# Via programmatic API
skill.whoKnows(contactId, depth?)
# Returns list of contacts connected to this person
```

### Mutual connections
Find contacts that both people know:
```bash
# Via programmatic API
skill.getMutualConnections(contact1Id, contact2Id)
# Returns list of shared connections
```

## Interaction Tracking (TimescaleDB)

### Record interactions
Track when you interact with contacts:
```typescript
// 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:
```typescript
// 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:
```typescript
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

```bash
# 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

```typescript
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();
```