@c4t4/heyamigo 0.1.18 → 0.5.0

package/config/memory-instructions.md

@@ -1,40 +1,181 @@
-# Memory instructions
+# Memory and runtime instructions
 
-You have a long-term memory system. Files are stored under `storage/memory/` and surface to you in the [Memory] blocks at the top of each message.
+You have long-term memory, a journaling system, and a background work lane. This file tells you how to use them. Every rule here is load-bearing — read it carefully.
 
-## When to flag for memory update
+## Storage layout
 
-When something genuinely worth remembering happens in a reply, append this marker to the END of your reply:
+Everything lives under `storage/memory/`. You have Read + Write access to this directory.
+
+```
+storage/memory/
+  index.md                                # map of the whole memory tree
+  buckets/<slug>/index.md                 # topical knowledge (projects, topics)
+  buckets/<slug>/*.md                     # bucket contents
+  persons/<phone-number>/index.md         # auto-maintained per-person profile
+  persons/<phone-number>/profile.md       # facts, preferences, patterns
+  chats/<jid>/index.md                    # auto-maintained per-chat brief
+  chats/<jid>/brief.md                    # purpose, tone, recent topics
+  journals/<slug>/index.md                # journal spec (frontmatter + body)
+  journals/<slug>/entries.jsonl           # append-only dated entries
+  journals/<slug>/observer-state.json     # last-scanned timestamp per JID
+  journals/<slug>/nudge-state.json        # last nudge timestamps + snooze
+```
+
+Relevant blocks from these files are surfaced to you in the `[Memory: ...]` sections at the top of each turn. You don't need to re-read a file that's already in your preamble.
+
+## DIGEST flag
+
+When something in the conversation is worth remembering long-term, append this marker to the END of your reply:
 
 ```
 [DIGEST: <one-line reason>]
 ```
 
-Examples of worth flagging:
-- New durable preference ("prefers audio notes over text")
-- Key fact about their life or work ("moving to Berlin May 1")
-- Relationship or context shift ("no longer working")
-- A decision they made that future replies should respect
+The marker is stripped before the user sees it. It schedules a background consolidation pass that updates the relevant person profile and/or chat brief.
+
+Use for: a new durable preference, a key life/work fact, a relationship or context shift, a decision that future replies should respect.
+
+Do NOT use for: small talk, jokes, logistics, facts already in the profile, things that happen constantly. A few times per week at most.
+
+## Journals
+
+A journal is a long-running tracking project the owner sets up: a health journal for Dani, a dog-training log, a competitor-outreach spy journal, etc. Each journal has a purpose, captures entries over time, and can nudge the owner proactively.
+
+Active journals appear in `[Journals: active]` in your preamble with slug + purpose. Use those exact slugs — never invent one.
+
+Journals are OWNER-SCOPED and GLOBAL. The same list applies across every chat the owner is in. A journal is not tied to a specific chat or person.
+
+### Creating a new journal
 
-Do NOT flag for:
-- Small talk, jokes, logistics
-- Facts the profile already knows
-- Every single message (flag sparingly, a few times per week at most)
+When the owner asks you to track something recurring that no existing journal covers:
 
-The marker will be stripped from your reply before the person sees it. It is a private signal to trigger profile/brief updates.
+1. Propose one concrete purpose in one message:
+   > "Competitor-outreach spy journal: track HT creators' shock-loss timelines, Elithair comment-section complaints, and open follow-up threads. Sound right?"
+2. Wait for confirmation.
+3. Once confirmed, append this marker at the END of your reply:
+   ```
+   [JOURNAL-NEW:<slug> — <one-line purpose>]
+   ```
 
-## Browser and screenshots
+Slug rules: lowercase letters, digits, hyphens. Max 48 chars. Start with a letter or digit. Be descriptive but short (`rivoara-spy`, `health`, `dog-training`).
 
-You have access to a Chrome browser via tools: browser_navigate, browser_take_screenshot, browser_snapshot, browser_click, browser_type, browser_evaluate, and more.
+The marker creates `storage/memory/journals/<slug>/index.md` with sensible defaults (status=active, nudge_if_silent=3d). You don't need to write the file yourself — the marker handles it.
 
-When asked to check a website, take a screenshot, or interact with a page, use these tools.
+You can flag the first entry in the same reply:
+```
+[JOURNAL-NEW:rivoara-spy — Track HT creator shock-loss timelines, Elithair complaints, open follow-ups]
+[JOURNAL:rivoara-spy — @ari269906 hits day 60 around mid-May, shock-loss window]
+```
 
-To send a file to the chat (screenshot, image, video, PDF, audio), save it to `storage/outbox/` and include this tag in your reply:
+### Appending entries
+
+When a message contains info that belongs in an active journal, append at the END of your reply:
 
 ```
-[FILE: storage/outbox/filename.png]
+[JOURNAL:<slug> — <one-line note>]
 ```
 
-Supported aliases: [IMAGE: path], [VIDEO: path], [AUDIO: path], [DOCUMENT: path] — all work the same.
+Multiple tags in one reply are fine. Separator between slug and note: em-dash, en-dash, hyphen, or colon.
+
+Realistic examples (assume active slugs `health`, `rivoara-spy`):
+
+- Dani: "slept 5hrs, toilet again, head pounding"
+  → `[JOURNAL:health — 5hrs sleep, GI symptoms recurring, headache]`
+- Cata: "@chigosfoodblog just posted Tag 5, pouring water down his fresh grafts with tap"
+  → `[JOURNAL:rivoara-spy — @chigosfoodblog day 5, visible tap-water rinse, strong filter pitch angle]`
+- Cata: "dinner was great"
+  → no journal tag. Irrelevant to any journal.
+
+Hard rules:
+- Use only slugs in `[Journals: active]`. Don't invent.
+- One journal, one subject. Don't cross-log (Dani's health entries don't go in Cata's health topic bucket or vice versa).
+- Don't log every message. Flag when there's real content for the journal.
+- If the owner's statement is ambiguous, ask before flagging.
+
+### Editing a journal (pause, archive, cadence, schema)
+
+There are no markers for pause/resume/archive. When the owner asks to pause, archive, snooze, or reshape a journal, edit `storage/memory/journals/<slug>/index.md` directly with Edit or Write.
+
+Frontmatter fields you may change:
+- `status: active | paused | archived` — paused and archived journals stop nudging and stop appearing in observer sweeps.
+- `purpose: <text>` — refine as the journal evolves.
+- `fields: [<field>, <field>, ...]` — what the journal typically captures.
+- `checkin: "daily HH:MM" | "Xh" | "Xd"` — proactive check-in cadence.
+- `nudge_if_silent: "Xd"` — nudge after this much silence on the topic.
+- `quiet_hours: "HH:MM-HH:MM"` — per-journal quiet window (overrides default 22:00-08:00).
+
+Do NOT edit `entries.jsonl` directly — that's append-only and maintained by the pipeline. Do NOT edit `observer-state.json` or `nudge-state.json` unless fixing a specific bug the owner asked you to investigate.
+
+Confirm the change in your reply so the owner sees what you did:
+> "Archived. Won't nudge you about it anymore. Entries stay in entries.jsonl as the historical record."
+
+## ASYNC background work
+
+The chat queue is serialized per chat. If you do real work inline (browsing, scraping, multi-step research), every subsequent message in that chat waits for you. To stay responsive, delegate long work to a background worker.
+
+Two parts in the same reply:
+
+1. A one or two-sentence ack in the reply text: "On it, will report back." / "Scraping now, give me a few minutes." / "Looking into it."
+2. Append at the END:
+   ```
+   [ASYNC: <self-sufficient task description>]
+   ```
+
+Example:
+
+```
+On it. Will send the list when it's ready.
+
+[ASYNC: Find 10 additional German TikTok creators documenting hair transplant journeys, 500-3000 followers, not in this list: @simply__stefan, @daenieal, @myhairjourney2025, @chigosfoodblog. Use the Rivoara TikTok account (already logged in) to browse. Output handle, follower count, one-line angle per creator.]
+```
+
+### When to use ASYNC
+
+Use it for:
+- Browser work (scraping, multi-page research, form filling, anything touching >1 URL)
+- Multi-step investigations with several tool calls
+- Anything you expect to take more than ~30 seconds
+
+Do NOT use it for:
+- A single quick URL fetch
+- Short calculations or reasoning
+- Anything you can answer from context alone
+- Things the owner needs answered in this reply, right now
+
+### Writing the task description
+
+The async worker has NO chat history, NO session, no memory of your conversation. Its only input is the description you write. Self-sufficient means:
+- Spell out exactly what to do.
+- Include every constraint, exclusion, and required context.
+- Reference specific tools or accounts (e.g. "use the Rivoara TikTok session").
+- Specify the expected output shape (list format, fields, order).
+
+Over-specify. A vague description produces a vague result.
+
+### Avoiding duplicates
+
+If you see `[Async tasks in progress]` in your preamble, a worker is already running for this chat. Do NOT emit another `[ASYNC:...]` for the same work. Reply naturally: "Still working on it, 4 minutes in."
+
+## Sending files
+
+To send a file (screenshot, image, video, PDF, audio) to the chat, save it to `storage/temp/` and include this tag in your reply:
+
+```
+[FILE: /absolute/path/to/file.png]
+```
+
+Aliases (all behave the same): `[IMAGE: path]`, `[VIDEO: path]`, `[AUDIO: path]`, `[DOCUMENT: path]`.
+
+Rules:
+- Always use absolute paths.
+- Always save under `storage/temp/`. Never save to the project root or anywhere else. Files are auto-deleted after sending.
+- Media type is detected from the file extension.
+- If you send a single file with a short text reply (under 1000 chars, non-audio), the text becomes the caption.
+
+## Browser tools
+
+You have a Chrome browser via Playwright MCP: `browser_navigate`, `browser_take_screenshot`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_evaluate`, etc.
+
+For anything beyond a single page load, use `[ASYNC: ...]` instead of running inline. Browser work blocks the main queue.
 
-Always save to `storage/outbox/`. Files are automatically deleted after sending. The tag will be stripped and the file sent as a WhatsApp media message. Auto-detects type from extension. Short text alongside a single file becomes the caption.
+To send a screenshot back: take it with the browser tool (save to `storage/temp/`), then include `[IMAGE: /absolute/path.png]` in your reply.

package/dist/gateway/commands.js

@@ -3,6 +3,10 @@ import { reloadSystemPrompt } from '../ai/claude.js';
 import { config } from '../config.js';
 import { runDigestNow } from '../memory/scheduler.js';
 import { sendText } from '../wa/sender.js';
+// Feature-level commands (/journal, /snooze, /tasks, etc.) are intentionally
+// absent. Claude is the interface — the owner asks for things in natural
+// language and Claude acts via markers or by editing files directly.
+// Only operational commands live here: reset, status, reload, digest.
 export async function tryCommand(ctx) {
     const prefix = config.commands.prefix;
     const trimmed = ctx.text.trim();

package/dist/gateway/outgoing.js

@@ -107,6 +107,45 @@ export async function handleReply(job, result, originalMsg) {
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+// Proactive outbound: send a message to a chat without an incoming trigger.
+// Chunks, persists to the message log, never throws. Callers are responsible
+// for the canSendProactive() gate — this function does not re-check it.
+export async function initiate(params) {
+    const sock = getSocket();
+    if (!sock) {
+        logger.warn({ jid: params.jid }, 'initiate: no socket available');
+        return false;
+    }
+    const raw = params.text.replaceAll('—', ', ').replaceAll('–', '-');
+    if (!raw.trim())
+        return false;
+    try {
+        const chunks = chunkText(raw, config.reply.chunkChars);
+        for (let i = 0; i < chunks.length; i++) {
+            const chunk = chunks[i];
+            await sendText(sock, params.jid, chunk);
+            await append({
+                id: `initiate-${Date.now()}-${i}`,
+                jid: params.jid,
+                direction: 'out',
+                fromMe: true,
+                sender: sock.user?.id ?? '',
+                senderNumber: config.owner.number,
+                timestamp: Math.floor(Date.now() / 1000),
+                text: chunk,
+                messageType: 'conversation',
+            });
+            if (i < chunks.length - 1)
+                await sleep(config.reply.chunkDelayMs);
+        }
+        logger.info({ jid: params.jid, chars: raw.length }, 'proactive message sent');
+        return true;
+    }
+    catch (err) {
+        logger.error({ err, jid: params.jid }, 'initiate failed');
+        return false;
+    }
+}
 export function chunkText(text, maxChars) {
     if (text.length <= maxChars)
         return [text];

package/dist/memory/digest-flag.js

@@ -1,8 +1,70 @@
-const DIGEST_RE = /\[DIGEST:\s*([^\]]+)\]\s*$/i;
+const TRAILING_TAG_RE = /\[(DIGEST|JOURNAL|JOURNAL-NEW|ASYNC):\s*([^\]]+)\]\s*$/i;
+// Peel trailing tags off the end of a reply. Supported:
+//   [DIGEST: <reason>]
+//   [JOURNAL:<slug> — <note>]         (append entry)
+//   [JOURNAL-NEW:<slug> — <purpose>]  (create journal)
+//   [ASYNC: <self-sufficient task description>]
+// Multiple tags supported, any order at the tail. Tags must be the LAST
+// thing in the reply (after trimming trailing whitespace).
+//
+// Journal pause/resume/archive is intentionally NOT a marker. If the owner
+// wants those, Claude edits the journal's index.md frontmatter directly.
+// Keeping the marker vocabulary small keeps Claude's context tight.
+export function extractFlags(reply) {
+    let current = reply;
+    let digest = null;
+    const journals = [];
+    const journalCreates = [];
+    const asyncTasks = [];
+    while (true) {
+        const trimmed = current.replace(/\s+$/, '');
+        const match = trimmed.match(TRAILING_TAG_RE);
+        if (!match)
+            break;
+        const kind = match[1].toUpperCase();
+        const payload = (match[2] ?? '').trim();
+        if (kind === 'DIGEST') {
+            if (digest === null)
+                digest = payload;
+        }
+        else if (kind === 'JOURNAL') {
+            const parsed = parseJournalPayload(payload);
+            if (parsed)
+                journals.unshift(parsed);
+        }
+        else if (kind === 'JOURNAL-NEW') {
+            const parsed = parseJournalPayload(payload);
+            if (parsed) {
+                journalCreates.unshift({ slug: parsed.slug, purpose: parsed.note });
+            }
+        }
+        else if (kind === 'ASYNC') {
+            if (payload.length >= 8) {
+                asyncTasks.unshift({ description: payload });
+            }
+        }
+        current = trimmed.slice(0, match.index).trimEnd();
+    }
+    return { clean: current, digest, journals, journalCreates, asyncTasks };
+}
+// Legacy helper kept so existing callers still compile.
 export function extractDigestFlag(reply) {
-    const match = reply.match(DIGEST_RE);
+    const r = extractFlags(reply);
+    return { clean: r.clean, flag: r.digest };
+}
+const JOURNAL_SEP_RE = /\s*(?:[—\-–]|:)\s*/;
+function parseJournalPayload(payload) {
+    // Split on first em-dash, en-dash, hyphen, or colon between slug and note.
+    const match = payload.match(/^([a-zA-Z0-9][a-zA-Z0-9-]*)(.*)$/);
     if (!match)
-        return { clean: reply, flag: null };
-    const clean = reply.slice(0, match.index).trimEnd();
-    return { clean, flag: match[1]?.trim() ?? '' };
+        return null;
+    const slug = match[1].toLowerCase();
+    const rest = match[2] ?? '';
+    const sepMatch = rest.match(JOURNAL_SEP_RE);
+    if (!sepMatch || sepMatch.index !== 0)
+        return null;
+    const note = rest.slice(sepMatch[0].length).trim();
+    if (!note)
+        return null;
+    return { slug, note };
 }

package/dist/memory/journal-cadence.js

@@ -0,0 +1,120 @@
+// Cadence parsing and "is due?" evaluation for journals.
+//
+// Supported shapes:
+//   "daily HH:MM"        — daily at HH:MM in owner.timezone (e.g. "daily 21:00")
+//   "Xh"                 — every X hours (e.g. "24h")
+//   "Xd"                 — every X days (e.g. "3d")
+//   "Xm"                 — every X minutes (only for testing; rounded up)
+//
+// Quiet hours shape: "HH:MM-HH:MM" (may span midnight: "22:00-08:00")
+export function parseCadence(raw) {
+    if (!raw)
+        return null;
+    const s = raw.trim().toLowerCase();
+    const daily = s.match(/^daily\s+(\d{1,2}):(\d{2})$/);
+    if (daily) {
+        const hour = Number(daily[1]);
+        const minute = Number(daily[2]);
+        if (hour < 0 || hour > 23 || minute < 0 || minute > 59)
+            return null;
+        return { kind: 'daily', hour, minute };
+    }
+    const iv = s.match(/^(\d+)\s*([mhd])$/);
+    if (iv) {
+        const n = Number(iv[1]);
+        const unit = iv[2];
+        if (!Number.isFinite(n) || n <= 0)
+            return null;
+        const secs = unit === 'm' ? n * 60 : unit === 'h' ? n * 3600 : n * 86400;
+        return { kind: 'interval', seconds: secs };
+    }
+    return null;
+}
+// Returns unix seconds (ts) of the next scheduled firing AFTER the given
+// "lastFiredTs" (or since "now" if never fired). For daily cadences, the time
+// is computed in the owner's timezone.
+export function nextFireTs(params) {
+    const { cadence, lastFiredTs, now, timezone } = params;
+    if (cadence.kind === 'interval') {
+        const base = lastFiredTs ?? now;
+        return base + cadence.seconds;
+    }
+    // daily HH:MM in timezone
+    const anchor = lastFiredTs ?? now;
+    // Start from the day of anchor, then walk forward until target time > anchor.
+    let target = dailyTargetTs(anchor, cadence, timezone);
+    while (target <= anchor) {
+        target = dailyTargetTs(target + 1, cadence, timezone);
+    }
+    return target;
+}
+// For a given reference ts, compute the unix ts for HH:MM that same day in the
+// given timezone. May be earlier than ref if the clock time is past HH:MM.
+function dailyTargetTs(refTs, cadence, timezone) {
+    const parts = timezoneParts(refTs, timezone);
+    // Construct an ISO-like string for "that date at HH:MM in tz" and convert
+    // back to epoch via UTC offset derived from parts.
+    const y = parts.year;
+    const mo = parts.month;
+    const d = parts.day;
+    const ts = zonedDateTimeToEpoch(y, mo, d, cadence.hour, cadence.minute, timezone);
+    return ts;
+}
+export function timezoneParts(tsSeconds, timezone) {
+    const fmt = new Intl.DateTimeFormat('en-GB', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    });
+    const p = Object.fromEntries(fmt.formatToParts(new Date(tsSeconds * 1000)).map((x) => [x.type, x.value]));
+    return {
+        year: Number(p.year),
+        month: Number(p.month),
+        day: Number(p.day),
+        hour: Number(p.hour) % 24,
+        minute: Number(p.minute),
+        second: Number(p.second),
+    };
+}
+// Convert a local (zoned) date-time to epoch seconds. Uses Intl to derive the
+// UTC offset for that zone at that wall time.
+function zonedDateTimeToEpoch(year, month, day, hour, minute, timezone) {
+    // Start with the wall time treated as UTC, then correct by the tz offset.
+    const asUtcMs = Date.UTC(year, month - 1, day, hour, minute, 0);
+    // Get what that UTC moment looks like in the target timezone
+    const parts = timezoneParts(Math.floor(asUtcMs / 1000), timezone);
+    // Compute the diff between the wall time we wanted and what we got
+    const wantedMs = asUtcMs;
+    const gotMs = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, 0);
+    const offsetMs = gotMs - wantedMs;
+    return Math.floor((asUtcMs - offsetMs) / 1000);
+}
+// Quiet hours: is the given time inside the quiet-hours window (in tz)?
+// Accepts "HH:MM-HH:MM" (e.g. "22:00-08:00" = 10pm to 8am next day).
+export function isInQuietHours(params) {
+    const { now, window, timezone } = params;
+    if (!window)
+        return false;
+    const m = window.match(/^(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})$/);
+    if (!m)
+        return false;
+    const startH = Number(m[1]);
+    const startM = Number(m[2]);
+    const endH = Number(m[3]);
+    const endM = Number(m[4]);
+    const parts = timezoneParts(now, timezone);
+    const curMin = parts.hour * 60 + parts.minute;
+    const startMin = startH * 60 + startM;
+    const endMin = endH * 60 + endM;
+    if (startMin <= endMin) {
+        // Non-wrapping window: [start, end)
+        return curMin >= startMin && curMin < endMin;
+    }
+    // Wrapping window: [start, 24:00) ∪ [00:00, end)
+    return curMin >= startMin || curMin < endMin;
+}