@psiclawops/hypermem 0.5.0 → 0.5.2

package/dist/topic-synthesizer.js

@@ -0,0 +1,315 @@
+/**
+ * Topic Synthesizer
+ *
+ * Synthesizes compiled knowledge pages (wiki-style) from stale topics.
+ * Heuristic-only: no LLM calls. Uses content-type classifier + keystone scoring.
+ *
+ * Architecture: Karpathy LLM Wiki Pattern adapted for hypermem.
+ * Raw sources (messages.db) → Wiki (knowledge table) → Compositor (compose-time)
+ */
+import { classifyContentType } from './content-type-classifier.js';
+import { KnowledgeStore } from './knowledge-store.js';
+// ─── Configuration ──────────────────────────────────────────────
+const SYNTHESIS_STALE_MINUTES = 30;
+const SYNTHESIS_MIN_MESSAGES = 5;
+const SYNTHESIS_REGROWTH_THRESHOLD = 5;
+const SYNTHESIS_MAX_SUMMARY_CHARS = 800;
+const SYNTHESIS_MAX_DECISIONS = 10;
+const SYNTHESIS_MAX_QUESTIONS = 5;
+const LINT_FREQUENCY = 10;
+const LINT_STALE_DAYS = 7;
+// Export so tests can reference them
+export { SYNTHESIS_STALE_MINUTES, SYNTHESIS_MIN_MESSAGES, SYNTHESIS_REGROWTH_THRESHOLD, SYNTHESIS_MAX_SUMMARY_CHARS, SYNTHESIS_MAX_DECISIONS, SYNTHESIS_MAX_QUESTIONS, LINT_FREQUENCY, LINT_STALE_DAYS, };
+// ─── Helpers ────────────────────────────────────────────────────
+/**
+ * Score a message for keystone quality.
+ * Heuristic: count references (file paths, agent mentions, quoted content, backticks).
+ */
+function keystoneScore(msg) {
+    const text = msg.text_content || '';
+    let score = 0;
+    // File path references
+    const pathMatches = text.match(/\/[\w./\-]+/g) || [];
+    score += pathMatches.length * 0.3;
+    // Backtick code references (inline or block)
+    const backtickMatches = text.match(/`[^`]+`/g) || [];
+    score += backtickMatches.length * 0.2;
+    // Agent mentions (known patterns)
+    const agentMentions = text.match(/\b(forge|compass|clarity|sentinel|vanguard|anvil|pylon|vigil|bastion|relay|crucible)\b/gi) || [];
+    score += agentMentions.length * 0.25;
+    // Quoted content
+    const quotedMatches = text.match(/"[^"]{10,}"/g) || [];
+    score += quotedMatches.length * 0.15;
+    // Decision/spec content type boosts score
+    const classification = classifyContentType(text);
+    if (classification.type === 'decision')
+        score += 1.0;
+    else if (classification.type === 'spec')
+        score += 0.5;
+    else if (classification.type === 'preference')
+        score += 0.3;
+    // Length bonus (up to 0.5 for ~500 chars)
+    score += Math.min(text.length / 1000, 0.5);
+    return score;
+}
+/**
+ * Extract file artifact paths from a message's tool_calls JSON.
+ */
+function extractArtifacts(msg) {
+    if (!msg.tool_calls)
+        return [];
+    const artifacts = [];
+    try {
+        const calls = JSON.parse(msg.tool_calls);
+        if (!Array.isArray(calls))
+            return [];
+        for (const call of calls) {
+            const args = call.input || call.function?.arguments || call.arguments || {};
+            let parsed = args;
+            if (typeof parsed === 'string') {
+                try {
+                    parsed = JSON.parse(parsed);
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (typeof parsed !== 'object' || !parsed)
+                continue;
+            for (const key of ['path', 'file', 'filePath', 'file_path']) {
+                const val = parsed[key];
+                if (typeof val === 'string' && val.startsWith('/')) {
+                    artifacts.push(val);
+                }
+            }
+        }
+    }
+    catch {
+        // Malformed JSON — skip
+    }
+    return artifacts;
+}
+/**
+ * Truncate text to maxChars with head+tail preservation.
+ * head = 60% of budget, tail = 40%.
+ */
+function truncateHeadTail(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const headLen = Math.floor(maxChars * 0.6);
+    const tailLen = maxChars - headLen - 5; // 5 for " ... "
+    return text.slice(0, headLen) + ' ... ' + text.slice(text.length - tailLen);
+}
+/**
+ * Parse the message_count stored in a knowledge source_ref or metadata.
+ * source_ref format: "topic:<id>" — but we need to find message_count
+ * from when the synthesis was stored. We store it in the content itself
+ * as a comment, or we can read from the knowledge row's source_ref.
+ *
+ * Strategy: embed last message count in sourceRef as "topic:<id>:mc:<count>"
+ */
+function parseStoredMessageCount(sourceRef) {
+    if (!sourceRef)
+        return 0;
+    const match = sourceRef.match(/:mc:(\d+)$/);
+    return match ? parseInt(match[1], 10) : 0;
+}
+// ─── TopicSynthesizer ───────────────────────────────────────────
+export class TopicSynthesizer {
+    libraryDb;
+    getMessageDb;
+    config;
+    effectiveConfig;
+    constructor(libraryDb, getMessageDb, config) {
+        this.libraryDb = libraryDb;
+        this.getMessageDb = getMessageDb;
+        this.config = config;
+        this.effectiveConfig = {
+            SYNTHESIS_STALE_MINUTES: config?.SYNTHESIS_STALE_MINUTES ?? SYNTHESIS_STALE_MINUTES,
+            SYNTHESIS_MIN_MESSAGES: config?.SYNTHESIS_MIN_MESSAGES ?? SYNTHESIS_MIN_MESSAGES,
+            SYNTHESIS_REGROWTH_THRESHOLD: config?.SYNTHESIS_REGROWTH_THRESHOLD ?? SYNTHESIS_REGROWTH_THRESHOLD,
+            SYNTHESIS_MAX_SUMMARY_CHARS: config?.SYNTHESIS_MAX_SUMMARY_CHARS ?? SYNTHESIS_MAX_SUMMARY_CHARS,
+            SYNTHESIS_MAX_DECISIONS: config?.SYNTHESIS_MAX_DECISIONS ?? SYNTHESIS_MAX_DECISIONS,
+            SYNTHESIS_MAX_QUESTIONS: config?.SYNTHESIS_MAX_QUESTIONS ?? SYNTHESIS_MAX_QUESTIONS,
+            LINT_FREQUENCY: config?.LINT_FREQUENCY ?? LINT_FREQUENCY,
+            LINT_STALE_DAYS: config?.LINT_STALE_DAYS ?? LINT_STALE_DAYS,
+        };
+    }
+    /**
+     * Run one synthesis pass for an agent.
+     * Finds stale topics, synthesizes wiki pages, writes to knowledge table.
+     */
+    tick(agentId) {
+        const result = {
+            topicsSynthesized: 0,
+            topicsSkipped: 0,
+            knowledgeEntriesWritten: 0,
+        };
+        const cfg = this.effectiveConfig;
+        const staleThresholdMinutes = cfg.SYNTHESIS_STALE_MINUTES;
+        // Query stale topics for this agent
+        // "Stale" = updated_at older than SYNTHESIS_STALE_MINUTES ago
+        let staleTopics;
+        try {
+            staleTopics = this.libraryDb.prepare(`
+        SELECT * FROM topics
+        WHERE agent_id = ?
+          AND message_count >= ?
+          AND updated_at < datetime('now', '-${staleThresholdMinutes} minutes')
+        ORDER BY updated_at ASC
+      `).all(agentId, cfg.SYNTHESIS_MIN_MESSAGES);
+        }
+        catch {
+            return result;
+        }
+        if (staleTopics.length === 0)
+            return result;
+        const knowledgeStore = new KnowledgeStore(this.libraryDb);
+        for (const topic of staleTopics) {
+            // Check if existing synthesis exists
+            const existing = knowledgeStore.get(agentId, 'topic-synthesis', topic.name);
+            if (existing) {
+                // Only re-synthesize if message_count has grown by >= threshold
+                const storedMc = parseStoredMessageCount(existing.sourceRef);
+                const growth = topic.message_count - storedMc;
+                if (growth < cfg.SYNTHESIS_REGROWTH_THRESHOLD) {
+                    result.topicsSkipped++;
+                    continue;
+                }
+            }
+            // Get messages for this topic from per-agent messages.db
+            const messageDb = this.getMessageDb(agentId);
+            if (!messageDb) {
+                result.topicsSkipped++;
+                continue;
+            }
+            let messages;
+            try {
+                messages = messageDb.prepare(`
+          SELECT * FROM messages WHERE topic_id = ? ORDER BY created_at ASC
+        `).all(String(topic.id));
+            }
+            catch {
+                result.topicsSkipped++;
+                continue;
+            }
+            if (messages.length === 0) {
+                result.topicsSkipped++;
+                continue;
+            }
+            // Build synthesis
+            const content = this.synthesizeTopic(topic, messages, cfg);
+            // Upsert into knowledge table
+            const sourceRef = `topic:${topic.id}:mc:${topic.message_count}`;
+            knowledgeStore.upsert(agentId, 'topic-synthesis', topic.name, content, {
+                sourceType: 'synthesizer',
+                sourceRef,
+            });
+            result.topicsSynthesized++;
+            result.knowledgeEntriesWritten++;
+        }
+        return result;
+    }
+    /**
+     * Synthesize a wiki page for a topic from its messages.
+     */
+    synthesizeTopic(topic, messages, cfg) {
+        // Classify + score all messages
+        const scored = messages.map(msg => ({
+            msg,
+            classification: classifyContentType(msg.text_content || ''),
+            score: keystoneScore(msg),
+        }));
+        // Extract decisions: classified as decision with confidence >= 0.7, top N
+        const decisions = scored
+            .filter(m => m.classification.type === 'decision' && m.classification.confidence >= 0.7)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, cfg.SYNTHESIS_MAX_DECISIONS);
+        // Extract open questions: classified as discussion + ends with ?, no decision follow-up within 5 msgs
+        const openQuestions = [];
+        for (let i = 0; i < scored.length; i++) {
+            const item = scored[i];
+            const text = item.msg.text_content || '';
+            // Question detection: ends with ? OR is a discussion-type with question keywords
+            const isQuestion = /\?\s*$/.test(text.trim()) ||
+                (item.classification.type === 'discussion' && /\b(why|how|what|when|where|should|could|would|can|is there)\b/i.test(text));
+            if (!isQuestion)
+                continue;
+            // Check if there's a decision-type response within next 5 messages
+            const followup = scored.slice(i + 1, i + 6);
+            const hasDecisionFollowup = followup.some(f => f.classification.type === 'decision');
+            if (!hasDecisionFollowup) {
+                openQuestions.push(item);
+                if (openQuestions.length >= cfg.SYNTHESIS_MAX_QUESTIONS)
+                    break;
+            }
+        }
+        // Extract artifacts from tool_calls
+        const allArtifacts = new Set();
+        for (const { msg } of scored) {
+            for (const artifact of extractArtifacts(msg)) {
+                allArtifacts.add(artifact);
+            }
+        }
+        // Extract participants: unique agent_ids
+        const participants = [...new Set(messages.map(m => m.agent_id).filter(Boolean))];
+        // Build summary: top-3 scored messages, concatenated and truncated
+        const top3 = [...scored]
+            .sort((a, b) => b.score - a.score)
+            .slice(0, 3)
+            .map(m => (m.msg.text_content || '').trim())
+            .filter(t => t.length > 0)
+            .join(' ');
+        const summary = truncateHeadTail(top3, cfg.SYNTHESIS_MAX_SUMMARY_CHARS);
+        // Build the wiki page markdown
+        const lines = [];
+        lines.push(`# ${topic.name}`);
+        lines.push('');
+        lines.push(`**Status:** ${topic.status}`);
+        lines.push(`**Last activity:** ${topic.updated_at}`);
+        lines.push(`**Messages:** ${topic.message_count}`);
+        lines.push(`**Participants:** ${participants.join(', ') || 'unknown'}`);
+        lines.push('');
+        lines.push('## Summary');
+        lines.push(summary || '_No summary available_');
+        lines.push('');
+        lines.push('## Key Decisions');
+        if (decisions.length > 0) {
+            for (const { msg } of decisions) {
+                const text = (msg.text_content || '').trim();
+                const first = text.split('\n')[0].slice(0, 200);
+                lines.push(`- ${first}`);
+            }
+        }
+        else {
+            lines.push('_No key decisions recorded_');
+        }
+        lines.push('');
+        lines.push('## Open Questions');
+        if (openQuestions.length > 0) {
+            for (const { msg } of openQuestions) {
+                const text = (msg.text_content || '').trim();
+                const first = text.split('\n')[0].slice(0, 200);
+                lines.push(`- ${first}`);
+            }
+        }
+        else {
+            lines.push('_No open questions_');
+        }
+        lines.push('');
+        lines.push('## Artifacts');
+        if (allArtifacts.size > 0) {
+            for (const artifact of allArtifacts) {
+                lines.push(`- ${artifact}`);
+            }
+        }
+        else {
+            lines.push('_No artifacts recorded_');
+        }
+        lines.push('');
+        lines.push('## Cross-References');
+        lines.push('_Auto-generated — see knowledge graph for links_');
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=topic-synthesizer.js.map

package/dist/trigger-registry.d.ts

@@ -0,0 +1,63 @@
+/**
+ * hypermem Trigger Registry (W5)
+ *
+ * Centralizes ACA collection trigger definitions with owner/category metadata.
+ * Extracted from compositor.ts for independent testability and auditability.
+ *
+ * - TRIGGER_REGISTRY_VERSION: semver string for the registry schema
+ * - TRIGGER_REGISTRY_HASH:    12-char SHA-256 of (collection, keywords) per entry
+ * - logRegistryStartup():     emits version + hash on first Compositor boot
+ */
+/**
+ * A trigger definition maps a collection to the conversation signals that
+ * indicate it should be queried. When any keyword matches the user's latest
+ * message, the compositor fetches relevant chunks from that collection.
+ *
+ * Centralizing trigger logic here (not in workspace stubs) means:
+ * - One update propagates to all agents
+ * - Stubs become documentation, not code
+ * - Trigger logic can be tested independently
+ *
+ * W5 additions: owner, category, description (all optional — backward compat).
+ */
+export interface CollectionTrigger {
+    /** Collection path: governance/policy, identity/job, etc. */
+    collection: string;
+    /** Keywords that trigger this collection (case-insensitive) */
+    keywords: string[];
+    /** Max tokens to inject from this collection */
+    maxTokens?: number;
+    /** Max chunks to retrieve */
+    maxChunks?: number;
+    /** Which agent/team owns this trigger set */
+    owner?: string;
+    /** Logical grouping: 'governance' | 'identity' | 'memory' | 'operations' */
+    category?: string;
+    /** Human-readable purpose */
+    description?: string;
+}
+export declare const TRIGGER_REGISTRY_VERSION = "1.0.0";
+/**
+ * Default trigger registry for standard ACA collections.
+ * Covers the core ACA offload use case from Anvil's spec.
+ */
+export declare const TRIGGER_REGISTRY: CollectionTrigger[];
+/** Backward-compat alias — same reference as TRIGGER_REGISTRY */
+export declare const DEFAULT_TRIGGERS: CollectionTrigger[];
+/**
+ * 12-char SHA-256 of the registry's (collection, keywords) pairs.
+ * Changes when trigger definitions change; stable across metadata-only edits.
+ * Computed once at module load.
+ */
+export declare const TRIGGER_REGISTRY_HASH: string;
+/**
+ * Match a user message against the trigger registry.
+ * Returns triggered collections (deduplicated, ordered by trigger specificity).
+ */
+export declare function matchTriggers(userMessage: string, triggers: CollectionTrigger[]): CollectionTrigger[];
+/**
+ * Emit a one-line startup log with registry version, hash, and entry count.
+ * Call once per process via the Compositor constructor guard.
+ */
+export declare function logRegistryStartup(): void;
+//# sourceMappingURL=trigger-registry.d.ts.map

package/dist/trigger-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger-registry.d.ts","sourceRoot":"","sources":["../src/trigger-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,iBAAiB,EAiH/C,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,gBAAgB,qBAAmB,CAAC;AAIjD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAGrB,CAAC;AAIhB;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAAE,GAC5B,iBAAiB,EAAE,CAMrB;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC"}

package/dist/trigger-registry.js

@@ -0,0 +1,163 @@
+/**
+ * hypermem Trigger Registry (W5)
+ *
+ * Centralizes ACA collection trigger definitions with owner/category metadata.
+ * Extracted from compositor.ts for independent testability and auditability.
+ *
+ * - TRIGGER_REGISTRY_VERSION: semver string for the registry schema
+ * - TRIGGER_REGISTRY_HASH:    12-char SHA-256 of (collection, keywords) per entry
+ * - logRegistryStartup():     emits version + hash on first Compositor boot
+ */
+import { createHash } from 'node:crypto';
+// ─── Registry ─────────────────────────────────────────────────
+export const TRIGGER_REGISTRY_VERSION = '1.0.0';
+/**
+ * Default trigger registry for standard ACA collections.
+ * Covers the core ACA offload use case from Anvil's spec.
+ */
+export const TRIGGER_REGISTRY = [
+    {
+        collection: 'governance/policy',
+        keywords: [
+            'escalat', 'policy', 'decision state', 'green', 'yellow', 'red',
+            'council procedure', 'naming', 'mandate', 'compliance', 'governance',
+            'override', 'human review', 'irreversible',
+        ],
+        maxTokens: 1500,
+        maxChunks: 3,
+        owner: 'council',
+        category: 'governance',
+        description: 'Governance policy: escalation triggers, decision states, naming rules, compliance mandates',
+    },
+    {
+        collection: 'governance/charter',
+        keywords: [
+            'charter', 'mission', 'director', 'org', 'reporting', 'boundary',
+            'delegation', 'authority', 'jurisdiction',
+        ],
+        maxTokens: 1000,
+        maxChunks: 2,
+        owner: 'council',
+        category: 'governance',
+        description: 'Organizational charter: mission, director roles, authority boundaries, delegation scope',
+    },
+    {
+        collection: 'governance/comms',
+        keywords: [
+            'message', 'send', 'tier 1', 'tier 2', 'tier 3', 'async', 'dispatch',
+            'sessions_send', 'inter-agent', 'protocol', 'comms', 'ping', 'notify',
+        ],
+        maxTokens: 800,
+        maxChunks: 2,
+        owner: 'council',
+        category: 'governance',
+        description: 'Inter-agent communication protocols: message tiers, dispatch rules, session messaging',
+    },
+    {
+        collection: 'operations/agents',
+        keywords: [
+            'boot', 'startup', 'bootstrap', 'heartbeat', 'workqueue', 'checkpoint',
+            'session start', 'roll call', 'memory recall', 'dispatch inbox',
+        ],
+        maxTokens: 800,
+        maxChunks: 2,
+        owner: 'forge',
+        category: 'operations',
+        description: 'Agent operational procedures: boot sequence, heartbeat, work queue, session startup',
+    },
+    {
+        collection: 'identity/job',
+        keywords: [
+            'deliberat', 'council round', 'vote', 'response contract', 'rating',
+            'first response', 'second response', 'handoff', 'floor open',
+            'performance', 'output discipline', 'assessment',
+        ],
+        maxTokens: 1200,
+        maxChunks: 3,
+        owner: 'council',
+        category: 'identity',
+        description: 'Agent job definitions: council deliberation roles, response contracts, performance standards',
+    },
+    {
+        collection: 'identity/motivations',
+        keywords: [
+            'motivation', 'fear', 'tension', 'why do you', 'how do you feel',
+            'drives', 'values',
+        ],
+        maxTokens: 600,
+        maxChunks: 1,
+        owner: 'council',
+        category: 'identity',
+        description: 'Agent motivations and values: intrinsic drivers, tensions, emotional context',
+    },
+    {
+        collection: 'memory/decisions',
+        keywords: [
+            'remember', 'decision', 'we decided', 'previously', 'last time',
+            'history', 'past', 'earlier', 'recall', 'context',
+        ],
+        maxTokens: 1500,
+        maxChunks: 4,
+        owner: 'forge',
+        category: 'memory',
+        description: 'Decision history: past choices, previously agreed approaches, recalled context',
+    },
+    {
+        collection: 'identity/soul',
+        keywords: [
+            'who are you', 'your role', 'your purpose', 'your domain', 'your job',
+            'identity', 'soul', 'persona', 'what do you do', 'how do you work',
+            'your principles', 'your values', 'your seat',
+        ],
+        maxTokens: 1200,
+        maxChunks: 2,
+        owner: 'council',
+        category: 'identity',
+        description: 'Agent soul and persona: role definition, domain ownership, core principles',
+    },
+    {
+        collection: 'operations/tools',
+        keywords: [
+            'tool', 'config', 'command', 'cli', 'path', 'deploy', 'restart',
+            'openclaw', 'session_status', 'model', 'plugin', 'workspace path',
+            'how to', 'where is', 'which command', 'quick ref',
+        ],
+        maxTokens: 1200,
+        maxChunks: 3,
+        owner: 'forge',
+        category: 'operations',
+        description: 'Agent tooling reference: CLI commands, config paths, deployment procedures, quick reference',
+    },
+];
+/** Backward-compat alias — same reference as TRIGGER_REGISTRY */
+export const DEFAULT_TRIGGERS = TRIGGER_REGISTRY;
+// ─── Registry Hash ────────────────────────────────────────────
+/**
+ * 12-char SHA-256 of the registry's (collection, keywords) pairs.
+ * Changes when trigger definitions change; stable across metadata-only edits.
+ * Computed once at module load.
+ */
+export const TRIGGER_REGISTRY_HASH = createHash('sha256')
+    .update(JSON.stringify(TRIGGER_REGISTRY.map(t => ({ collection: t.collection, keywords: t.keywords }))))
+    .digest('hex')
+    .slice(0, 12);
+// ─── matchTriggers ────────────────────────────────────────────
+/**
+ * Match a user message against the trigger registry.
+ * Returns triggered collections (deduplicated, ordered by trigger specificity).
+ */
+export function matchTriggers(userMessage, triggers) {
+    if (!userMessage)
+        return [];
+    const lower = userMessage.toLowerCase();
+    return triggers.filter(t => t.keywords.some(kw => lower.includes(kw.toLowerCase())));
+}
+// ─── Startup Log ──────────────────────────────────────────────
+/**
+ * Emit a one-line startup log with registry version, hash, and entry count.
+ * Call once per process via the Compositor constructor guard.
+ */
+export function logRegistryStartup() {
+    console.log(`[hypermem:triggers] version=${TRIGGER_REGISTRY_VERSION} hash=${TRIGGER_REGISTRY_HASH} entries=${TRIGGER_REGISTRY.length}`);
+}
+//# sourceMappingURL=trigger-registry.js.map