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