@psiclawops/hypermem 0.9.1 → 0.9.3

package/dist/expertise-store.d.ts

@@ -0,0 +1,129 @@
+/**
+ * hypermem Expertise Store
+ *
+ * Stores domain expertise patterns — learned behaviors that make the Nth run
+ * better than the 1st. Two-phase lifecycle:
+ *   1. Observations: raw learnings logged from conversations, pipelines, reviews
+ *   2. Patterns: graduated observations with N≥3 confirming instances
+ *
+ * Patterns are agent-scoped but domain-tagged, enabling cross-agent queries.
+ * Patterns have confidence, frequency tracking, and decay on counter-evidence.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface ExpertiseObservation {
+    id: number;
+    agentId: string;
+    domain: string;
+    context: string | null;
+    observationText: string;
+    sourceType: 'conversation' | 'pipeline' | 'review' | 'manual';
+    sourceRef: string | null;
+    createdAt: string;
+}
+export interface ExpertisePattern {
+    id: number;
+    agentId: string;
+    domain: string;
+    patternText: string;
+    confidence: number;
+    frequency: number;
+    firstSeen: string;
+    lastConfirmed: string;
+    invalidatedAt: string | null;
+    invalidationReason: string | null;
+    decayScore: number;
+}
+export interface ExpertiseEvidence {
+    observationId: number;
+    patternId: number;
+    relationship: 'confirms' | 'contradicts';
+    createdAt: string;
+}
+export declare class ExpertiseStore {
+    private readonly db;
+    private readonly graduationThreshold;
+    constructor(db: DatabaseSync, graduationThreshold?: number);
+    /**
+     * Record a raw observation from any source.
+     */
+    record(agentId: string, observationText: string, domain: string, opts?: {
+        context?: string;
+        sourceType?: ExpertiseObservation['sourceType'];
+        sourceRef?: string;
+    }): ExpertiseObservation;
+    /**
+     * Get observations for an agent, optionally filtered by domain.
+     */
+    getObservations(agentId: string, opts?: {
+        domain?: string;
+        limit?: number;
+    }): ExpertiseObservation[];
+    /**
+     * Retrieve active expertise patterns for current work context.
+     * Returns patterns sorted by confidence DESC, frequency DESC.
+     * Excludes invalidated patterns by default.
+     */
+    query(agentId: string, domain: string, opts?: {
+        context?: string;
+        includeInvalidated?: boolean;
+        limit?: number;
+        minConfidence?: number;
+    }): ExpertisePattern[];
+    /**
+     * Cross-agent query: get patterns from any agent in a given domain.
+     * Useful for fleet-wide expertise ("what has any agent learned about X?").
+     */
+    queryFleet(domain: string, opts?: {
+        limit?: number;
+        minConfidence?: number;
+    }): ExpertisePattern[];
+    /**
+     * Graduate an observation to a pattern.
+     *
+     * If a similar pattern already exists (same agent, domain, and pattern text prefix match),
+     * increments its frequency and updates lastConfirmed instead of creating a duplicate.
+     *
+     * Auto-graduation happens when an observation has N≥graduationThreshold confirming
+     * evidence links. Can also be called manually.
+     */
+    graduate(agentId: string, observationId: number, opts?: {
+        patternText?: string;
+        confidence?: number;
+    }): ExpertisePattern | null;
+    /**
+     * Record evidence linking an observation to a pattern.
+     * If this pushes a pattern's contradicting evidence past threshold,
+     * auto-invalidates the pattern.
+     */
+    addEvidence(observationId: number, patternId: number, relationship: 'confirms' | 'contradicts'): void;
+    /**
+     * Check if any observations are ready for auto-graduation.
+     * An observation graduates when it has N≥threshold confirming evidence links.
+     * Returns the number of newly graduated patterns.
+     */
+    autoGraduate(agentId: string): number;
+    /**
+     * Mark a pattern as invalidated.
+     */
+    invalidate(patternId: number, reason: string): boolean;
+    /**
+     * List all active patterns for an agent, optionally filtered by domain.
+     */
+    list(agentId: string, opts?: {
+        domain?: string;
+        includeInvalidated?: boolean;
+    }): ExpertisePattern[];
+    /**
+     * Decay all patterns by a fixed rate. Similar to fact decay.
+     */
+    decayPatterns(agentId: string, decayRate?: number): number;
+    /**
+     * Get pattern and observation counts for an agent.
+     */
+    getStats(agentId: string): {
+        observations: number;
+        activePatterns: number;
+        invalidatedPatterns: number;
+    };
+}
+//# sourceMappingURL=expertise-store.d.ts.map

package/dist/expertise-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expertise-store.d.ts","sourceRoot":"","sources":["../src/expertise-store.ts"],"names":[],"mappings":"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"}

package/dist/expertise-store.js

@@ -0,0 +1,342 @@
+/**
+ * hypermem Expertise Store
+ *
+ * Stores domain expertise patterns — learned behaviors that make the Nth run
+ * better than the 1st. Two-phase lifecycle:
+ *   1. Observations: raw learnings logged from conversations, pipelines, reviews
+ *   2. Patterns: graduated observations with N≥3 confirming instances
+ *
+ * Patterns are agent-scoped but domain-tagged, enabling cross-agent queries.
+ * Patterns have confidence, frequency tracking, and decay on counter-evidence.
+ */
+function nowIso() {
+    return new Date().toISOString();
+}
+function parseObservationRow(row) {
+    return {
+        id: row.id,
+        agentId: row.agent_id,
+        domain: row.domain,
+        context: row.context || null,
+        observationText: row.observation_text,
+        sourceType: row.source_type,
+        sourceRef: row.source_ref || null,
+        createdAt: row.created_at,
+    };
+}
+function parsePatternRow(row) {
+    return {
+        id: row.id,
+        agentId: row.agent_id,
+        domain: row.domain,
+        patternText: row.pattern_text,
+        confidence: row.confidence,
+        frequency: row.frequency,
+        firstSeen: row.first_seen,
+        lastConfirmed: row.last_confirmed,
+        invalidatedAt: row.invalidated_at || null,
+        invalidationReason: row.invalidation_reason || null,
+        decayScore: row.decay_score,
+    };
+}
+// ── Graduation threshold ──
+const DEFAULT_GRADUATION_THRESHOLD = 3;
+export class ExpertiseStore {
+    db;
+    graduationThreshold;
+    constructor(db, graduationThreshold = DEFAULT_GRADUATION_THRESHOLD) {
+        this.db = db;
+        this.graduationThreshold = graduationThreshold;
+    }
+    // ── Observations ──
+    /**
+     * Record a raw observation from any source.
+     */
+    record(agentId, observationText, domain, opts) {
+        const now = nowIso();
+        const result = this.db.prepare(`
+      INSERT INTO expertise_observations
+        (agent_id, domain, context, observation_text, source_type, source_ref, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(agentId, domain, opts?.context || null, observationText, opts?.sourceType || 'conversation', opts?.sourceRef || null, now);
+        const id = Number(result.lastInsertRowid);
+        return {
+            id,
+            agentId,
+            domain,
+            context: opts?.context || null,
+            observationText,
+            sourceType: opts?.sourceType || 'conversation',
+            sourceRef: opts?.sourceRef || null,
+            createdAt: now,
+        };
+    }
+    /**
+     * Get observations for an agent, optionally filtered by domain.
+     */
+    getObservations(agentId, opts) {
+        let sql = 'SELECT * FROM expertise_observations WHERE agent_id = ?';
+        const params = [agentId];
+        if (opts?.domain) {
+            sql += ' AND domain = ?';
+            params.push(opts.domain);
+        }
+        sql += ' ORDER BY created_at DESC';
+        if (opts?.limit) {
+            sql += ' LIMIT ?';
+            params.push(opts.limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseObservationRow);
+    }
+    // ── Patterns ──
+    /**
+     * Retrieve active expertise patterns for current work context.
+     * Returns patterns sorted by confidence DESC, frequency DESC.
+     * Excludes invalidated patterns by default.
+     */
+    query(agentId, domain, opts) {
+        let sql = `
+      SELECT * FROM expertise_patterns
+      WHERE agent_id = ? AND domain = ?
+      AND decay_score < 0.8
+    `;
+        const params = [agentId, domain];
+        if (!opts?.includeInvalidated) {
+            sql += ' AND invalidated_at IS NULL';
+        }
+        if (opts?.minConfidence) {
+            sql += ' AND confidence >= ?';
+            params.push(opts.minConfidence);
+        }
+        sql += ' ORDER BY confidence DESC, frequency DESC';
+        if (opts?.limit) {
+            sql += ' LIMIT ?';
+            params.push(opts.limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parsePatternRow);
+    }
+    /**
+     * Cross-agent query: get patterns from any agent in a given domain.
+     * Useful for fleet-wide expertise ("what has any agent learned about X?").
+     */
+    queryFleet(domain, opts) {
+        let sql = `
+      SELECT * FROM expertise_patterns
+      WHERE domain = ?
+      AND invalidated_at IS NULL
+      AND decay_score < 0.8
+    `;
+        const params = [domain];
+        if (opts?.minConfidence) {
+            sql += ' AND confidence >= ?';
+            params.push(opts.minConfidence);
+        }
+        sql += ' ORDER BY confidence DESC, frequency DESC';
+        if (opts?.limit) {
+            sql += ' LIMIT ?';
+            params.push(opts.limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parsePatternRow);
+    }
+    /**
+     * Graduate an observation to a pattern.
+     *
+     * If a similar pattern already exists (same agent, domain, and pattern text prefix match),
+     * increments its frequency and updates lastConfirmed instead of creating a duplicate.
+     *
+     * Auto-graduation happens when an observation has N≥graduationThreshold confirming
+     * evidence links. Can also be called manually.
+     */
+    graduate(agentId, observationId, opts) {
+        // Get the observation
+        const obsRow = this.db.prepare('SELECT * FROM expertise_observations WHERE id = ? AND agent_id = ?').get(observationId, agentId);
+        if (!obsRow)
+            return null;
+        const obs = parseObservationRow(obsRow);
+        const patternText = opts?.patternText || obs.observationText;
+        const confidence = opts?.confidence || 0.7;
+        const now = nowIso();
+        // Check for existing similar pattern (same domain, prefix match)
+        const prefix = patternText.slice(0, 80);
+        const existing = this.db.prepare(`
+      SELECT * FROM expertise_patterns
+      WHERE agent_id = ? AND domain = ? AND pattern_text LIKE ?
+      AND invalidated_at IS NULL
+      LIMIT 1
+    `).get(agentId, obs.domain, `${prefix}%`);
+        if (existing) {
+            // Increment frequency and update
+            this.db.prepare(`
+        UPDATE expertise_patterns
+        SET frequency = frequency + 1,
+            confidence = MAX(confidence, ?),
+            last_confirmed = ?,
+            decay_score = MAX(decay_score - 0.1, 0)
+        WHERE id = ?
+      `).run(confidence, now, existing.id);
+            // Link evidence
+            this.db.prepare(`
+        INSERT INTO expertise_evidence (observation_id, pattern_id, relationship, created_at)
+        VALUES (?, ?, 'confirms', ?)
+      `).run(observationId, existing.id, now);
+            // Return updated pattern
+            const updated = this.db.prepare('SELECT * FROM expertise_patterns WHERE id = ?')
+                .get(existing.id);
+            return parsePatternRow(updated);
+        }
+        // Create new pattern
+        const result = this.db.prepare(`
+      INSERT INTO expertise_patterns
+        (agent_id, domain, pattern_text, confidence, frequency, first_seen, last_confirmed, decay_score)
+      VALUES (?, ?, ?, ?, 1, ?, ?, 0.0)
+    `).run(agentId, obs.domain, patternText, confidence, now, now);
+        const patternId = Number(result.lastInsertRowid);
+        // Link the graduating observation as evidence
+        this.db.prepare(`
+      INSERT INTO expertise_evidence (observation_id, pattern_id, relationship, created_at)
+      VALUES (?, ?, 'confirms', ?)
+    `).run(observationId, patternId, now);
+        return {
+            id: patternId,
+            agentId,
+            domain: obs.domain,
+            patternText,
+            confidence,
+            frequency: 1,
+            firstSeen: now,
+            lastConfirmed: now,
+            invalidatedAt: null,
+            invalidationReason: null,
+            decayScore: 0,
+        };
+    }
+    /**
+     * Record evidence linking an observation to a pattern.
+     * If this pushes a pattern's contradicting evidence past threshold,
+     * auto-invalidates the pattern.
+     */
+    addEvidence(observationId, patternId, relationship) {
+        const now = nowIso();
+        this.db.prepare(`
+      INSERT INTO expertise_evidence (observation_id, pattern_id, relationship, created_at)
+      VALUES (?, ?, ?, ?)
+    `).run(observationId, patternId, relationship, now);
+        if (relationship === 'confirms') {
+            // Boost the pattern
+            this.db.prepare(`
+        UPDATE expertise_patterns
+        SET frequency = frequency + 1,
+            last_confirmed = ?,
+            decay_score = MAX(decay_score - 0.05, 0)
+        WHERE id = ?
+      `).run(now, patternId);
+        }
+        else {
+            // Contradicting: increase decay, check if should invalidate
+            this.db.prepare(`
+        UPDATE expertise_patterns
+        SET decay_score = MIN(decay_score + 0.2, 1.0)
+        WHERE id = ?
+      `).run(patternId);
+            // Count contradictions vs confirmations
+            const counts = this.db.prepare(`
+        SELECT relationship, COUNT(*) as cnt
+        FROM expertise_evidence
+        WHERE pattern_id = ?
+        GROUP BY relationship
+      `).all(patternId);
+            const confirms = counts.find(c => c.relationship === 'confirms')?.cnt ?? 0;
+            const contradicts = counts.find(c => c.relationship === 'contradicts')?.cnt ?? 0;
+            // Auto-invalidate if contradictions exceed confirmations
+            if (contradicts > confirms) {
+                this.invalidate(patternId, 'auto: contradicting evidence exceeded confirmations');
+            }
+        }
+    }
+    /**
+     * Check if any observations are ready for auto-graduation.
+     * An observation graduates when it has N≥threshold confirming evidence links.
+     * Returns the number of newly graduated patterns.
+     */
+    autoGraduate(agentId) {
+        // Find observations with enough confirming evidence that aren't already patterns
+        const candidates = this.db.prepare(`
+      SELECT e.observation_id, COUNT(*) as confirm_count
+      FROM expertise_evidence e
+      JOIN expertise_observations o ON o.id = e.observation_id
+      WHERE o.agent_id = ?
+      AND e.relationship = 'confirms'
+      AND e.observation_id NOT IN (
+        SELECT DISTINCT e2.observation_id FROM expertise_evidence e2
+        JOIN expertise_patterns p ON p.id = e2.pattern_id
+        WHERE p.agent_id = ?
+      )
+      GROUP BY e.observation_id
+      HAVING COUNT(*) >= ?
+    `).all(agentId, agentId, this.graduationThreshold);
+        let graduated = 0;
+        for (const candidate of candidates) {
+            const result = this.graduate(agentId, candidate.observation_id);
+            if (result)
+                graduated++;
+        }
+        return graduated;
+    }
+    /**
+     * Mark a pattern as invalidated.
+     */
+    invalidate(patternId, reason) {
+        const now = nowIso();
+        const result = this.db.prepare(`
+      UPDATE expertise_patterns
+      SET invalidated_at = ?, invalidation_reason = ?, updated_at = ?
+      WHERE id = ? AND invalidated_at IS NULL
+    `).run(now, reason, now, patternId);
+        return result.changes > 0;
+    }
+    /**
+     * List all active patterns for an agent, optionally filtered by domain.
+     */
+    list(agentId, opts) {
+        let sql = 'SELECT * FROM expertise_patterns WHERE agent_id = ?';
+        const params = [agentId];
+        if (opts?.domain) {
+            sql += ' AND domain = ?';
+            params.push(opts.domain);
+        }
+        if (!opts?.includeInvalidated) {
+            sql += ' AND invalidated_at IS NULL';
+        }
+        sql += ' ORDER BY confidence DESC, frequency DESC';
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parsePatternRow);
+    }
+    /**
+     * Decay all patterns by a fixed rate. Similar to fact decay.
+     */
+    decayPatterns(agentId, decayRate = 0.005) {
+        const result = this.db.prepare(`
+      UPDATE expertise_patterns
+      SET decay_score = MIN(decay_score + ?, 1.0)
+      WHERE agent_id = ? AND decay_score < 1.0 AND invalidated_at IS NULL
+    `).run(decayRate, agentId);
+        return result.changes;
+    }
+    /**
+     * Get pattern and observation counts for an agent.
+     */
+    getStats(agentId) {
+        const obs = this.db.prepare('SELECT COUNT(*) as count FROM expertise_observations WHERE agent_id = ?').get(agentId);
+        const active = this.db.prepare('SELECT COUNT(*) as count FROM expertise_patterns WHERE agent_id = ? AND invalidated_at IS NULL').get(agentId);
+        const invalidated = this.db.prepare('SELECT COUNT(*) as count FROM expertise_patterns WHERE agent_id = ? AND invalidated_at IS NOT NULL').get(agentId);
+        return {
+            observations: obs.count,
+            activePatterns: active.count,
+            invalidatedPatterns: invalidated.count,
+        };
+    }
+}
+//# sourceMappingURL=expertise-store.js.map

package/dist/fact-store.d.ts

@@ -0,0 +1,90 @@
+/**
+ * hypermem Fact Store
+ *
+ * CRUD operations for facts (extracted knowledge that spans sessions).
+ * Facts live in the central library DB, tagged by agent_id.
+ * Facts have scope (agent/session/user), confidence, and decay.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { Fact, FactScope } from './types.js';
+export declare class FactStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Add a new fact. Checks for duplicates by content.
+     */
+    addFact(agentId: string, content: string, opts?: {
+        scope?: FactScope;
+        domain?: string;
+        confidence?: number;
+        visibility?: string;
+        sourceType?: string;
+        sourceSessionKey?: string;
+        sourceRef?: string;
+        expiresAt?: string;
+    }): Fact;
+    /**
+     * Get active facts for an agent.
+     */
+    getActiveFacts(agentId: string, opts?: {
+        scope?: FactScope;
+        domain?: string;
+        limit?: number;
+        minConfidence?: number;
+    }): Fact[];
+    /**
+     * Full-text search facts.
+     */
+    searchFacts(query: string, opts?: {
+        agentId?: string;
+        domain?: string;
+        visibility?: string;
+        limit?: number;
+    }): Fact[];
+    /**
+     * Mark an old fact as superseded by a new one.
+     *
+     * Sets `superseded_by` on the old fact row so it is excluded from active
+     * retrieval queries (both FTS and KNN paths check `superseded_by IS NULL`).
+     * Returns false if the fact is already superseded or does not exist.
+     */
+    markSuperseded(oldFactId: number, newFactId: number): boolean;
+    /**
+     * Find the most recent active fact for an agent whose content is a near-duplicate
+     * of the given content (same first 100 chars, different suffix, or same domain+topic).
+     * Used by the background indexer to detect supersedes relationships.
+     *
+     * Returns the existing fact id if a candidate is found, otherwise null.
+     */
+    findSupersedableByContent(agentId: string, content: string, opts?: {
+        domain?: string;
+    }): number | null;
+    /**
+     * Decay all facts by a fixed rate.
+     */
+    decayFacts(agentId: string, decayRate?: number): number;
+    /**
+     * Remove expired and fully decayed facts.
+     */
+    pruneFacts(agentId: string): number;
+    /**
+     * Get fact count for an agent.
+     */
+    getFactCount(agentId: string): number;
+    /**
+     * Get facts that were valid at a specific point in time.
+     * Returns facts where valid_from <= dateMs AND (invalid_at IS NULL OR invalid_at > dateMs).
+     * This enables "what was true on date X?" queries (Zep-competitive).
+     */
+    getFactsValidAt(agentId: string, dateMs: number, opts?: {
+        domain?: string;
+        limit?: number;
+    }): Fact[];
+    /**
+     * Mark a fact as invalid at a specific time (or now).
+     * Unlike supersede, this doesn't require a replacement fact.
+     * Used by contradiction detection to mark stale facts.
+     */
+    invalidateFact(factId: number, atDate?: string): boolean;
+}
+//# sourceMappingURL=fact-store.d.ts.map

package/dist/fact-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-store.d.ts","sourceRoot":"","sources":["../src/fact-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA6BlD,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;OAEG;IACH,OAAO,CACL,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,SAAS,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,IAAI;IA+EP;;OAEG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,SAAS,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GACA,IAAI,EAAE;IAkCT;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,IAAI,EAAE;IAoCV;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAY7D;;;;;;OAMG;IACH,yBAAyB,CACvB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACzB,MAAM,GAAG,IAAI;IA0BhB;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,MAAM;IAU7D;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAanC;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAOrC;;;;OAIG;IACH,eAAe,CACb,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GACA,IAAI,EAAE;IA4BT;;;;OAIG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO;CAUzD"}