ContactKiller

Kill contact chaos. Keep every relationship.

ContactKiller is an experimental, open-source contact-reconciliation project for people whose address books have become accidental CRMs. The public tree combines a working SurrealDB-backed prototype, read-only local research tools, and an experimental ActiveGraph domain pack. Its target architecture preserves source evidence, proposes conservative identity matches, and keeps risky provider changes behind explicit human approval; the current web importer does not yet deliver those guarantees end to end.

Explore the open-source launch site

[!WARNING] ContactKiller is not a production-safe bulk deletion tool. Use synthetic data while developing. Never point an unreviewed build at a real address book or CRM.

Why this exists

One person can appear as five unrelated records:

• iCloud remembers a name and phone number;
• a personal Google account has an older email;
• a work Google account contains an imported lead card;
• a CRM still classifies the person as a prospect; and
• WhatsApp shows only a number because the phone cannot resolve the right card.

Conventional sync chooses a winner and overwrites the rest. ContactKiller's target workflow treats the address book as a distributed system: capture every observation, keep account boundaries visible, explain how an identity proposal was assembled, and preview cleanup before touching a provider.

What is different

Principle	Current public evidence and limitation
Evidence before mutation	The DuckDB forensic tool records manifests and observations, and the ActiveGraph pack models source evidence. The web prototype still writes mutable contacts directly and does not retain every raw provider observation.
Conservative identity	ActiveGraph proposes exact normalized email or E.164 matches. A complete identity engine is not connected to the web prototype.
Replayable decisions	The ActiveGraph pack includes event lifecycle and replay tests. The SurrealDB-backed prototype is not yet a projection of that history.
Approval at the boundary	Approval and mutation-plan objects are modeled. No production provider-write executor ships.
Account isolation	The prototype records provider links and ContactKiller tenant ownership, but cannot distinguish two accounts from the same provider for one user. Multi-account provenance and full tenant-isolation proof remain acceptance gates.

Project status

The repository is intentionally candid about maturity:

Area	Status	Notes
Contact explorer and CRUD API	Implemented prototype	SurrealDB-backed interface and routes; not production-proven.
Google Contacts	Experimental	Read-only OAuth scope and one-way import with exact-identifier matching; access tokens refresh from the stored refresh token (not yet verified against live Google); write-back is not implemented.
iCloud	Experimental	Manual vCard import under the same exact-match rules as Google (UID, email, valid phone); no CardDAV sync.
Mesh	Research connector	Bounded, read-only snapshot path into owner-only local storage.
ActiveGraph	Experimental foundation	Typed reconciliation objects, approval routing, replay, and runtime tests. Not the live production authority.
SurrealDB	Implemented prototype persistence	The web prototype stores users, contacts, conflicts, sync logs, and encrypted OAuth tokens in SurrealDB with owner-scoped permissions. The provenance, observation, and replay model remains a documented target.
FalkorDB	Community extension	No ContactKiller adapter ships today; disposable projection and benchmark contributions are welcome.
Provider mutations	Planned	The data model exists; no production-safe executor is available.

See Capabilities and Integrations for the detailed matrix.

Target reconciliation flow

Apple / Google / CRM / Mesh / messaging evidence
                         │
                         ▼
       immutable source observations + manifests
                         │
                         ▼
        normalization with field-level provenance
                         │
                         ▼
          identity proposals and confidence rules
                         │
               ┌─────────┴─────────┐
               ▼                   ▼
         canonical projection   review queue
                                   │
                                   ▼
                         approval-gated change plan
                                   │
                                   ▼
                         bounded provider mutation

The public tree does not implement this flow end to end. Today, Google and iCloud imports fill empty fields on an exactly matched contact and file conflicts for differences, rather than retaining a separate source observation. The diagram is an architecture contract and acceptance target, not a production-readiness claim.

The target architecture separates three responsibilities:

• SurrealDB persists the web prototype today (mutable contacts, accounts, conflicts, encrypted provider tokens) and is the target for a canonical boundary covering evidence, records, operations, and graph relations.
• ActiveGraph supplies typed behavior, tasks, approval routing, event history, replay, and fork/diff experiments.
• FalkorDB is a potential disposable projection seam for community experiments—not a second source of truth.

Read Architecture, ActiveGraph, SurrealDB, and the FalkorDB projection RFC.

Repository layout

activegraph-contactkiller/   ActiveGraph domain pack and tests
docs/                        Public architecture, safety, and contributor guides
examples/synthetic/          Synthetic contact fixtures and failure cases
scripts/                     Read-only snapshots and disposable forensic tooling
web/                         Next.js reconciliation prototype
website/                     Public open-source launch site

Quick start

Prerequisites

• Bun 1.4 or newer
• Node.js 20.9 or newer
• Python 3.11 or newer for the ActiveGraph pack
• DuckDB CLI 1.5.5 or newer for the forensic-cache tool and its integration tests
• Docker (or a SurrealDB 3.x server) for the web prototype's local database

Web prototype

cd web
cp .env.local.example .env.local      # placeholders only; set your own encryption key
cp compose.env.example compose.env    # then set a local SurrealDB root password
bun install
docker compose --env-file compose.env up -d --wait   # SurrealDB on 127.0.0.1:8000
# For the first account only: set CONTACTKILLER_ALLOW_SIGNUP=true in .env.local
bun run db:migrate                                   # apply migrations, sync the sign-up switch
bun run dev

Open http://localhost:3000/login, create a local account, and import a synthetic vCard from Settings. .env.local needs CONTACTKILLER_TOKEN_ENCRYPTION_KEY; generate one with openssl rand -base64 32. To exercise Google import, create a development OAuth web client and register http://localhost:3000/api/auth/google/callback (or the matching NEXT_PUBLIC_APP_URL) as its redirect URI.

Sign-up is off by default and is enforced inside SurrealDB, not only in the app: the database's sign-up clause refuses to run unless setting:signup is on, and bun run db:migrate sets it from CONTACTKILLER_ALLOW_SIGNUP. To create the first user, set the variable to true, run bun run db:migrate, restart the dev server, sign up on /login, then set it back to false and run bun run db:migrate again. Accounts, sessions, and row-level ownership are likewise enforced by SurrealDB itself; the web app never holds database root credentials. Use synthetic fixtures and a development database; do not reuse production credentials or personal contact exports, and never expose the SurrealDB port beyond loopback. See Development for tests and troubleshooting.

ActiveGraph pack

cd activegraph-contactkiller
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[test]'
pytest

Read-only local research tools

# Plan a bounded Mesh read without contacting the service.
bun scripts/mesh-mcp-snapshot.ts --name "Maya Chen"

# Initialize the ignored, disposable DuckDB forensic cache.
bun scripts/forensic-cache.ts init
bun scripts/forensic-cache.ts summary

Mesh execution requires your own authenticated connector. Raw snapshots are written under ignored .local/ storage with owner-only permissions. They must never be committed or attached to an issue.

Safety rules for contributors

1. Use only synthetic people, phone numbers, emails, events, and source payloads in public fixtures.
2. Keep adapters read-only by default.
3. Preserve source bytes and provenance before proposing normalization or identity changes.
4. Never merge on names alone.
5. Put every external write behind an explicit approval object and a bounded batch.
6. Include replay, idempotency, tenant-isolation, and rollback tests for persistence changes.

Read Privacy and data safety before opening an issue or pull request.

Contributing

Useful first contributions include:

• a read-only source adapter;
• a synthetic duplicate or missing-name scenario;
• deterministic normalization and identity rules;
• replay and reconciliation benchmarks;
• graph visualizations;
• a disposable FalkorDB projection; and
• stronger provider-write safety gates.

Start with CONTRIBUTING.md, the development guide, and the testing guide. Community decisions follow GOVERNANCE.md.

Security

Do not report vulnerabilities through a public issue. Follow SECURITY.md. Never include real contact exports, OAuth tokens, account identifiers, phone numbers, or customer data in a report.

License

Copyright 2026 ContactKiller contributors.

Licensed under the Apache License 2.0. See NOTICE and third-party notices for attribution and dependency-license boundaries.