people-memories

name	people-memories
version	1.0.0
description	Personal CRM that captures notes about people from conversations. Store preferences, relationships, key facts, and reminders — recall them when you interact with that person again. Use this skill when tracking personal contacts, remembering details about people, building relationship context, or the user says "remember that [person]", "what do I know about [person]", or wants to track personal/professional contacts.
author	G-HunterAi
license	MIT
tags	["crm","people","contacts","memory","relationships"]
platforms	["all"]
category	communication
metadata	{"clawdbot":{"emoji":"👥"}}

People Memories Skill

Keep a searchable memory vault about people you interact with so your assistant can recall preferences, context, and key details instantly. Never lose track of important personal or professional relationships.

When to Use

• Remembering preferences, hobbies, or family details about personal contacts
• Tracking relationship context (how you met, what they do, shared interests)
• Building lightweight personal CRM data without heavy enterprise software
• Automating birthday/anniversary reminders
• Capturing "remember this about them" notes from conversations or voice input
• Exporting contact summaries as fact cards for reference

When NOT to Use

• Enterprise CRM: Use HubSpot or Salesforce for large sales pipelines and complex workflows
• General knowledge storage: Use agent-memory skill for facts unrelated to specific people
• Large contact databases: Use postgres-advanced skill with a proper backend for 10,000+ records
• Lead scoring and sales workflows: Use hubspot skill for qualification and pipeline management

Unique Feature: Voice Transcript Extension

The bundled extensions/people-memories extension listens to voice transcripts automatically. When you mention someone's details in conversation — "remember Alex likes cats" — the skill captures and stores it without extra typing. This is the lightest way to populate your people database over time.

Prerequisites

• Python 3.10+ or Node.js 18+ (depending on chosen runtime)
• Write access to data directory (configurable via $PEOPLE_MEMORY_PATH)
• Optional: cron or systemd timer for daily reminder digests

Quick Start

1. Initialize

# Set custom storage path (defaults to $XDG_DATA_HOME/people-memories/)
export PEOPLE_MEMORY_PATH=~/my-contacts/people.json

# Or use the default
python3 skills/people-memories/scripts/people_memory.py list

2. Add a person

python3 skills/people-memories/scripts/people_memory.py remember \
  --person Alex \
  --note "loves chai and late-night music practice" \
  --tags drinks,music

3. Recall details

python3 skills/people-memories/scripts/people_memory.py recall --person Alex --limit 5

4. Search across all people

python3 skills/people-memories/scripts/people_memory.py search --query coffee

5. Export a fact card

python3 skills/people-memories/scripts/people_memory.py summarize --person Alex
# or
python3 skills/people-memories/scripts/people_memory.py export \
  --person Alex \
  --format md \
  --out ~/Desktop/alex.md

Storage & Data Structure

Data is stored in JSON at $PEOPLE_MEMORY_PATH (or $XDG_DATA_HOME/people-memories/people.json by default):

{
  "people": {
    "alex": {
      "displayName": "Alex",
      "notes": [
        {
          "timestamp": "2026-01-29T12:05:00Z",
          "note": "Likes cats and doing late-night music practice",
          "source": "voice",
          "tags": ["pets", "music"]
        }
      ]
    }
  },
  "index": {
    "music": ["alex"],
    "cats": ["alex"],
    "pets": ["alex"]
  }
}

Key points:

• Names are normalized to lowercase keys but display with proper casing
• Each note includes timestamp, content, source (voice/text/manual), and tag metadata
• The index map enables fast keyword searches across all people
• Tags and keywords are extracted automatically for intelligent retrieval

CLI Commands

Use the bundled script to manage the database:

python3 skills/people-memories/scripts/people_memory.py <command> [options]

Command	Usage	Description
remember	--person NAME --note TEXT --tags TAG1,TAG2	Add a note about someone
recall	--person NAME --limit N	Fetch the latest N notes for a person
summarize	--person NAME	Print a fact card with tags, note counts, last update
search	--query KEYWORD	Find all people whose notes match a keyword
export	--person NAME --format md|json --out PATH	Export notes as Markdown or JSON
list	(no args)	Show all stored people and note counts
reminders	--days OFFSET --window DAYS --format message|json	Find upcoming birthdays/anniversaries

Voice Integration (Auto-Capture)

The extensions/people-memories extension monitors voice transcripts. When you naturally say phrases like:

• "Remember Alex likes cats"
• "Note that Pat works at TechCorp"
• "Don't forget: Jordan's birthday is next month"

The skill automatically runs the remember command and logs the note. Confirmations stay quiet unless you explicitly ask.

Reminders & Automation

Notes tagged with birthday, anniversary, or similar event tags trigger scheduled reminders. Run this daily (via cron) to get a digest:

python3 skills/people-memories/scripts/people_memory.py reminders \
  --days 0 \
  --window 7 \
  --format message

Then send the output to Slack, Discord, email, or any notification channel via webhook. Update your cron schedule or timer to suit your preference.

Example crontab entry

0 9 * * * python3 ~/skills/people-memories/scripts/people_memory.py reminders --days 0 --window 7 --format message | curl -X POST -d @- https://your-webhook.example.com

Directory Reference

people-memories/
├── scripts/
│   └── people_memory.py          # CLI tool for all database operations
├── extensions/
│   └── people-memories.js        # Voice transcript auto-capture handler
├── tests/
│   ├── test_remember.py
│   ├── test_search.py
│   └── test_export.py
├── SKILL.md                       # This file
├── README.md                      # Extended documentation
├── LICENSE                        # MIT license
└── CHANGELOG.md                   # Version history

Scripts Directory

• people_memory.py: Main CLI tool. Handles all database CRUD, searching, exports, and reminder scheduling.

Extensions Directory

• people-memories.js: Voice integration. Listens for transcript events and auto-parses "remember …" phrases.

Error Handling

Error	Cause	Solution
FileNotFoundError: people.json not found	Data file doesn't exist yet	Run any command (e.g., list) to initialize
JSONDecodeError: Expecting value	Corrupt JSON file	Restore from backup or delete and reinitialize
PermissionError: [Errno 13]	No write access to storage path	Check file permissions or change $PEOPLE_MEMORY_PATH
Duplicate entry for [person]	Name collision with different casing	Use consistent capitalization when adding notes
Tag index out of sync	Index lost during crash	Rebuild via python3 scripts/people_memory.py rebuild-index

Works Well With

• agent-memory — General-purpose facts and context storage. Use people-memories for personal relationships, agent-memory for everything else.
• hubspot — Enterprise CRM. Sync high-value contacts to HubSpot for sales workflows.
• email-automation — Personalized outreach. Reference person preferences when drafting emails.
• postgres-advanced — Scalable backend. Move to PostgreSQL when you outgrow the JSON file (10,000+ records).
• apple-calendar — Integrate birthday/anniversary reminders with your calendar.

Key Enhancements in This Version

1. Smart Indexing — Tags and keyword extraction keep lookups fast even as your people database grows.
2. Summaries & Exports — Generate fact cards in Markdown or JSON for sharing or archival.
3. Voice Integration — Auto-capture from conversation transcripts; no typing required.
4. Structured Data — Normalized names, timestamps, and tag metadata make the database consumable by other tools.
5. Flexible Storage — Configurable data path via environment variable; works on any system with write access.

Next Steps & Nice-to-Haves

• Add optional confirmation responses ("Noted, saved for Alex.") via runtime messaging
• Build a simple watch UI (web or terminal) that previews and updates the latest people cards
• Implement cross-agent sync for shared contact databases
• Add optional encryption for sensitive notes
• Integrate priority filters ("top contacts", "recent interactions")

Contributing

Found a bug or have an improvement? Contributions welcome. Please ensure tests pass:

python3 -m pytest tests/ -v

---

License: MIT (see LICENSE file) Author: G-HunterAi