@c4t4/heyamigo 0.5.0 → 0.6.1

package/config/config.example.json

@@ -45,7 +45,8 @@
     "chunkDelayMs": 800,
     "typingIndicator": true,
     "errorMessage": "Could not process that, please try again.",
-    "maxMessageAgeMs": 10800000
+    "maxMessageAgeMs": 10800000,
+    "showStats": true
   },
 
   "storage": {

package/config/memory-instructions.md

@@ -23,6 +23,28 @@ storage/memory/
 
 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.
 
+## Rolling state index — [State: current]
+
+At the top of every turn, you get `[State: current]`: a rolling index across all people, chats, buckets, and active journals. One to three lines per entity. This is your cheat sheet.
+
+It is an **index**, not a summary. Each entry carries load-bearing facts + a path to the full file. Everything else lives in the full profile / brief / entries.
+
+### Dig-deeper heuristic
+
+- **Passing reference** ("Dani said X in passing"): the compressed line is enough. Answer.
+- **Deep conversation about someone** ("let's dig into Cata's gut protocol"): Read the full file.
+- **Identity, medical, or rule cue** (pronouns, symptoms, relationship, hard rules): verify against the full file before responding. Laziness here is expensive.
+- **Already Read this session**: the content is still in your context. Do NOT re-Read.
+- **Unfamiliar topic or entity**: Read.
+
+You decide. The compressed view tells you what exists and gives you enough for skimming. It does not try to replace the full files.
+
+Do NOT edit `storage/memory/compressed.md` yourself. It is auto-regenerated after digests and on boot.
+
+## Reply footer (system-generated)
+
+Your replies are auto-suffixed with a tiny stats line on send — duration, tokens, context %, flags fired. You do NOT write this line. Do NOT mimic it. Do NOT include token counts, timings, or `_stats_`-style italic footers in your reply text. The system adds them; you focus on the message.
+
 ## DIGEST flag
 
 When something in the conversation is worth remembering long-term, append this marker to the END of your reply:

package/dist/config.js

@@ -44,6 +44,7 @@ const ConfigSchema = z.object({
         typingIndicator: z.boolean(),
         errorMessage: z.string(),
         maxMessageAgeMs: z.number(),
+        showStats: z.boolean().default(true),
     }),
     storage: z.object({
         messagesDir: z.string(),

package/dist/gateway/outgoing.js

@@ -33,6 +33,9 @@ export async function handleReply(job, result, originalMsg) {
     const { text, files } = extractFiles(raw);
     const isGroup = isJidGroup(job.jid) === true;
     const quoted = isGroup && config.reply.quoteInGroups ? originalMsg : undefined;
+    const footer = result.stats && config.reply.showStats
+        ? formatStatsFooter(result.stats)
+        : '';
     try {
         // Send files first (images, videos, PDFs, audio, etc.)
         for (const filePath of files) {
@@ -43,7 +46,15 @@ export async function handleReply(job, result, originalMsg) {
             const caption = isFirst && text && text.length <= 1000 && files.length === 1 && supportsCaption
                 ? text
                 : undefined;
-            await sendFile(sock, job.jid, filePath, caption, isFirst ? quoted : undefined);
+            // Append footer to caption at send time only (not to storage). Only
+            // when this media file is the final user-facing payload (no text
+            // coming after, single file with caption case).
+            const willHaveTextAfter = !!text &&
+                !(files.length === 1 && text.length <= 1000 && supportsCaption);
+            const captionForSend = caption && footer && !willHaveTextAfter
+                ? `${caption}\n\n${footer}`
+                : caption;
+            await sendFile(sock, job.jid, filePath, captionForSend, isFirst ? quoted : undefined);
             await append({
                 id: `reply-file-${Date.now()}`,
                 jid: job.jid,
@@ -73,7 +84,9 @@ export async function handleReply(job, result, originalMsg) {
             for (let i = 0; i < chunks.length; i++) {
                 const chunk = chunks[i];
                 const q = i === 0 && files.length === 0 ? quoted : undefined;
-                await sendText(sock, job.jid, chunk, q);
+                const isLast = i === chunks.length - 1;
+                const chunkForSend = isLast && footer ? `${chunk}\n\n${footer}` : chunk;
+                await sendText(sock, job.jid, chunkForSend, q);
                 await append({
                     id: `reply-${Date.now()}-${i}`,
                     jid: job.jid,
@@ -107,6 +120,50 @@ export async function handleReply(job, result, originalMsg) {
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+// Append-only-at-send footer. Never stored, never in Claude's recent-context
+// feedback loop. Adaptive: shows only what's interesting for this reply.
+export function formatStatsFooter(stats) {
+    const parts = [];
+    // Duration — always
+    const secs = stats.durationMs / 1000;
+    parts.push(secs < 10 ? `${secs.toFixed(1)}s` : `${Math.round(secs)}s`);
+    // Tokens in / out — always. Show cache hit only when it's meaningful.
+    const inStr = compactTokens(stats.inputTokens + stats.cacheReadTokens);
+    const outStr = compactTokens(stats.outputTokens);
+    const cacheStr = stats.cacheReadTokens >= 500
+        ? ` (${compactTokens(stats.cacheReadTokens)} cached)`
+        : '';
+    parts.push(`${inStr}↑${cacheStr} ${outStr}↓`);
+    // Context % — only when worth calling out
+    if (stats.contextWindow > 0) {
+        const pct = Math.round((stats.totalContextTokens / stats.contextWindow) * 100);
+        if (pct >= 90)
+            parts.push(`⚠ ${pct}% ctx`);
+        else if (pct >= 70)
+            parts.push(`${pct}% ctx`);
+    }
+    // Fresh session — resume is default, says nothing
+    if (stats.fresh)
+        parts.push('fresh');
+    // Journal flagged — show each slug (usually 0 or 1)
+    for (const slug of stats.journalSlugs)
+        parts.push(`+journal:${slug}`);
+    // Digest fired
+    if (stats.hasDigest)
+        parts.push('+digest');
+    // Async spawned
+    if (stats.asyncCount > 0) {
+        parts.push(stats.asyncCount === 1 ? '+async' : `+${stats.asyncCount} async`);
+    }
+    return `_${parts.join(' · ')}_`;
+}
+function compactTokens(n) {
+    if (n < 1000)
+        return String(n);
+    if (n < 10_000)
+        return `${(n / 1000).toFixed(1)}k`;
+    return `${Math.round(n / 1000)}k`;
+}
 // 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.

package/dist/memory/compressed.js

@@ -0,0 +1,334 @@
+import { spawn } from 'child_process';
+import { existsSync, readFileSync, readdirSync, writeFileSync, } from 'fs';
+import { dirname, resolve } from 'path';
+import { mkdirSync } from 'fs';
+import { config } from '../config.js';
+import { logger } from '../logger.js';
+import { logPrompt } from '../promptlog.js';
+import { listJournals, readEntries } from './journals.js';
+import { memoryRoot, treeRoot, entityIndexPath } from './paths.js';
+// The compressed view is a rolling index across all memory: people, chats,
+// buckets, active journals. 1-3 lines per entity. Purpose: every fresh
+// session starts with enough state to respond to a passing mention without
+// re-reading any file. Deep context still lives in the full profile/brief/
+// entries files — Claude reads those on demand.
+//
+// Regenerated on: boot, and after any digest that edits a memory file
+// (marked dirty, lazily rebuilt on next access).
+export function compressedPath() {
+    return resolve(memoryRoot(), 'compressed.md');
+}
+function compressedStatePath() {
+    return resolve(memoryRoot(), 'compressed-state.json');
+}
+function loadState() {
+    const raw = readIfExists(compressedStatePath());
+    if (!raw)
+        return { lastBuiltAt: 0, dirty: true };
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            lastBuiltAt: parsed.lastBuiltAt ?? 0,
+            dirty: parsed.dirty ?? false,
+        };
+    }
+    catch {
+        return { lastBuiltAt: 0, dirty: true };
+    }
+}
+function saveState(state) {
+    const path = compressedStatePath();
+    ensureDirFor(path);
+    writeFileSync(path, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+}
+function readIfExists(path) {
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, 'utf-8');
+}
+function ensureDirFor(path) {
+    mkdirSync(dirname(path), { recursive: true });
+}
+export function markCompressedDirty() {
+    const state = loadState();
+    state.dirty = true;
+    saveState(state);
+}
+export function readCompressed() {
+    return readIfExists(compressedPath());
+}
+// ---------- generator ----------
+function collectPersons() {
+    const dir = treeRoot('persons');
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const d of readdirSync(dir, { withFileTypes: true })) {
+        if (!d.isDirectory())
+            continue;
+        const profilePath = resolve(dir, d.name, 'profile.md');
+        const profile = readIfExists(profilePath);
+        if (profile)
+            out.push({ number: d.name, profile });
+    }
+    return out;
+}
+function collectChats() {
+    const dir = treeRoot('chats');
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const d of readdirSync(dir, { withFileTypes: true })) {
+        if (!d.isDirectory())
+            continue;
+        const briefPath = resolve(dir, d.name, 'brief.md');
+        const brief = readIfExists(briefPath);
+        if (brief)
+            out.push({ jid: d.name, brief });
+    }
+    return out;
+}
+function collectBuckets() {
+    const dir = treeRoot('buckets');
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const d of readdirSync(dir, { withFileTypes: true })) {
+        if (!d.isDirectory())
+            continue;
+        const idx = readIfExists(entityIndexPath('buckets', d.name));
+        if (idx)
+            out.push({ slug: d.name, index: idx });
+    }
+    return out;
+}
+function collectJournals() {
+    return listJournals()
+        .filter((j) => j.status === 'active')
+        .map((j) => {
+        const cadenceBits = [];
+        if (j.cadence.checkin)
+            cadenceBits.push(`check-in ${j.cadence.checkin}`);
+        if (j.cadence.nudge_if_silent)
+            cadenceBits.push(`silent-nudge ${j.cadence.nudge_if_silent}`);
+        const recent = readEntries(j.slug, 2);
+        return {
+            slug: j.slug,
+            purpose: j.purpose,
+            status: j.status,
+            cadence: cadenceBits.join(', '),
+            lastEntries: recent.map((e) => {
+                const d = new Date(e.ts * 1000)
+                    .toISOString()
+                    .slice(0, 10);
+                return `[${d}] ${e.note}`;
+            }),
+        };
+    });
+}
+function buildInputForGenerator() {
+    const lines = [];
+    const persons = collectPersons();
+    if (persons.length) {
+        lines.push('## PEOPLE (raw profiles)');
+        for (const p of persons) {
+            lines.push(`### ${p.number}`);
+            lines.push(p.profile.trim());
+            lines.push('');
+        }
+    }
+    const chats = collectChats();
+    if (chats.length) {
+        lines.push('## CHATS (raw briefs)');
+        for (const c of chats) {
+            lines.push(`### ${c.jid}`);
+            lines.push(c.brief.trim());
+            lines.push('');
+        }
+    }
+    const buckets = collectBuckets();
+    if (buckets.length) {
+        lines.push('## BUCKETS (raw indexes)');
+        for (const b of buckets) {
+            lines.push(`### ${b.slug}`);
+            lines.push(b.index.trim());
+            lines.push('');
+        }
+    }
+    const journals = collectJournals();
+    if (journals.length) {
+        lines.push('## JOURNALS (active)');
+        for (const j of journals) {
+            lines.push(`### ${j.slug}`);
+            lines.push(`purpose: ${j.purpose}`);
+            if (j.cadence)
+                lines.push(`cadence: ${j.cadence}`);
+            if (j.lastEntries.length) {
+                lines.push('last entries:');
+                for (const e of j.lastEntries)
+                    lines.push(`  ${e}`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n') || '(no memory yet)';
+}
+function generatorPrompt(raw) {
+    return `Write the line you'd want to see if you woke up with amnesia and were about to answer this person. That's the whole job.
+
+You are producing a rolling "state of the world" index. Every fresh Claude session starts by reading it. It is NOT a summary. It is an INDEX with load-bearing excerpts, pointing at full files for depth.
+
+RULES (enforce ruthlessly):
+- Every phrase must change a response. If removing it wouldn't change how you'd reply, cut it.
+- Staccato. No filler verbs (is, was, has, tends to). No hedges (maybe, usually, often).
+- Behavior-shifting facts only: identity (pronouns, name), hard rules ("always English", "don't X"), current state ("gut recovering", "bulk to 63kg"), key constraints.
+- NO biography. Age, location, occupation are NOT load-bearing unless they directly change a response.
+- Cap: one to three lines per entity. Closer to one is better.
+- High word/meaning ratio. "Trolls, verify." does the work of a paragraph.
+
+OUTPUT FORMAT (exact):
+
+# State: current
+
+## People
+
+- <name> (<number>): <phrase>. <phrase>. <phrase>.
+  → storage/memory/persons/<number>/profile.md
+
+(one entry per person, three phrases MAX)
+
+## Chats
+
+- <jid> "<chat name if known>": <one line of norms + current state>.
+  → storage/memory/chats/<jid>/brief.md
+
+## Buckets
+
+- <slug>: <one line — what this is + current status>.
+  → storage/memory/buckets/<slug>/index.md
+
+## Journals (active, open todos)
+
+- <slug>: <purpose, tight>.
+  last: <copy the most recent entry VERBATIM, do not paraphrase>
+  cadence: <check-in / silent-nudge as applicable>
+  → storage/memory/journals/<slug>/
+
+RAW SOURCES:
+
+${raw}
+
+Output ONLY the compressed index in the exact format above. No preamble, no explanation, no code fences.`;
+}
+async function spawnGenerator(prompt) {
+    const args = [
+        '-p',
+        '--output-format',
+        'json',
+        '--model',
+        config.claude.model,
+        '--permission-mode',
+        'acceptEdits',
+    ];
+    const startedAt = Date.now();
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn('claude', args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            cwd: process.cwd(),
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (c) => {
+            stdout += c.toString('utf-8');
+        });
+        child.stderr.on('data', (c) => {
+            stderr += c.toString('utf-8');
+        });
+        const logFail = (error) => void logPrompt({
+            ts: Math.floor(startedAt / 1000),
+            caller: 'compressed',
+            args,
+            input: prompt,
+            error,
+            durationMs: Date.now() - startedAt,
+        });
+        child.on('error', (err) => {
+            logFail(`spawn failed: ${err.message}`);
+            rejectPromise(err);
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                logFail(`exit ${code}: ${stderr.slice(0, 300)}`);
+                return rejectPromise(new Error(`compressed generator exit ${code}`));
+            }
+            try {
+                const parsed = JSON.parse(stdout);
+                if (parsed.is_error ||
+                    parsed.subtype !== 'success' ||
+                    !parsed.result) {
+                    logFail(`bad output: ${parsed.result ?? stderr.slice(0, 200)}`);
+                    return rejectPromise(new Error('compressed generator bad output'));
+                }
+                const output = parsed.result.trim();
+                void logPrompt({
+                    ts: Math.floor(startedAt / 1000),
+                    caller: 'compressed',
+                    args,
+                    input: prompt,
+                    output,
+                    durationMs: Date.now() - startedAt,
+                });
+                resolvePromise(output);
+            }
+            catch (err) {
+                logFail(`parse failed: ${err.message}`);
+                rejectPromise(err);
+            }
+        });
+        child.stdin.write(prompt);
+        child.stdin.end();
+    });
+}
+let buildInFlight = null;
+export async function rebuildCompressed() {
+    if (buildInFlight)
+        return buildInFlight;
+    buildInFlight = (async () => {
+        const raw = buildInputForGenerator();
+        if (raw === '(no memory yet)') {
+            const empty = '# State: current\n\n(no memory yet)\n';
+            const path = compressedPath();
+            ensureDirFor(path);
+            writeFileSync(path, empty, 'utf-8');
+            saveState({ lastBuiltAt: Math.floor(Date.now() / 1000), dirty: false });
+            logger.info('compressed: empty scaffold written (no memory yet)');
+            return;
+        }
+        const prompt = generatorPrompt(raw);
+        const output = await spawnGenerator(prompt);
+        const path = compressedPath();
+        ensureDirFor(path);
+        writeFileSync(path, output + '\n', 'utf-8');
+        saveState({ lastBuiltAt: Math.floor(Date.now() / 1000), dirty: false });
+        logger.info({ chars: output.length }, 'compressed: rebuilt');
+    })();
+    try {
+        await buildInFlight;
+    }
+    finally {
+        buildInFlight = null;
+    }
+}
+// Regenerate only if dirty or missing. Used in boot + lazy access paths.
+export async function ensureCompressedFresh() {
+    const state = loadState();
+    const exists = existsSync(compressedPath());
+    if (!state.dirty && exists)
+        return;
+    try {
+        await rebuildCompressed();
+    }
+    catch (err) {
+        logger.error({ err }, 'compressed: rebuild failed');
+    }
+}

package/dist/memory/digest.js

@@ -3,6 +3,7 @@ import { config } from '../config.js';
 import { logger } from '../logger.js';
 import { logPrompt } from '../promptlog.js';
 import { readLast } from '../store/messages.js';
+import { markCompressedDirty } from './compressed.js';
 import { readBrief, readProfile, setLastDigestedAt, writeBrief, writeProfile, } from './store.js';
 /**
  * Run a stateless Claude call to consolidate memory.
@@ -199,4 +200,7 @@ export async function runDigest(params) {
             logger.error({ err, number }, 'profile digest failed');
         }
     }
+    // A profile or brief changed. Mark compressed view dirty so the next
+    // session boot or ensureCompressedFresh() call regenerates it.
+    markCompressedDirty();
 }

package/dist/memory/preamble.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
 import { config } from '../config.js';
 import { listAsyncTasks } from '../queue/async-tasks.js';
+import { readCompressed } from './compressed.js';
 import { buildJournalsPreambleBlock, ensureJournalsScaffold, } from './journals.js';
 import { masterIndexPath, treeIndexPath } from './paths.js';
 import { routeIndexes } from './router.js';
@@ -75,6 +76,14 @@ export function buildMemoryPreamble(params) {
         sections.push(`[Instruction]\n${DIGEST_REMINDER}`);
         return sections.join('\n\n');
     }
+    // Rolling state index: people + chats + buckets + active journals, 1-3
+    // lines each with path pointers. This is the primary memory surface.
+    // Tree indexes + routed entity indexes remain below as a secondary layer
+    // for Claude when the compressed view doesn't carry enough.
+    const compressed = readCompressed();
+    if (compressed) {
+        sections.push(`[State: current]\n${compressed.trim()}`);
+    }
     // Full or self: load master + tree indexes
     const master = readIfExists(masterIndexPath());
     if (master)

package/dist/memory/scheduler.js

@@ -81,6 +81,17 @@ export function startScheduler() {
         return;
     ensureScaffold();
     void prunePrompts(); // run once on boot
+    // Rebuild the compressed memory view on boot so every session starts with
+    // current state. Runs in background, don't block scheduler startup.
+    void (async () => {
+        try {
+            const { ensureCompressedFresh } = await import('./compressed.js');
+            await ensureCompressedFresh();
+        }
+        catch (err) {
+            logger.error({ err }, 'compressed: boot rebuild failed');
+        }
+    })();
     sweepTimer = setInterval(() => {
         void sweep().catch((err) => logger.error({ err }, 'sweep failed'));
     }, config.memory.sweepIntervalMs);

package/dist/queue/worker.js

@@ -1,5 +1,6 @@
 import { askClaude } from '../ai/claude.js';
 import { clearSession, setSession, setUsage } from '../ai/sessions.js';
+import { config } from '../config.js';
 import { logger } from '../logger.js';
 import { extractFlags } from '../memory/digest-flag.js';
 import { appendEntry, createJournal, getJournal, isValidSlug, } from '../memory/journals.js';
@@ -10,11 +11,14 @@ function isStaleSessionError(err) {
         err.message.includes('No conversation found'));
 }
 async function callClaude(job) {
+    const startedAt = Date.now();
+    const wasFresh = !job.sessionId;
     const { reply, sessionId, usage } = await askClaude({
         input: job.input,
         sessionId: job.sessionId,
         allowedTools: job.allowedTools,
     });
+    const durationMs = Date.now() - startedAt;
     if (!job.sessionId) {
         setSession(job.jid, sessionId);
     }
@@ -83,7 +87,21 @@ async function callClaude(job) {
             allowedTools: job.allowedTools ?? 'all',
         });
     }
-    return { reply: clean };
+    return {
+        reply: clean,
+        stats: {
+            durationMs,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            cacheReadTokens: usage.cacheReadTokens,
+            totalContextTokens,
+            contextWindow: config.claude.contextWindow,
+            fresh: wasFresh,
+            hasDigest: digest !== null,
+            journalSlugs: journals.map((j) => j.slug),
+            asyncCount: asyncTasks.length,
+        },
+    };
 }
 function titleCase(slug) {
     return slug

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4t4/heyamigo",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "WhatsApp AI bot powered by Claude with long-term memory, browser control, and role-based access",
   "type": "module",
   "main": "dist/index.js",