Relationships are your most valuable asset, but they're also the hardest thing to keep track of. Contacts scattered across Apple, Google, and LinkedIn. Names you recognize but can't quite place. Introductions you meant to follow up on but never did. Contrack fixes that.
Sync your contacts from every source into one unified network with automatic dedupe across platforms. Let AI enrichment research your connections across the web and fill in the context you never had time to enter. Behind the scenes, proactive intelligence keeps watch over your network and nudges you to reconnect before important relationships go quiet.
|
Get a complete picture of every connection instantly. View their interaction history, personal details, and relationship context all in one beautifully designed profile card. Built with a timeline architecture featuring @mention network weaving, AI briefings, Ghost entity extraction, multi-value fields, and data age halos. |
|
|
Navigate your entire network at lightning speed without ever touching your mouse. Instantly search contacts, log new notes, or jump to specific views using keyboard shortcuts. A GitHub-style command center featuring faceted filters ( |
|
|
Never let an important connection slip through the cracks again. This proactive dashboard automatically tracks your network health and suggests who you should reach out to next. Runs on an automated scoring engine (frequency × recency × depth) to power action item swimlanes and generate daily AI insights. |
|
|
Visualize your network geographically to plan trips or coordinate local meetups. See exactly where your connections are clustered around the globe at a glance. Interactive cluster map powered by React Leaflet, utilizing Mapbox and Nominatim for accurate backend geocoding and detail overlays. |
|
|
Query your CRM using natural language just like you're talking to an assistant. Ask complex questions like "Who do I know in San Francisco that works in tech?" and get precise answers. Driven by a Hybrid RAG pipeline combining FTS5 + local vector KNN via Reciprocal Rank Fusion, with instant retrieval (<15ms) and streaming AI-enriched reasoning. |
|
|
Keep your database impeccably clean with an automated assistant that spots duplicate contacts for you. Review merged suggestions quickly with an intuitive swipe interface. Multi-pass engine utilizing Double Metaphone phonetic matching, Levenshtein distance, E.164 phone normalization, and 768-dim AI embeddings with one-click undo. |
|
- Magic Paste — Paste unstructured text, AI extracts a structured contact
- Multi-Provider AI — Gemini (default), OpenAI, or Anthropic via provider-agnostic adapters
- Smart Router — Automatic Gemini model selection (Lite/Flash/Pro) per use case
- Batch Enrichment — AI-powered web research to hydrate contact profiles
- Custom Lists — Unlimited groups with icons, drag-to-reorder, bulk membership
- Doc2Query — Write-time search expansion via AI for better recall
- Ghost Detection — Passive entity extraction from notes creates ghost contacts
- @Mentions — Bi-directional relationship graph via Tiptap rich text
- AI Cache Telemetry — Multi-tiered LRU caching with full transparency dashboard
- Enterprise Virtualization — <20ms page transitions for 100K+ contacts
- Quick Note (
Cmd+Shift+I) — Log interactions from anywhere - Link Unfurling — Zero-Chromium OpenGraph extraction via Cheerio
- Logo Proxy — Heuristic company logo discovery with local caching
Try it locally in under 60 seconds.
The easiest way to run Contrack is via Docker Compose. This ensures all native dependencies (like sqlite-vec) work perfectly.
git clone https://github.com/arvarik/contrack.git
cd contrack
cp .env.example .env
# Add your API key (GEMINI_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY)
docker-compose up -dOpen http://localhost:3210. Data is automatically persisted to ./data.
git clone https://github.com/arvarik/contrack.git
cd contrack
npm install
cp .env.example .env
# Add your API key (GEMINI_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY)
npm run devOpen http://localhost:3210. The server auto-initializes the database, loads embedding models, and starts background tasks.
Seed data: Run
npm run seedto populate with demo contacts.
| Domain | Technology |
|---|---|
| Frontend | React 19, Vite 6, React Query v5, Tailwind CSS v4, Tiptap, Motion |
| Backend | Node.js 22, Express, TypeScript (tsx), Zod validation |
| Database | SQLite3 (WAL mode), Drizzle ORM, FTS5, sqlite-vec |
| AI | Gemini / OpenAI / Anthropic (provider-agnostic adapter pattern) |
| Search | Hybrid RAG: FTS5 keyword + 384-dim local vector KNN (Transformers.js) |
| Mapping | React Leaflet + Leaflet Cluster, Mapbox/Nominatim geocoding |
| Testing | Vitest — 180 tests, <600ms |
Full documentation lives in the docs/ directory:
| Guide | Description |
|---|---|
| Getting Started | Installation, first boot, scripts, keyboard shortcuts |
| Configuration | Environment variables, AI provider setup, tier tuning |
| Architecture | System overview, data flow, schema, caching |
| API Reference | Complete REST API with curl and JavaScript examples |
| Feature | Guide |
|---|---|
| Contact Management | docs/features/contact-management.md |
| Command Palette | docs/features/command-palette.md |
| AI Search | docs/features/ai-search.md |
| Deduplication | docs/features/deduplication.md |
| Pulse Dashboard | docs/features/dashboard-pulse.md |
| Map View | docs/features/map-view.md |
| Lists | docs/features/lists.md |
| Variable | Description | Default |
|---|---|---|
AI_PROVIDER |
LLM provider: gemini, openai, anthropic |
gemini |
GEMINI_API_KEY |
Gemini API key | — |
OPENAI_API_KEY |
OpenAI API key | — |
ANTHROPIC_API_KEY |
Anthropic API key | — |
AI_TIER |
FREE or PAID rate limit profile |
FREE |
PORT |
Express listening port | 3210 |
MAPBOX_API_KEY |
Mapbox geocoding (optional, higher accuracy) | — |
See Configuration Guide for full details.
graph TD
subgraph Frontend ["UI Layer — React 19 / Vite"]
RQ["React Query v5"] --> TW["Tailwind v4 'No-Line' UI"]
TW --> TT["Tiptap Editor + Cheerio Previews"]
TT --> Map["React Leaflet Geospatial"]
end
subgraph Backend ["Node.js Express Server"]
EX["Express Router"] --> SVC["Service Layer"]
SVC --> AI["AI Service + Smart Router"]
SVC --> SRCH["Ask Contrack v3 Spotlight"]
SVC --> DDP["Dedupe Engine"]
SVC --> REL["Relationship Scoring"]
end
subgraph Storage ["Persistence — Local-First"]
SQL[("SQLite3 WAL Mode")]
DZ["Drizzle ORM"] --> SQL
FTS["FTS5 Search Index"] --- SQL
VEC["sqlite-vec Embeddings"] --- SQL
end
subgraph AILayer ["AI Infrastructure"]
SR["Smart Router"] --> Adapters["Gemini / OpenAI / Anthropic"]
SR --> QT["Quota Tracker + Parallel Queue"]
LE["Transformers.js Local"] --> VEC
end
Frontend <===>|"JSON REST + UUID Tracing"| Backend
AI <===>|"Smart Router model selection"| AILayer
Backend <===>|"Drizzle ORM"| Storage
See CONTRIBUTING.md for development standards, code style, and PR process.
This project is licensed under the GNU Affero General Public License v3.0. This means you can use, modify, and distribute the code, but any modified versions — including those offered as a network service (SaaS) — must also be open-sourced under AGPL v3.