alexa-ai 2.1.1

package/src/repositories/MemoryRepository.js

@@ -0,0 +1,215 @@
+'use strict';
+
+/**
+ * MemoryRepository
+ * ----------------
+ * Long-term facts about a person.
+ *
+ * Design rule: memories are keyed to `user_id` ONLY — never to a group. That
+ * is what makes Alexa recognise the same person's details in a DM and in any
+ * group. `UNIQUE (user_id, key)` means re-learning a key
+ * (e.g. the user moves city) overwrites instead of piling up duplicates.
+ */
+class MemoryRepository {
+    /** @param {import('../db/Database')} db */
+    constructor(db) {
+        this.db = db;
+    }
+
+    /** Reserved keys that must never be stored as "facts". */
+    static BLOCKED_KEYS = new Set(['', 'null', 'undefined', 'none', 'n/a', 'memory', 'key', 'value']);
+
+    static MAX_KEY = 64;
+    static MAX_VALUE = 512;
+
+    /**
+     * Insert or update one fact.
+     * @param {number} userId
+     * @param {string} key
+     * @param {string} value
+     * @param {object} [opts]
+     * @param {string} [opts.source='auto']
+     * @param {string} [opts.learnedIn]
+     * @param {number} [opts.confidence=1]
+     * @param {Date|null} [opts.expiresAt]
+     * @returns {Promise<object|null>}
+     */
+    async remember(userId, key, value, opts = {}) {
+        const normalisedKey = MemoryRepository.normalizeKey(key);
+        const normalisedValue = MemoryRepository.normalizeValue(value);
+        if (!userId || !normalisedKey || !normalisedValue) return null;
+
+        return this.db.one(
+            `INSERT INTO wa_memories (user_id, key, value, source, learned_in, confidence, expires_at)
+             VALUES ($1, $2, $3, $4, $5, $6, $7)
+             ON CONFLICT (user_id, key) DO UPDATE
+               SET value      = EXCLUDED.value,
+                   source     = EXCLUDED.source,
+                   learned_in = COALESCE(EXCLUDED.learned_in, wa_memories.learned_in),
+                   confidence = EXCLUDED.confidence,
+                   expires_at = EXCLUDED.expires_at,
+                   updated_at = NOW()
+             RETURNING *`,
+            [
+                userId,
+                normalisedKey,
+                normalisedValue,
+                opts.source || 'auto',
+                opts.learnedIn || null,
+                typeof opts.confidence === 'number' ? opts.confidence : 1.0,
+                opts.expiresAt || null,
+            ]
+        );
+    }
+
+    /**
+     * Store many facts at once (one round-trip, single transaction).
+     * @param {number} userId
+     * @param {Record<string,any>} facts
+     * @param {object} [opts]
+     * @returns {Promise<object[]>}
+     */
+    async rememberMany(userId, facts, opts = {}) {
+        if (!userId || !facts || typeof facts !== 'object') return [];
+
+        const entries = Object.entries(facts)
+            .map(([k, v]) => [MemoryRepository.normalizeKey(k), MemoryRepository.normalizeValue(v)])
+            .filter(([k, v]) => k && v);
+
+        if (!entries.length) return [];
+
+        // Cap per-turn writes so a malformed model reply can't flood the table.
+        const limited = entries.slice(0, 12);
+
+        return this.db.transaction(async (client) => {
+            const saved = [];
+            for (const [key, value] of limited) {
+                const { rows } = await client.query(
+                    `INSERT INTO wa_memories (user_id, key, value, source, learned_in, confidence)
+                     VALUES ($1, $2, $3, $4, $5, $6)
+                     ON CONFLICT (user_id, key) DO UPDATE
+                       SET value      = EXCLUDED.value,
+                           source     = EXCLUDED.source,
+                           learned_in = COALESCE(EXCLUDED.learned_in, wa_memories.learned_in),
+                           updated_at = NOW()
+                     RETURNING *`,
+                    [
+                        userId,
+                        key,
+                        value,
+                        opts.source || 'auto',
+                        opts.learnedIn || null,
+                        typeof opts.confidence === 'number' ? opts.confidence : 1.0,
+                    ]
+                );
+                saved.push(rows[0]);
+            }
+            return saved;
+        });
+    }
+
+    /**
+     * All live memories for a user (expired rows filtered out).
+     * @param {number} userId
+     * @param {number} [limit=25]
+     */
+    async getAll(userId, limit = 25) {
+        if (!userId) return [];
+        return this.db.many(
+            `SELECT * FROM wa_memories
+              WHERE user_id = $1
+                AND (expires_at IS NULL OR expires_at > NOW())
+              ORDER BY updated_at DESC
+              LIMIT $2`,
+            [userId, limit]
+        );
+    }
+
+    /** Plain `{key: value}` map for prompt injection. */
+    async getMap(userId, limit = 25) {
+        const rows = await this.getAll(userId, limit);
+        const map = {};
+        for (const row of rows) map[row.key] = row.value;
+        return map;
+    }
+
+    async get(userId, key) {
+        const normalisedKey = MemoryRepository.normalizeKey(key);
+        if (!userId || !normalisedKey) return null;
+        return this.db.one(
+            `SELECT * FROM wa_memories
+              WHERE user_id = $1 AND key = $2
+                AND (expires_at IS NULL OR expires_at > NOW())`,
+            [userId, normalisedKey]
+        );
+    }
+
+    async forget(userId, key) {
+        const normalisedKey = MemoryRepository.normalizeKey(key);
+        if (!userId || !normalisedKey) return false;
+        const { rowCount } = await this.db.query(
+            'DELETE FROM wa_memories WHERE user_id = $1 AND key = $2',
+            [userId, normalisedKey]
+        );
+        return rowCount > 0;
+    }
+
+    async forgetAll(userId) {
+        if (!userId) return 0;
+        const { rowCount } = await this.db.query('DELETE FROM wa_memories WHERE user_id = $1', [userId]);
+        return rowCount;
+    }
+
+    /** Bump usage counters for memories that were injected into a prompt. */
+    async markUsed(userId, keys) {
+        if (!userId || !Array.isArray(keys) || !keys.length) return;
+        await this.db.query(
+            'UPDATE wa_memories SET hit_count = hit_count + 1 WHERE user_id = $1 AND key = ANY($2::text[])',
+            [userId, keys]
+        );
+    }
+
+    /** Housekeeping: drop expired rows. */
+    async pruneExpired() {
+        const { rowCount } = await this.db.query(
+            'DELETE FROM wa_memories WHERE expires_at IS NOT NULL AND expires_at <= NOW()'
+        );
+        return rowCount;
+    }
+
+    // ------------------------------------------------------------ helpers ---
+
+    /** `Favourite Food ` -> `favourite_food` */
+    static normalizeKey(key) {
+        if (key == null) return null;
+        const cleaned = String(key)
+            .trim()
+            .toLowerCase()
+            .replace(/[\s-]+/g, '_')
+            .replace(/[^a-z0-9_]/g, '')
+            .replace(/_{2,}/g, '_')
+            .replace(/^_|_$/g, '');
+        if (!cleaned || MemoryRepository.BLOCKED_KEYS.has(cleaned)) return null;
+        return cleaned.slice(0, MemoryRepository.MAX_KEY);
+    }
+
+    /** Objects/arrays are JSON-stringified so nested model output still stores. */
+    static normalizeValue(value) {
+        if (value == null) return null;
+        let str;
+        if (typeof value === 'object') {
+            try {
+                str = JSON.stringify(value);
+            } catch {
+                return null;
+            }
+        } else {
+            str = String(value);
+        }
+        str = str.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '').trim();
+        if (!str || MemoryRepository.BLOCKED_KEYS.has(str.toLowerCase())) return null;
+        return str.slice(0, MemoryRepository.MAX_VALUE);
+    }
+}
+
+module.exports = MemoryRepository;

package/src/repositories/UserRepository.js

@@ -0,0 +1,275 @@
+'use strict';
+
+const JidParser = require('../utils/JidParser');
+const { ValidationError } = require('../core/errors');
+
+/**
+ * UserRepository
+ * --------------
+ * Users and groups. One `wa_users` row per person, keyed by canonical jid, so
+ * the same human is recognised in a DM and in every group.
+ */
+class UserRepository {
+    /** @param {import('../db/Database')} db */
+    constructor(db) {
+        this.db = db;
+    }
+
+    /**
+     * Find-or-create a user, refreshing `last_seen_at` and push name.
+     * @param {string} rawJid
+     * @param {object} [info]
+     * @param {string} [info.pushName]
+     * @param {object} [info.metadata]
+     * @returns {Promise<object>} user row
+     */
+    async upsertUser(rawJid, info = {}) {
+        const parsed = JidParser.parse(rawJid);
+        if (!parsed.valid || parsed.isGroup) {
+            throw new ValidationError(`Invalid user jid: ${JSON.stringify(rawJid)}`);
+        }
+
+        const pushName = UserRepository._clean(info.pushName, 128);
+        const metadata = info.metadata && typeof info.metadata === 'object' ? info.metadata : {};
+
+        // If this jid is already a known ALIAS of somebody, that person is who
+        // is writing — creating a second row here is exactly the bug that made
+        // Alexa forget people between a DM and a group.
+        const known = await this.db.one(
+            `SELECT u.* FROM wa_users u
+               JOIN wa_user_identities i ON i.user_id = u.id
+              WHERE i.jid = $1
+              LIMIT 1`,
+            [parsed.jid]
+        );
+        if (known) {
+            await this.db.query('UPDATE wa_user_identities SET last_seen_at = NOW() WHERE jid = $1', [parsed.jid]);
+            return (await this.touch(known.id, { pushName, metadata })) || known;
+        }
+
+        // COALESCE keeps a previously-known push name if this event lacks one.
+        const user = await this.db.one(
+            `INSERT INTO wa_users (jid, jid_local, jid_server, jid_type, phone, push_name, metadata, last_seen_at)
+             VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb, NOW())
+             ON CONFLICT (jid) DO UPDATE
+               SET last_seen_at = NOW(),
+                   push_name    = COALESCE(NULLIF(EXCLUDED.push_name, ''), wa_users.push_name),
+                   phone        = COALESCE(wa_users.phone, EXCLUDED.phone),
+                   metadata     = wa_users.metadata || EXCLUDED.metadata
+             RETURNING *`,
+            [
+                parsed.jid,
+                parsed.local,
+                parsed.server,
+                parsed.type,
+                parsed.phone,
+                pushName,
+                JSON.stringify(metadata),
+            ]
+        );
+
+        // Every user is their own primary identity. DO NOTHING on conflict:
+        // re-pointing a jid at another person is IdentityRepository's job, and
+        // it merges instead of silently stealing the alias.
+        await this.db.query(
+            `INSERT INTO wa_user_identities (user_id, jid, jid_local, jid_server, jid_type, phone, is_primary, source)
+             VALUES ($1, $2, $3, $4, $5, $6, TRUE, 'primary')
+             ON CONFLICT (jid) DO UPDATE SET last_seen_at = NOW()`,
+            [user.id, parsed.jid, parsed.local, parsed.server, parsed.type, parsed.phone]
+        );
+
+        return user;
+    }
+
+    /** Refresh `last_seen_at` / push name on a known row. */
+    async touch(userId, info = {}) {
+        if (!userId) return null;
+        const pushName = UserRepository._clean(info.pushName, 128);
+        const metadata = info.metadata && typeof info.metadata === 'object' ? info.metadata : {};
+        return this.db.one(
+            `UPDATE wa_users
+                SET last_seen_at = NOW(),
+                    push_name    = COALESCE(NULLIF($2, ''), push_name),
+                    metadata     = metadata || $3::jsonb
+              WHERE id = $1
+              RETURNING *`,
+            [userId, pushName, JSON.stringify(metadata)]
+        );
+    }
+
+    async findById(userId) {
+        if (!userId) return null;
+        return this.db.one('SELECT * FROM wa_users WHERE id = $1', [userId]);
+    }
+
+    /**
+     * Find-or-create a group.
+     * @param {string} rawJid
+     * @param {object} [info]
+     * @param {string} [info.subject]
+     * @returns {Promise<object|null>}
+     */
+    async upsertGroup(rawJid, info = {}) {
+        if (!rawJid) return null;
+        const parsed = JidParser.parse(rawJid);
+        if (!parsed.valid || !parsed.isGroup) {
+            throw new ValidationError(`Invalid group jid: ${JSON.stringify(rawJid)}`);
+        }
+
+        const subject = UserRepository._clean(info.subject, 256);
+        const metadata = info.metadata && typeof info.metadata === 'object' ? info.metadata : {};
+
+        return this.db.one(
+            `INSERT INTO wa_groups (jid, subject, metadata, last_seen_at)
+             VALUES ($1, $2, $3::jsonb, NOW())
+             ON CONFLICT (jid) DO UPDATE
+               SET last_seen_at = NOW(),
+                   subject      = COALESCE(NULLIF(EXCLUDED.subject, ''), wa_groups.subject),
+                   metadata     = wa_groups.metadata || EXCLUDED.metadata
+             RETURNING *`,
+            [parsed.jid, subject, JSON.stringify(metadata)]
+        );
+    }
+
+    /** Record that `userId` is present in `groupId`. */
+    async linkMember(groupId, userId, isAdmin = false) {
+        if (!groupId || !userId) return null;
+        return this.db.one(
+            `INSERT INTO wa_group_members (group_id, user_id, is_admin, last_seen_at)
+             VALUES ($1, $2, $3, NOW())
+             ON CONFLICT (group_id, user_id) DO UPDATE
+               SET last_seen_at  = NOW(),
+                   message_count = wa_group_members.message_count + 1,
+                   is_admin      = EXCLUDED.is_admin OR wa_group_members.is_admin
+             RETURNING *`,
+            [groupId, userId, Boolean(isAdmin)]
+        );
+    }
+
+    /**
+     * Look a user up by ANY address they are known under — the row itself or
+     * one of their linked aliases (`@lid` <-> phone jid).
+     */
+    async findByJid(rawJid) {
+        const jid = JidParser.normalize(rawJid);
+        if (!jid) return null;
+        return this.db.one(
+            `SELECT u.* FROM wa_users u
+              WHERE u.jid = $1
+              UNION
+             SELECT u.* FROM wa_users u
+               JOIN wa_user_identities i ON i.user_id = u.id
+              WHERE i.jid = $1
+              LIMIT 1`,
+            [jid]
+        );
+    }
+
+    async findGroupByJid(rawJid) {
+        const jid = JidParser.normalize(rawJid);
+        if (!jid) return null;
+        return this.db.one('SELECT * FROM wa_groups WHERE jid = $1', [jid]);
+    }
+
+    async incrementMessageCount(userId, chars = 0) {
+        if (!userId) return;
+        await this.db.query(
+            `UPDATE wa_users
+                SET message_count  = message_count + 1,
+                    token_estimate = token_estimate + $2
+              WHERE id = $1`,
+            [userId, Math.ceil(chars / 4)]
+        );
+    }
+
+    /**
+     * Block/unblock by ANY address the person is known under.
+     *
+     * Previously this matched `wa_users.jid` only, so blocking someone by the
+     * `@lid` seen in a group silently did nothing (returned null) when their
+     * row had been created from a DM phone jid — and vice versa. It now walks
+     * the alias graph, and when blocking someone the bot has never seen it
+     * creates the row so the block is already in force on their first message.
+     */
+    async setBlocked(rawJid, blocked = true) {
+        const parsed = JidParser.parse(rawJid);
+        if (!parsed.valid || parsed.isGroup) {
+            throw new ValidationError(`Invalid user jid: ${JSON.stringify(rawJid)}`);
+        }
+        let user = await this.findByJid(parsed.jid);
+        if (!user) {
+            if (!blocked) return null; // nothing to unblock
+            user = await this.upsertUser(parsed.jid);
+        }
+        return this.db.one('UPDATE wa_users SET is_blocked = $2 WHERE id = $1 RETURNING *', [
+            user.id,
+            Boolean(blocked),
+        ]);
+    }
+
+    async isBlocked(rawJid) {
+        const user = await this.findByJid(rawJid);
+        return Boolean(user?.is_blocked);
+    }
+
+    /**
+     * Enable/disable the AI in a group. Creates the group row when the bot
+     * has not seen the group yet (an admin usually disables Alexa *before*
+     * she has answered there), instead of returning null and doing nothing.
+     */
+    async setGroupEnabled(rawJid, enabled = true) {
+        const parsed = JidParser.parse(rawJid);
+        if (!parsed.valid || !parsed.isGroup) {
+            throw new ValidationError(`Invalid group jid: ${JSON.stringify(rawJid)}`);
+        }
+        const group = (await this.findGroupByJid(parsed.jid)) || (await this.upsertGroup(parsed.jid));
+        return this.db.one('UPDATE wa_groups SET is_enabled = $2 WHERE id = $1 RETURNING *', [
+            group.id,
+            Boolean(enabled),
+        ]);
+    }
+
+    /** Name Alexa should use: learned name > WhatsApp push name > fallback. */
+    async resolveDisplayName(userId, fallback = 'there') {
+        const row = await this.db.one(
+            `SELECT COALESCE(
+                        u.display_name,
+                        (SELECT m.value FROM wa_memories m
+                          WHERE m.user_id = u.id AND m.key IN ('name','full_name','nickname')
+                          ORDER BY (m.key = 'name') DESC, m.updated_at DESC LIMIT 1),
+                        u.push_name
+                    ) AS name
+               FROM wa_users u WHERE u.id = $1`,
+            [userId]
+        );
+        return UserRepository._clean(row?.name, 64) || fallback;
+    }
+
+    async setDisplayName(rawJid, name) {
+        const jid = JidParser.normalize(rawJid);
+        return this.db.one('UPDATE wa_users SET display_name = $2 WHERE jid = $1 RETURNING *', [
+            jid,
+            UserRepository._clean(name, 64),
+        ]);
+    }
+
+    async stats() {
+        return this.db.one(`
+            SELECT (SELECT COUNT(*) FROM wa_users)                          AS users,
+                   (SELECT COUNT(*) FROM wa_groups)                         AS groups,
+                   (SELECT COUNT(*) FROM wa_conversations)                  AS conversations,
+                   (SELECT COUNT(*) FROM wa_messages)                       AS messages,
+                   (SELECT COUNT(*) FROM wa_memories)                       AS memories,
+                   (SELECT COUNT(*) FROM wa_users WHERE last_seen_at > NOW() - INTERVAL '24 hours') AS active_24h
+        `);
+    }
+
+    static _clean(value, max) {
+        if (value == null) return null;
+        const str = String(value).replace(/[\u0000-\u001F\u007F]/g, '').trim();
+        if (!str) return null;
+        return str.length > max ? str.slice(0, max) : str;
+    }
+}
+
+module.exports = UserRepository;

package/src/services/AmnesiaGuard.js

@@ -0,0 +1,176 @@
+'use strict';
+
+/**
+ * AmnesiaGuard
+ * ------------
+ * Stops the assistant from denying a memory it demonstrably has.
+ *
+ * THE BUG THIS FIXES
+ * ------------------
+ * The engine stores facts per human and injects them into every prompt, but the
+ * free DeepAI tier still loves to answer:
+ *
+ *   user  (in a group): "do you remember me?"
+ *   model:              "Unfortunately, as a bot I can't remember you."
+ *
+ * …while the database is holding `name=Nimal, location=Galle, hobby=cricket`.
+ * The reply is simply false, and it is the single most damaging thing the bot
+ * can say.
+ *
+ * Two layers:
+ *   1. `directiveFor()` — a short, explicit instruction (plus the answer the
+ *      model should give) placed immediately before a recall question.
+ *   2. `repair()`       — if the reply still denies having a memory while we
+ *      hold facts, the denial is rewritten from the database. Deterministic:
+ *      no second round-trip, no extra latency, and it can never be wrong.
+ */
+class AmnesiaGuard {
+    /** "do you remember me", "what's my name", "who am I", … */
+    static RECALL_QUESTION =
+        /\b(?:do (?:you|u) (?:still )?(?:remember|know|recall)|remember me|remember my|you remember|what(?:'s| is)? my (?:name|age|city|town|country|job|hobby|favou?rite)|who am i|do you know (?:me|my|who i am)|mata mathakada|mage nama)\b/i;
+
+    /** Denials of having any memory at all. */
+    static DENIAL =
+        /(?:\b(?:i|we)\s+(?:really\s+)?(?:can(?:'|no)?t|cannot|can not|do(?:n'?t| not)|am unable to|are unable to|have no (?:way|ability)|don'?t have (?:the )?(?:ability|capability|memory|access)|lack the ability)\s+(?:to\s+)?(?:really\s+)?(?:remember|recall|retain|store|save|access|keep track of)\b)|(?:\bas an? (?:ai|bot|assistant|language model)[^.!?]{0,60}(?:remember|recall|memory|retain)\b)|(?:\bi\s+(?:have|hold|retain)\s+no\s+(?:memory|memories|record|recollection)\b)|(?:\bno memory of (?:you|our|previous|past|earlier)\b)|(?:\bi\s+don'?t\s+(?:have|keep|retain|store)\s+(?:any\s+)?(?:memory|memories|records?|information about you)\b)|(?:\b(?:our|this) conversation (?:has )?just started\b)|(?:\bi don'?t have access to (?:previous|past|prior|earlier) (?:conversations|chats|messages)\b)|(?:\bevery (?:conversation|chat) (?:starts|begins) (?:fresh|anew)\b)|(?:\bi start(?: over)? fresh\b)/i;
+
+    /** Human-friendly labels for the keys we store most often. */
+    static LABELS = {
+        name: 'your name is',
+        full_name: 'your full name is',
+        nickname: 'you also go by',
+        age: "you're",
+        location: "you're from",
+        city: "you're from",
+        country: "you're from",
+        hobby: 'you love',
+        favourite_food: 'your favourite food is',
+        favorite_food: 'your favourite food is',
+        favourite_team: 'you support',
+        favorite_team: 'you support',
+        job: 'you work as',
+        occupation: 'you work as',
+        studies: "you're studying",
+        language: 'you speak',
+        birthday: 'your birthday is',
+    };
+
+    /**
+     * @param {object} [persona]
+     * @param {string} [persona.assistantName='Alexa']
+     */
+    constructor({ assistantName = 'Alexa' } = {}) {
+        this.name = String(assistantName || 'Alexa').trim() || 'Alexa';
+    }
+
+    /** Is the user asking the assistant to recall something about them? */
+    static isRecallQuestion(message) {
+        const text = String(message ?? '').trim();
+        if (!text || text.length > 400) return false;
+        return AmnesiaGuard.RECALL_QUESTION.test(text);
+    }
+
+    /** Does this reply deny having a memory? */
+    static isDenial(reply) {
+        const text = String(reply ?? '');
+        if (!text.trim()) return false;
+        return AmnesiaGuard.DENIAL.test(text);
+    }
+
+    /**
+     * Instruction injected right before a recall question, carrying the answer.
+     * @param {object} params
+     * @param {Record<string,string>} params.memories
+     * @param {string} [params.displayName]
+     * @param {boolean} params.isRecall
+     * @param {boolean} [params.isGroup]
+     * @returns {string} '' when nothing needs saying
+     */
+    directiveFor({ memories = {}, displayName = null, isRecall = false, isGroup = false } = {}) {
+        const keys = Object.keys(memories || {});
+        if (!isRecall) return '';
+
+        if (!keys.length) {
+            return (
+                '[MEMORY CHECK: You DO have a permanent memory, but you have not saved any facts about this ' +
+                'person yet. Say warmly that you do not have their details saved yet and ask them to tell you. ' +
+                'Do NOT say you are unable to remember things.]\n\n'
+            );
+        }
+
+        const facts = keys.map((k) => `${k.replace(/_/g, ' ')}: ${memories[k]}`).join('; ');
+        const where = isGroup
+            ? 'You know this person from their private chat with you, and this message is in a group — the same person, same memory. '
+            : '';
+        return (
+            `[MEMORY CHECK: You DO remember this person. ${where}Saved facts: ${facts}. ` +
+            `Answer their question directly and warmly using these facts${displayName ? `, greeting them as ${displayName}` : ''}. ` +
+            'NEVER say you cannot remember, have no memory, or that the conversation just started.]\n\n'
+        );
+    }
+
+    /**
+     * Rewrite a reply that denies having a memory.
+     *
+     * @param {string} reply
+     * @param {object} params
+     * @param {Record<string,string>} params.memories
+     * @param {string} [params.displayName]
+     * @param {boolean} [params.isRecall]
+     * @returns {{ text: string, repaired: boolean }}
+     */
+    repair(reply, { memories = {}, displayName = null, isRecall = false } = {}) {
+        const text = String(reply ?? '');
+        if (!AmnesiaGuard.isDenial(text)) return { text, repaired: false };
+
+        const known = Object.keys(memories || {}).length > 0;
+
+        // Drop only the sentences that contain the denial; keep the rest.
+        const sentences = AmnesiaGuard.splitSentences(text);
+        const kept = sentences.filter((s) => !AmnesiaGuard.DENIAL.test(s)).join(' ').trim();
+
+        if (known) {
+            const recall = this.recallSentence(memories, displayName);
+            if (isRecall || !kept) return { text: recall, repaired: true };
+            return { text: `${recall} ${kept}`.trim(), repaired: true };
+        }
+
+        const honest = displayName
+            ? `I don't have any details saved about you yet, ${displayName} — tell me and I'll remember. 😊`
+            : "I don't have any details saved about you yet — tell me and I'll remember. 😊";
+        return { text: kept ? `${honest} ${kept}`.trim() : honest, repaired: true };
+    }
+
+    /**
+     * A warm, WhatsApp-formatted sentence built from stored facts.
+     * @param {Record<string,string>} memories
+     * @param {string} [displayName]
+     */
+    recallSentence(memories, displayName = null) {
+        const entries = Object.entries(memories || {}).filter(([, v]) => v);
+        const name = memories.name || memories.full_name || displayName;
+
+        const parts = [];
+        for (const [key, value] of entries.slice(0, 6)) {
+            if (key === 'name' || key === 'full_name') continue;
+            const label = AmnesiaGuard.LABELS[key] || `your ${key.replace(/_/g, ' ')} is`;
+            parts.push(`${label} _${value}_`);
+        }
+
+        const opener = name ? `Of course I remember you, *${name}*! 😊` : 'Of course I remember you! 😊';
+        if (!parts.length) return opener;
+
+        const list =
+            parts.length === 1 ? parts[0] : `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}`;
+        return `${opener} I remember that ${list}.`;
+    }
+
+    /** @private naive but dependable sentence splitter. */
+    static splitSentences(text) {
+        return String(text)
+            .split(/(?<=[.!?])\s+/)
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+}
+
+module.exports = AmnesiaGuard;