BlueSky0329/mama-message

Mama Message

In one sentence: Turn a family chat log into one number, one label, and one message you can actually send.

The user doesn't need AI to tell them their mom loves them. They need three things: ① a number they've never counted ("You replied 'mm-hmm' 38 times"); ② a social scaffold ("The app says I owe you a call" is easier to send than "I miss you"); ③ an image they can share (sharing guilt = sharing conscience). Every module in the report serves these three things. It's not psychological analysis—mom doesn't need an attachment style.

Process: get the logs → confirm the two people → convert to messages.json → stats.py does the math → ask three questions → write the text → render.py produces the report and two cards. Practice mode and comparison mode are optional add-ons.

Support files are in this directory. Refer to them as needed:

• references/metrics.md — how each number is calculated (if the user asks "how is this computed," point here).
• references/types.md — 10 types for her + 6 types for you + 5-tier ratings.
• references/dictionary.md — base dictionary and generation rules for the jargon translation table.
• references/writing-rules.md — rules for the narrative text, anti-AI blacklist, and when to hold back.
• references/report-template.md — report template and narrative.json fields.
• references/practice.md — practice mode.
• references/export-guide.md — platform-specific export/screenshot guide (if the user asks "how do I export," point here; recommend screenshots first).
• scripts/ — parse_export.py validate.py stats.py render.py compare.py redact.py. Only standard library, no internet.
• assets/ — HTML templates for the report and two cards.

---

Privacy (above all else)

• Read only the screenshots/files the user gives. Do not decrypt the WeChat database. Do not connect to the internet. Do not store logs anywhere the user hasn't explicitly requested. Script artifacts (messages.json / stats.json / reports/) stay in the current directory. Tell the user where they are and that they can delete them anytime.
• The report does not reproduce the full original text, only short quotes. For transfers (money), record only the count, never the amount.
• If the user hasn't redacted sensitive info: remind them once that "you can first use scripts/redact.py to blur names and sensitive content." Do not repeat.
• If the user asks "will this leak?": be honest — whatever tool you're running this in, the logs are sent to that tool's servers; the scripts themselves send nothing.

---

Step 1: Get the logs

First ask if they have WeChat on their computer. An export file is far better than screenshots — you can get half a year's logs at once, with complete timestamps, without having to scroll screen by screen and have AI transcribe each one (dozens of screenshots only cover a few hundred messages and are easy to mis-transcribe).

Priority:

1. Export file (best): Use WeFlow (WeChat 4.0+) or Liuhen / WeChatMsg / PyWxDump (WeChat 3.x) to export the chat with this person as JSON / CSV / TXT. scripts/parse_export.py can handle these. Specific platform steps are in references/export-guide.md. Answer only the relevant section based on the user's situation, don't read it all at once.
2. Screenshots (fallback): Use this when they only have a phone, use a Mac, or don't want to install anything on their computer. Works with WeChat / QQ / SMS. Android can use long screenshots.
3. Pasted text directly.

If the user hasn't given anything and says "I want to analyze chats with my mom," first ask:

Do you have WeChat installed on your computer? If so, I can teach you how to export your chat history—it'll grab the full half-year at once, much more accurate than screenshots. If you only have your phone, that's fine too—just take screenshots, starting from the most recent and scrolling up, one screen per screenshot.

When taking the screenshot route, add: Adjacent screenshots should ideally overlap by 1-2 messages; 10-20 screenshots can produce a report, but 30-40 give stable numbers; names and sensitive content can be redacted first.

Step 2: Identify the two people

• Which side is the user, and which is the family member. In WeChat screenshots, the green bubble on the right is the user, the white bubble on the left is the other person. In export files, check the sender field. If unclear, ask once.
• Who is the other person, what to call them, and whether to use "she" or "he." If the user says "my mom" use "mom/she"; if they say "my dad" use "dad/he"; if they say "grandma" use "grandma/she." The report title, type names, and holidays (Mother's Day/Father's Day) should all match. The skill is called "Mama Message," but half the users will use it for their dad.
• Birthdays (optional): theirs and the user's (MM-DD), used for the holiday scoreboard and countdown.

Step 3: Convert to a dataset

The target is messages.json:

{"me": "Me", "her": "Mom", "her_pronoun": "she", "source": "screenshots",
 "messages": [
   {"ts": "2026-05-12T21:03:14", "sender": "her", "type": "text", "content": "Had dinner yet?", "dur": null},
   {"ts": null, "sender": "me", "type": "text", "content": "Yes", "dur": null},
   {"ts": "2026-05-12T21:05:00", "sender": "her", "type": "voice", "content": "", "dur": 23}
 ]}

type ∈ text / voice / image / video / sticker / transfer / link / call_voice / call_video / recall / location / file. For voice and calls, put the duration in seconds in dur. For link, put the title in content. For transfers, content is only "transfer" — no amount.

Screenshot path: transcribe one by one. Rules:

• For overlapping messages between adjacent screenshots, record each message only once, aligned by content and position, no guessing.
• WeChat only shows timestamps when there's a significant gap. If a timestamp exists, fill in ts; if not, set ts to null (the script will count these but exclude them from time calculations). Do not fabricate timestamps for messages that don't have them.
• For voice, record the duration in seconds; for stickers, use sticker (for built-in emojis like [Rose], put the description in content); for transfers, record only the count.
• If screenshots are too blurry or clearly missing a section: transcribe what you can see and note it in the data description. Do not fabricate data to make the report look better.
• After transcribing, run python scripts/validate.py messages.json: it checks format, chronological order, suspected duplicates (overlapping messages not removed), transfers with amounts, and prints the total count and time range. Show this summary to the user for confirmation before computing.

Export path (preferred):

python scripts/parse_export.py export_file --her "name_in_log" --call "mom" --out messages.json
# If you don't know what the other person is called in the log: run without --her first — the script will list the names
# If the log spans several years, add --since 2026-01-01 (or --last-days 180) to take only the recent segment for a more focused report

For WeFlow exports, choose JSON format (it includes the isSend field for sender marking, so you don't need to fill in --her; TXT and weclone CSV are also recognized but contain less info). Tools like WeFlow and Liuhen export the full chat history, which may have tens of thousands of messages. If the span is too long, the report gets diluted (e.g., "she asks about this most often" becomes an average over three years). The default recommendation is to take only the last 6–12 months. Note: WeFlow does not export voice duration, so the "longest voice" metric will be missing — that's normal.

Step 4: Do the math

python scripts/stats.py messages.json --out stats.json --today 2026-08-30 --her-birthday 10-20 --my-birthday 06-03

The terminal prints a summary; stats.json contains all numbers. Every number in the report comes from here, no manual calculation. Definitions are in references/metrics.md. Copy any warnings from stats.json verbatim into the data notes at the end of the report.

If you can't run the script (e.g., in a dialogue-only environment): manually calculate the core metrics from metrics.md — who initiates first, median response time, short replies, unanswered messages, most frequent questions, time distribution — and mark the rest as "requires an exported log to compute."

Step 5: Ask three questions

After computing, first show the user the three indices and the identification results (this is the most interesting part, do it first), then ask:

Before I write the final section, I'd like to ask you three things — you can skip any of them: ① How long since you've been home? ② Is anything going on with her recently — health, family? ③ What did you last talk about on the phone?

Step 6: Write the text

Follow references/writing-rules.md. What to write:

• One pithy sentence for each of the three indices (a number + a detail)
• One sentence each for her type and your type (quote original message + number)
• 6–10 entries from the jargon translation table (things she actually said, see dictionary.md)
• What she transferred to you: one insight (what was transferred, how it relates to something the user said)
• What she really meant to say: 120–220 words
• Three things to do tonight
• Three help-you-reply suggestions
• Three phone call openers
• One message you can send her directly: 60–100 words, with a specific time

First, present the full report in the dialogue using the Markdown template from report-template.md, while also writing the text into narrative.json.

Step 7: Output the report and cards

python scripts/render.py stats.json narrative.json --out reports/

Three files: the full report, a "family bill" card (for the user to share), and a card to send to her. Tell the user to open them in a browser and screenshot them. Cards are portrait-oriented. The card to send to her is the real output of this product — if you recommend only one, recommend this one.

---

Optional add-ons

Practice mode (user says "practice," "let's practice," "play the role of my mom") → read references/practice.md. The AI chats with the user in her style for 10 rounds. If the user replies "mm-hmm," flag it immediately and score it at the end. Requires ≥ 40 messages.

Comparison mode (user says "compare with a friend," "who do I reply to faster") → ask the user to provide another set of screenshots with a friend, follow the same process to produce friend-stats.json, then:

python scripts/compare.py stats.json friend-stats.json --labels "Your Mom" "Friend" --mode friend

The conclusion is one line: "You reply to your friend in 3 minutes, but you reply to your mom in 4 hours 12 minutes — that's 84 times slower."

Partiality report (user gives both parents' logs) → --labels "Mom" "Dad" --mode papa.

Cards only (user says "make a card," "give me an image") → if stats and narrative already exist, just render; otherwise, follow the full process — the cards are a natural output.

Help you reply (user says "help me reply to her") → only write replies for the "unanswered" list and three call openers; do not produce a full report.

---

When to hold back

Read from the logs and the user's tone — you don't need them to say it explicitly. Details are at the end of writing-rules.md. Key points:

• If there are fewer than 20 messages: only output numbers, no interpretation.
• If the logs contain conflict, insults, controlling behavior, or persistent marriage/financial pressure: describe both sides' patterns neutrally, don't assume who's right or wrong, and remove the "three things to do tonight" and "message to send to her."
• If the user is upset, the family is strained, or they mention their mom has passed away: respond to the person first, ask if they want to continue; if they do, remove the ratings.
• If the analysis is for someone else: switch to third person.

Under no circumstances label the user. "Short reply" is not "dismissive," "unanswered" is not "unfilial," the ratings are a chapter title, not a verdict.

---

Pre-publish checklist

• Every number can be found in stats.json
• Every judgment in "what she really meant to say" can be traced back to an original message or a number
• The type sentence quotes an original message
• The message to send to her has a specific time
• The entire text has no blacklisted phrases (no "dismissive," "unfilial," "should"), no exclamation marks
• The pronouns and titles match ("she"/"he", holiday selected correctly)
• No transfer amounts are written
• The data notes include screenshot gaps and the count of untimestamped messages