Poppy-Local

A local-first relationship management assistant — manage contacts, interactions, and follow-up reminders with all data stored locally in SQLite.

Features

• Contacts Management — Full CRUD for contacts with relationship types, tags, and notes
• Richer Contact Profiles — Optional avatars, birthdays, anniversaries, and duplicate merge tools
• Interaction Tracking — Log calls, emails, meetings, and notes with any contact
• Smart Reminders — Set one-time or recurring reminders with automatic follow-up creation
• Relationship Health — Automatic tracking of relationship warmth based on interaction frequency
• Assistant Insights — AI-powered queue of contacts needing attention
• Import/Export — Full data portability with JSON, CSV, and vCard export/import
• Dashboard — Overview of your relationship network health

Quick Start

# Install dependencies
npm install

# Start the server
npm start

Open http://localhost:3456 in your browser.

Configuration

Environment Variable	Description	Default
PORT	Server port	3456
POPPY_DB_PATH	Full path to SQLite database	~/.poppy-local/poppy.db
POPPY_DATA_DIR	Directory for database	~/.poppy-local/

API Endpoints

Health

• GET /api/health — Server health check

Contacts

• GET /api/contacts — List contacts (supports q, tag, relationship_type, sort, order)
• GET /api/tags — List known tags with usage counts
• GET /api/contacts/duplicates — List potential duplicate contacts
• GET /api/contacts/:id — Get single contact with interactions and reminders
• POST /api/contacts — Create contact
• PUT /api/contacts/:id — Update contact
• POST /api/contacts/:id/merge — Merge another contact into the selected contact
• DELETE /api/contacts/:id — Delete contact
• GET /api/contacts/:id/vcard — Export a single contact as .vcf
• GET /api/contacts/vcard — Export all contacts as .vcf

Interactions

• GET /api/contacts/:id/interactions — List interactions for contact
• POST /api/contacts/:id/interactions — Add interaction
• PUT /api/interactions/:id — Update interaction
• DELETE /api/interactions/:id — Delete interaction

Reminders

• GET /api/reminders — List all reminders (supports show_completed)
• GET /api/contacts/:id/reminders — List reminders for contact
• POST /api/contacts/:id/reminders — Create reminder
• PUT /api/reminders/:id — Update reminder
• PATCH /api/reminders/:id — Complete/uncomplete reminder
• DELETE /api/reminders/:id — Delete reminder

Import/Export

• GET /api/export — Export all data as JSON
• POST /api/import — Import data (supports mode: 'merge' or 'replace')
• GET /api/contacts/export — Export contacts as CSV
• POST /api/contacts/import — Import contacts from CSV

Dashboard

• GET /api/stats — Dashboard statistics
• GET /api/assistant/brief — AI queue of contacts needing attention

Relationship Types

Type	Cadence
inner_circle	14 days
family	21 days
friend	30 days
colleague	30 days
professional	45 days
mentor	45 days
acquaintance	90 days

Development

# Run in development mode with auto-reload
npm run dev

Tech Stack

• Backend: Express.js + better-sqlite3
• Frontend: Vanilla JS SPA (no build required)
• Storage: SQLite with WAL mode

License

MIT