telegram-agent-memory 0.2.1

package/dist/telegram/TelegramMemory.js

@@ -0,0 +1,981 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelegramMemory = exports.TelegramMemoryConfigError = void 0;
+exports.createTelegramMemory = createTelegramMemory;
+exports.validateTelegramMemoryConfig = validateTelegramMemoryConfig;
+exports.assertValidTelegramMemoryConfig = assertValidTelegramMemoryConfig;
+exports.telegramMemoryConfigFromEnv = telegramMemoryConfigFromEnv;
+exports.createTelegramMemoryFromEnv = createTelegramMemoryFromEnv;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const AnthropicProvider_1 = require("../intelligence/AnthropicProvider");
+const OpenAIProvider_1 = require("../intelligence/OpenAIProvider");
+const file_memory_1 = require("./file-memory");
+const local_index_1 = require("./local-index");
+class TelegramMemoryConfigError extends Error {
+    constructor(message, issues) {
+        super(message);
+        this.name = 'TelegramMemoryConfigError';
+        this.issues = issues;
+    }
+}
+exports.TelegramMemoryConfigError = TelegramMemoryConfigError;
+const DEFAULT_STORAGE_DIR = node_path_1.default.resolve(process.cwd(), '.telegram-agent-memory');
+const DEFAULT_RECENT_DAYS = 3;
+const DEFAULT_MAX_PROFILE_FACTS = 40;
+const DEFAULT_MAX_FACTS_PER_MESSAGE = 8;
+const DEFAULT_PROFILE_CONTEXT_FACTS = 6;
+const DEFAULT_DAILY_CONTEXT_FACTS = 5;
+const DAILY_RECALL_MIN_SCORE = 0.45;
+const DEFAULT_SHARE_PROFILE_ACROSS_GROUPS = true;
+function clampImportance(value) {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        return 0.5;
+    }
+    return Math.max(0, Math.min(1, value));
+}
+function normalizeTags(tags) {
+    if (!Array.isArray(tags)) {
+        return [];
+    }
+    return Array.from(new Set(tags.map((tag) => String(tag).trim().toLowerCase()).filter(Boolean))).slice(0, 8);
+}
+function normalizeCategory(value) {
+    const trimmed = value?.trim().toLowerCase();
+    return trimmed || 'other';
+}
+function scoreFact(fact, query) {
+    const text = `${fact.summary}\n${fact.content}\n${fact.tags.join(' ')}`.toLowerCase();
+    const tokens = query
+        .toLowerCase()
+        .split(/\s+/)
+        .map((item) => item.trim())
+        .filter(Boolean);
+    let matchCount = 0;
+    for (const token of tokens) {
+        if (text.includes(token)) {
+            matchCount += 1;
+        }
+    }
+    const lexical = tokens.length === 0 ? 0.3 : matchCount / tokens.length;
+    return lexical * 0.7 + fact.importance * 0.3;
+}
+function formatDateKey(now) {
+    return now.toISOString().slice(0, 10);
+}
+function formatErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function maybeParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        const match = text.match(/\{[\s\S]*\}/);
+        if (!match) {
+            return null;
+        }
+        try {
+            return JSON.parse(match[0]);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+function ensureArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+class TelegramMemory {
+    constructor(config, deps = {}) {
+        assertValidTelegramMemoryConfig(config);
+        this.rawConfig = normalizeTelegramMemoryConfig(config);
+        this.provider = this.rawConfig.provider ?? 'openai';
+        this.logger = deps.logger;
+        this.now = deps.now ?? (() => new Date());
+        this.rootDir = node_path_1.default.resolve(this.rawConfig.storage?.rootDir ?? DEFAULT_STORAGE_DIR);
+        this.store = deps.store ?? new file_memory_1.TelegramFileMemoryStore(this.rootDir);
+        this.llm =
+            deps.llm ??
+                (this.provider === 'anthropic'
+                    ? new AnthropicProvider_1.AnthropicProvider({
+                        apiKey: this.rawConfig.anthropic.apiKey,
+                        model: this.rawConfig.anthropic?.model,
+                        baseURL: this.rawConfig.anthropic?.baseURL,
+                        headers: this.rawConfig.anthropic?.headers,
+                        logger: deps.logger,
+                    })
+                    : new OpenAIProvider_1.OpenAIProvider({
+                        apiKey: this.rawConfig.openai.apiKey,
+                        model: this.rawConfig.openai?.model,
+                        baseURL: this.rawConfig.openai?.baseURL,
+                        headers: this.rawConfig.openai?.headers,
+                        logger: deps.logger,
+                    }));
+        this.embedder =
+            deps.embedder ??
+                (this.rawConfig.openai?.embeddingModel
+                    ? new local_index_1.OpenAIEmbeddingProvider({
+                        apiKey: this.rawConfig.openai.apiKey,
+                        baseURL: this.rawConfig.openai?.baseURL,
+                        model: this.rawConfig.openai?.embeddingModel,
+                        headers: this.rawConfig.openai?.headers,
+                    })
+                    : new local_index_1.LocalEmbeddingProvider());
+        this.recentDays = Math.max(1, this.rawConfig.behavior?.recentDays ?? DEFAULT_RECENT_DAYS);
+        this.maxProfileFacts = Math.max(1, this.rawConfig.behavior?.maxProfileFacts ?? DEFAULT_MAX_PROFILE_FACTS);
+        this.maxFactsPerMessage = Math.max(1, this.rawConfig.behavior?.maxFactsPerMessage ?? DEFAULT_MAX_FACTS_PER_MESSAGE);
+        this.shareProfileAcrossGroups =
+            this.rawConfig.behavior?.shareProfileAcrossGroups ?? DEFAULT_SHARE_PROFILE_ACROSS_GROUPS;
+        this.whatToRemember = this.rawConfig.whatToRemember?.trim() || undefined;
+    }
+    async rememberTelegramMessage(message, actor) {
+        await this.store.ensureReady();
+        const extraction = await this.extractFacts(message, actor);
+        const profileFacts = ensureArray(extraction.profile_facts).slice(0, this.maxFactsPerMessage);
+        const dailyFacts = ensureArray(extraction.daily_facts).slice(0, this.maxFactsPerMessage);
+        const shouldStore = extraction.should_store !== false && (profileFacts.length > 0 || dailyFacts.length > 0);
+        if (!shouldStore) {
+            return {
+                profileFacts: [],
+                dailyFacts: [],
+                skipped: true,
+                summary: {
+                    added: 0,
+                    profile: 0,
+                    daily: 0,
+                },
+            };
+        }
+        const now = this.now();
+        const isoNow = now.toISOString();
+        const dateKey = formatDateKey(now);
+        const profile = await this.readWritableProfile(actor);
+        const effectiveProfileFacts = await this.collectProfileFacts(actor.groupId, actor.userId);
+        const baseProfile = {
+            ...profile,
+            facts: this.shareProfileAcrossGroups ? effectiveProfileFacts : profile.facts,
+        };
+        baseProfile.actor.username = actor.username ?? baseProfile.actor.username;
+        baseProfile.actor.groupId = actor.groupId;
+        const mergedProfile = this.mergeProfileFacts(baseProfile, effectiveProfileFacts, profileFacts, actor, message, isoNow);
+        baseProfile.facts = mergedProfile.nextFacts;
+        baseProfile.updatedAt = isoNow;
+        await this.writeWritableProfile(baseProfile);
+        const daily = await this.store.readDailyLog(actor.groupId, actor.userId, dateKey);
+        daily.actor.username = actor.username ?? daily.actor.username;
+        const mappedDailyFacts = dailyFacts.map((fact) => this.toStoredFact(fact, {
+            actor,
+            sourceText: message,
+            nowIso: isoNow,
+            kind: 'daily',
+            path: this.store.toRelativePath(node_path_1.default.join(this.rootDir, 'groups', actor.groupId, 'members', actor.userId, 'memory', `${dateKey}.md`)),
+        }));
+        daily.entries.push(...mappedDailyFacts);
+        daily.updatedAt = isoNow;
+        await this.store.writeDailyLog(daily);
+        await this.refreshLocalIndexSafely(actor.groupId, actor.userId);
+        this.logger?.info?.('TelegramMemory stored extracted facts.', {
+            userId: actor.userId,
+            groupId: actor.groupId,
+            profileFacts: mergedProfile.nextFacts.length,
+            addedProfileFacts: mergedProfile.addedFacts.length,
+            addedDailyFacts: mappedDailyFacts.length,
+        });
+        return {
+            profileFacts: mergedProfile.addedFacts,
+            dailyFacts: mappedDailyFacts,
+            skipped: false,
+            summary: {
+                added: mergedProfile.addedFacts.length + mappedDailyFacts.length,
+                profile: mergedProfile.addedFacts.length,
+                daily: mappedDailyFacts.length,
+            },
+        };
+    }
+    async remember(message, actor) {
+        return this.rememberTelegramMessage(message, actor);
+    }
+    async recall(query, options) {
+        const facts = await this.searchIndexedFacts(query, options);
+        return facts.slice(0, Math.max(1, options.limit ?? 8)).map((fact) => ({
+            id: fact.id,
+            kind: fact.kind,
+            content: fact.content,
+            summary: fact.summary,
+            category: fact.category,
+            importance: fact.importance,
+            score: fact.score,
+            path: fact.path,
+            updatedAt: fact.updatedAt,
+        }));
+    }
+    async buildPromptContext(query, options) {
+        const stableProfileFacts = this.store
+            .sortFactsByUpdatedAt(await this.collectProfileFacts(options.groupId, options.userId))
+            .sort((left, right) => right.importance - left.importance || scoreFact(right, query) - scoreFact(left, query))
+            .slice(0, DEFAULT_PROFILE_CONTEXT_FACTS);
+        const recentMemories = (await this.searchIndexedFacts(query, {
+            ...options,
+            includeProfile: false,
+            limit: DEFAULT_DAILY_CONTEXT_FACTS,
+        }))
+            .filter((fact) => fact.kind === 'daily' && fact.score >= DAILY_RECALL_MIN_SCORE)
+            .slice(0, DEFAULT_DAILY_CONTEXT_FACTS);
+        const memories = [
+            ...stableProfileFacts.map((fact) => ({
+                id: fact.id,
+                kind: fact.kind,
+                content: fact.content,
+                summary: fact.summary,
+                category: fact.category,
+                importance: fact.importance,
+                score: scoreFact(fact, query),
+                path: fact.path,
+                updatedAt: fact.updatedAt,
+            })),
+            ...recentMemories,
+        ];
+        const lines = [
+            `Telegram memory context for user ${options.userId} in group ${options.groupId}.`,
+            `Current message: ${query}`,
+            '',
+        ];
+        if (stableProfileFacts.length === 0) {
+            lines.push('Member profile:');
+            lines.push('- No saved profile yet.');
+        }
+        else {
+            lines.push('Member profile:');
+            for (const fact of stableProfileFacts) {
+                lines.push(`- ${fact.summary} | category=${fact.category} | importance=${fact.importance.toFixed(2)}`);
+            }
+        }
+        lines.push('');
+        if (recentMemories.length === 0) {
+            lines.push('Relevant recent memory:');
+            lines.push('- No relevant recent memory found.');
+        }
+        else {
+            lines.push('Relevant recent memory:');
+            for (const memory of recentMemories) {
+                lines.push(`- ${memory.summary} | date=${memory.updatedAt.slice(0, 10)} | category=${memory.category} | score=${memory.score.toFixed(2)}`);
+                lines.push(`  ${memory.content}`);
+            }
+        }
+        return {
+            text: `${lines.join('\n')}\n`,
+            memories,
+        };
+    }
+    async context(query, options) {
+        return this.buildPromptContext(query, options);
+    }
+    async getUserMemoryStats(userId, groupId) {
+        const stats = await this.store.getUserStats(groupId, userId);
+        const profileFacts = await this.collectProfileFacts(groupId, userId);
+        const profileTimestamps = profileFacts.map((fact) => fact.updatedAt);
+        const timestamps = [...profileTimestamps, stats.lastUpdatedAt]
+            .filter(Boolean)
+            .sort();
+        return {
+            profileFacts: profileFacts.length,
+            dailyFacts: stats.dailyFacts,
+            totalFacts: profileFacts.length + stats.dailyFacts,
+            lastUpdatedAt: timestamps.at(-1),
+        };
+    }
+    async getMemory(memoryId) {
+        return this.store.getFactById(memoryId);
+    }
+    async updateMemory(memoryId, updates) {
+        const existing = await this.store.getFactById(memoryId);
+        if (!existing) {
+            return null;
+        }
+        const actor = {
+            userId: existing.userId ?? '',
+            groupId: existing.groupId,
+        };
+        if (existing.kind === 'profile' && existing.userId) {
+            const profile = await this.readProfileForFact(existing);
+            const index = profile.facts.findIndex((fact) => fact.id === memoryId);
+            if (index === -1) {
+                return null;
+            }
+            const updated = {
+                ...profile.facts[index],
+                content: updates.content ?? profile.facts[index].content,
+                summary: updates.summary ?? profile.facts[index].summary,
+                importance: clampImportance(updates.importance ?? profile.facts[index].importance),
+                tags: updates.tags ? normalizeTags(updates.tags) : profile.facts[index].tags,
+                updatedAt: this.now().toISOString(),
+            };
+            profile.facts[index] = updated;
+            profile.updatedAt = updated.updatedAt;
+            await this.writeProfileForFact(profile, existing);
+            await this.refreshLocalIndexSafely(existing.groupId, existing.userId);
+            return updated;
+        }
+        if (existing.kind === 'daily' && existing.userId) {
+            const dateKey = node_path_1.default.basename(existing.path).replace(/\.md$/, '');
+            const daily = await this.store.readDailyLog(actor.groupId, actor.userId, dateKey);
+            const index = daily.entries.findIndex((fact) => fact.id === memoryId);
+            if (index === -1) {
+                return null;
+            }
+            const updated = {
+                ...daily.entries[index],
+                content: updates.content ?? daily.entries[index].content,
+                summary: updates.summary ?? daily.entries[index].summary,
+                importance: clampImportance(updates.importance ?? daily.entries[index].importance),
+                tags: updates.tags ? normalizeTags(updates.tags) : daily.entries[index].tags,
+                updatedAt: this.now().toISOString(),
+            };
+            daily.entries[index] = updated;
+            daily.updatedAt = updated.updatedAt;
+            await this.store.writeDailyLog(daily);
+            await this.refreshLocalIndexSafely(existing.groupId, existing.userId);
+            return updated;
+        }
+        return null;
+    }
+    async deleteMemory(memoryId) {
+        const existing = await this.store.getFactById(memoryId);
+        if (!existing?.userId) {
+            return false;
+        }
+        if (existing.kind === 'profile') {
+            const profile = await this.readProfileForFact(existing);
+            const nextFacts = profile.facts.filter((fact) => fact.id !== memoryId);
+            if (nextFacts.length === profile.facts.length) {
+                return false;
+            }
+            profile.facts = nextFacts;
+            profile.updatedAt = this.now().toISOString();
+            await this.writeProfileForFact(profile, existing);
+            await this.refreshLocalIndexSafely(existing.groupId, existing.userId);
+            return true;
+        }
+        const dateKey = node_path_1.default.basename(existing.path).replace(/\.md$/, '');
+        const daily = await this.store.readDailyLog(existing.groupId, existing.userId, dateKey);
+        const nextEntries = daily.entries.filter((fact) => fact.id !== memoryId);
+        if (nextEntries.length === daily.entries.length) {
+            return false;
+        }
+        daily.entries = nextEntries;
+        daily.updatedAt = this.now().toISOString();
+        await this.store.writeDailyLog(daily);
+        await this.refreshLocalIndexSafely(existing.groupId, existing.userId);
+        return true;
+    }
+    async getMemoryHistory(memoryId) {
+        const fact = await this.getMemory(memoryId);
+        return fact ? [fact] : [];
+    }
+    async checkHealth() {
+        const checks = [];
+        try {
+            await this.store.ensureReady();
+            const probeFile = node_path_1.default.join(this.rootDir, '.healthcheck');
+            await promises_1.default.writeFile(probeFile, 'ok', 'utf8');
+            await promises_1.default.unlink(probeFile);
+            checks.push({
+                name: 'storage',
+                ok: true,
+            });
+        }
+        catch (error) {
+            checks.push({
+                name: 'storage',
+                ok: false,
+                message: formatErrorMessage(error),
+            });
+        }
+        const apiKey = this.provider === 'anthropic'
+            ? (this.rawConfig.anthropic?.apiKey?.trim() ?? '')
+            : (this.rawConfig.openai?.apiKey?.trim() ?? '');
+        checks.push({
+            name: 'llm',
+            ok: Boolean(apiKey),
+            message: apiKey ? undefined : 'LLM provider API key is missing.',
+        });
+        return {
+            ok: checks.every((check) => check.ok),
+            checks,
+        };
+    }
+    async preflight() {
+        const checks = [
+            {
+                name: 'config',
+                ok: true,
+                fatal: true,
+                message: 'TelegramMemory configuration is present.',
+                details: {
+                    rootDir: this.rootDir,
+                    recentDays: this.recentDays,
+                    maxProfileFacts: this.maxProfileFacts,
+                },
+            },
+        ];
+        const health = await this.checkHealth();
+        const storage = health.checks.find((check) => check.name === 'storage');
+        const llm = health.checks.find((check) => check.name === 'llm');
+        checks.push({
+            name: 'storage',
+            ok: storage?.ok ?? false,
+            fatal: true,
+            message: storage?.message ?? 'Storage is writable.',
+        });
+        checks.push({
+            name: 'llm',
+            ok: llm?.ok ?? false,
+            fatal: true,
+            message: llm?.message ?? 'LLM provider configuration is available.',
+        });
+        const report = {
+            ok: checks.every((check) => check.ok || !check.fatal),
+            checks,
+        };
+        this.logger?.info?.('TelegramMemory preflight completed.', {
+            ok: report.ok,
+            checks: report.checks.map((check) => ({
+                name: check.name,
+                ok: check.ok,
+                fatal: check.fatal,
+            })),
+        });
+        return report;
+    }
+    async extractFacts(message, actor) {
+        const prompt = [
+            'You are extracting durable Telegram member memory.',
+            'Return strict JSON.',
+            'Only keep information worth remembering for future group interactions.',
+            'Schema:',
+            '{',
+            '  "should_store": boolean,',
+            '  "profile_facts": [{"kind":"profile","summary":"...","content":"...","category":"...","tags":["..."],"importance":0.0,"confidence":0.0}],',
+            '  "daily_facts": [{"kind":"daily","summary":"...","content":"...","category":"...","tags":["..."],"importance":0.0,"confidence":0.0}]',
+            '}',
+            'Profile facts are stable preferences, identity, habits, long-term relationships, ongoing work, recurring patterns.',
+            'Daily facts are recent events, plans, updates, one-off situations.',
+            'Do not include trivia, greetings, filler, or raw transcript copies.',
+            this.whatToRemember
+                ? `Additional memory policy from the user:\n${this.whatToRemember}`
+                : 'Additional memory policy from the user:\nUse the default policy only.',
+            `groupId: ${actor.groupId}`,
+            `userId: ${actor.userId}`,
+            `username: ${actor.username ?? ''}`,
+            `message: ${JSON.stringify(message)}`,
+        ].join('\n');
+        const raw = await this.llm.generate(prompt, {
+            temperature: 0.1,
+            maxTokens: 1200,
+            responseFormat: 'json_object',
+        });
+        const parsed = maybeParseJson(raw);
+        if (!parsed) {
+            this.logger?.warn?.('TelegramMemory extraction returned invalid JSON.', {
+                raw,
+                userId: actor.userId,
+                groupId: actor.groupId,
+            });
+            return { should_store: false, profile_facts: [], daily_facts: [] };
+        }
+        return parsed;
+    }
+    mergeProfileFacts(profile, effectiveProfileFacts, incomingFacts, actor, sourceText, nowIso) {
+        const bySummary = new Map();
+        const effectiveBySummary = new Map();
+        const addedFacts = [];
+        for (const fact of effectiveProfileFacts) {
+            effectiveBySummary.set(fact.summary.trim().toLowerCase(), fact);
+        }
+        for (const fact of profile.facts) {
+            bySummary.set(fact.summary.trim().toLowerCase(), fact);
+        }
+        for (const fact of incomingFacts) {
+            const key = fact.summary.trim().toLowerCase();
+            const mapped = this.toStoredFact(fact, {
+                actor,
+                sourceText,
+                nowIso,
+                kind: 'profile',
+                path: this.profileMarkdownPathForActor(actor),
+            });
+            const existingInCurrentGroup = bySummary.get(key);
+            const existingEffective = effectiveBySummary.get(key);
+            if (!existingInCurrentGroup && !existingEffective) {
+                bySummary.set(key, mapped);
+                addedFacts.push(mapped);
+                continue;
+            }
+            if (!existingInCurrentGroup) {
+                continue;
+            }
+            bySummary.set(key, {
+                ...existingInCurrentGroup,
+                content: mapped.content,
+                summary: mapped.summary,
+                category: mapped.category,
+                tags: normalizeTags([...existingInCurrentGroup.tags, ...mapped.tags]),
+                importance: Math.max(existingInCurrentGroup.importance, mapped.importance),
+                confidence: Math.max(existingInCurrentGroup.confidence, mapped.confidence),
+                updatedAt: nowIso,
+                sourceText: mapped.sourceText,
+            });
+        }
+        return {
+            nextFacts: this.store
+                .sortFactsByUpdatedAt(Array.from(bySummary.values()))
+                .slice(0, this.maxProfileFacts),
+            addedFacts,
+        };
+    }
+    toStoredFact(fact, params) {
+        return {
+            id: (0, node_crypto_1.randomUUID)(),
+            kind: params.kind,
+            scope: 'user',
+            userId: params.actor.userId,
+            groupId: params.actor.groupId,
+            content: fact.content.trim(),
+            summary: fact.summary.trim(),
+            category: normalizeCategory(fact.category),
+            tags: normalizeTags(fact.tags),
+            importance: clampImportance(fact.importance),
+            confidence: clampImportance(fact.confidence ?? 0.8),
+            sourceText: params.sourceText,
+            createdAt: params.nowIso,
+            updatedAt: params.nowIso,
+            path: params.path,
+        };
+    }
+    async searchIndexedFacts(query, options) {
+        const minImportance = options.minImportance ?? 0;
+        const limit = Math.max(1, options.limit ?? 8);
+        const allFacts = await this.collectFactsForUser(options.groupId, options.userId, Math.max(1, options.recentDays ?? this.recentDays), options.includeProfile !== false);
+        if (allFacts.length === 0) {
+            return [];
+        }
+        const index = await this.ensureLocalIndex(options.groupId, options.userId);
+        const now = this.now();
+        const queryTokens = (0, local_index_1.tokenizeQuery)(query);
+        const queryEmbedding = await this.embedQuery(query);
+        const indexedById = new Map(index.entries.map((entry) => [entry.factId, entry]));
+        return allFacts
+            .filter((fact) => fact.importance >= minImportance)
+            .map((fact) => {
+            const indexed = indexedById.get(fact.id);
+            const score = indexed
+                ? (0, local_index_1.scoreIndexedEntry)({
+                    entry: indexed,
+                    query,
+                    queryTokens,
+                    queryEmbedding,
+                    now,
+                })
+                : scoreFact(fact, query);
+            return {
+                id: fact.id,
+                kind: fact.kind,
+                content: fact.content,
+                summary: fact.summary,
+                category: fact.category,
+                importance: fact.importance,
+                score,
+                path: fact.path,
+                updatedAt: fact.updatedAt,
+            };
+        })
+            .sort((left, right) => right.score - left.score ||
+            new Date(right.updatedAt).getTime() - new Date(left.updatedAt).getTime())
+            .slice(0, limit);
+    }
+    async collectFactsForUser(groupId, userId, recentDays, includeProfile) {
+        const dailies = await this.store.listRecentDailyLogs(groupId, userId, recentDays);
+        const facts = [];
+        if (includeProfile) {
+            facts.push(...(await this.collectProfileFacts(groupId, userId)));
+        }
+        for (const daily of dailies) {
+            facts.push(...daily.entries);
+        }
+        return facts;
+    }
+    async ensureLocalIndex(groupId, userId) {
+        const current = await this.store.readLocalIndex(groupId, userId);
+        const facts = await this.collectFactsForUser(groupId, userId, 3650, true);
+        const factFingerprint = facts
+            .map((fact) => `${fact.id}:${fact.updatedAt}`)
+            .sort()
+            .join('|');
+        const indexFingerprint = current.entries
+            .map((entry) => `${entry.factId}:${entry.updatedAt}`)
+            .sort()
+            .join('|');
+        if (current.model === this.embedder.model && factFingerprint === indexFingerprint) {
+            return current;
+        }
+        try {
+            return await this.rebuildLocalIndex(groupId, userId, current, facts);
+        }
+        catch (error) {
+            this.logger?.warn?.('TelegramMemory local index rebuild failed. Falling back to lexical ranking.', {
+                error: formatErrorMessage(error),
+                userId,
+                groupId,
+            });
+            return current;
+        }
+    }
+    async rebuildLocalIndex(groupId, userId, existingIndex, knownFacts) {
+        const facts = knownFacts ?? (await this.collectFactsForUser(groupId, userId, 3650, true));
+        const previous = existingIndex ?? (await this.store.readLocalIndex(groupId, userId));
+        const reusable = new Map();
+        for (const entry of previous.entries) {
+            reusable.set(`${entry.factId}:${entry.updatedAt}:${previous.model}`, entry);
+        }
+        const entries = [];
+        const textsToEmbed = [];
+        const pendingFacts = [];
+        for (const fact of facts) {
+            const cacheKey = `${fact.id}:${fact.updatedAt}:${this.embedder.model}`;
+            const cached = reusable.get(cacheKey);
+            if (cached) {
+                entries.push(cached);
+                continue;
+            }
+            pendingFacts.push(fact);
+            textsToEmbed.push((0, local_index_1.buildEmbeddingInput)(fact));
+        }
+        if (pendingFacts.length > 0) {
+            const embeddings = await this.embedTexts(textsToEmbed);
+            for (let index = 0; index < pendingFacts.length; index += 1) {
+                const fact = pendingFacts[index];
+                entries.push({
+                    factId: fact.id,
+                    kind: fact.kind,
+                    path: fact.path,
+                    updatedAt: fact.updatedAt,
+                    summary: fact.summary,
+                    content: fact.content,
+                    category: fact.category,
+                    tags: fact.tags,
+                    importance: fact.importance,
+                    embedding: embeddings[index] ?? [],
+                });
+            }
+        }
+        const nextIndex = {
+            version: 1,
+            model: this.embedder.model,
+            updatedAt: this.now().toISOString(),
+            entries: entries.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt)),
+        };
+        await this.store.writeLocalIndex(groupId, userId, nextIndex);
+        return nextIndex;
+    }
+    async embedQuery(query) {
+        try {
+            const [embedding] = await this.embedTexts([query]);
+            return embedding ?? null;
+        }
+        catch (error) {
+            this.logger?.warn?.('TelegramMemory query embedding failed. Falling back to lexical ranking.', {
+                error: formatErrorMessage(error),
+            });
+            return null;
+        }
+    }
+    async embedTexts(texts) {
+        if (texts.length === 0) {
+            return [];
+        }
+        return this.embedder.embed(texts);
+    }
+    async refreshLocalIndexSafely(groupId, userId) {
+        try {
+            await this.rebuildLocalIndex(groupId, userId);
+        }
+        catch (error) {
+            this.logger?.warn?.('TelegramMemory local index refresh failed after write.', {
+                error: formatErrorMessage(error),
+                userId,
+                groupId,
+            });
+        }
+    }
+    async collectProfileFacts(groupId, userId) {
+        if (!this.shareProfileAcrossGroups) {
+            const profile = await this.store.readProfile(groupId, userId);
+            return profile.facts;
+        }
+        const sharedProfile = await this.store.readSharedProfile(userId, groupId);
+        const profiles = [sharedProfile, ...(await this.store.listGroupProfilesForUser(userId))];
+        const bySummary = new Map();
+        const allFacts = profiles
+            .flatMap((profile) => profile.facts)
+            .sort((left, right) => new Date(right.updatedAt).getTime() - new Date(left.updatedAt).getTime());
+        for (const fact of allFacts) {
+            const key = fact.summary.trim().toLowerCase();
+            const existing = bySummary.get(key);
+            if (!existing) {
+                bySummary.set(key, fact);
+                continue;
+            }
+            const newer = new Date(fact.updatedAt).getTime() > new Date(existing.updatedAt).getTime()
+                ? fact
+                : existing;
+            const older = newer === fact ? existing : fact;
+            bySummary.set(key, {
+                ...newer,
+                tags: normalizeTags([...newer.tags, ...older.tags]),
+                importance: Math.max(newer.importance, older.importance),
+                confidence: Math.max(newer.confidence, older.confidence),
+            });
+        }
+        return this.store.sortFactsByUpdatedAt(Array.from(bySummary.values()));
+    }
+    async readWritableProfile(actor) {
+        return this.shareProfileAcrossGroups
+            ? this.store.readSharedProfile(actor.userId, actor.groupId)
+            : this.store.readProfile(actor.groupId, actor.userId);
+    }
+    async writeWritableProfile(profile) {
+        if (this.shareProfileAcrossGroups) {
+            await this.store.writeSharedProfile(profile);
+            return;
+        }
+        await this.store.writeProfile(profile);
+    }
+    async readProfileForFact(fact) {
+        if (!fact.userId) {
+            throw new Error('Cannot read a profile fact without userId.');
+        }
+        return this.isSharedProfilePath(fact.path)
+            ? this.store.readSharedProfile(fact.userId, fact.groupId)
+            : this.store.readProfile(fact.groupId, fact.userId);
+    }
+    async writeProfileForFact(profile, fact) {
+        if (this.isSharedProfilePath(fact.path)) {
+            await this.store.writeSharedProfile(profile);
+            return;
+        }
+        await this.store.writeProfile(profile);
+    }
+    isSharedProfilePath(relativePath) {
+        return relativePath.split('/')[0] === 'users';
+    }
+    profileMarkdownPathForActor(actor) {
+        const absolutePath = this.shareProfileAcrossGroups
+            ? node_path_1.default.join(this.rootDir, 'users', actor.userId, 'PROFILE.md')
+            : node_path_1.default.join(this.rootDir, 'groups', actor.groupId, 'members', actor.userId, 'PROFILE.md');
+        return this.store.toRelativePath(absolutePath);
+    }
+}
+exports.TelegramMemory = TelegramMemory;
+async function createTelegramMemory(config, dependencies = {}) {
+    const normalized = normalizeTelegramMemoryConfig(config);
+    assertValidTelegramMemoryConfig(normalized);
+    const memory = new TelegramMemory(normalized, dependencies);
+    const report = await memory.preflight();
+    if (!report.ok) {
+        const fatalChecks = report.checks
+            .filter((check) => check.fatal && !check.ok)
+            .map((check) => `${check.name}: ${check.message ?? 'failed'}`);
+        throw new Error(`TelegramMemory preflight failed. ${fatalChecks.join('; ')}`);
+    }
+    return memory;
+}
+function validateTelegramMemoryConfig(config) {
+    const normalized = normalizeTelegramMemoryConfig(config);
+    const issues = [];
+    if (normalized.provider === 'anthropic') {
+        if (!normalized.anthropic?.apiKey?.trim()) {
+            issues.push({
+                field: 'anthropic.apiKey',
+                message: 'Anthropic API key is required when provider=anthropic.',
+            });
+        }
+    }
+    else if (!normalized.openai?.apiKey?.trim()) {
+        issues.push({
+            field: 'apiKey',
+            message: 'OpenAI-compatible API key is required when provider=openai.',
+        });
+    }
+    if (normalized.storage?.rootDir !== undefined && !normalized.storage.rootDir.trim()) {
+        issues.push({
+            field: 'dir',
+            message: 'dir cannot be empty.',
+        });
+    }
+    if (normalized.behavior?.recentDays !== undefined &&
+        (!Number.isFinite(normalized.behavior.recentDays) || normalized.behavior.recentDays <= 0)) {
+        issues.push({
+            field: 'behavior.recentDays',
+            message: 'behavior.recentDays must be greater than 0.',
+        });
+    }
+    if (normalized.behavior?.maxProfileFacts !== undefined &&
+        (!Number.isFinite(normalized.behavior.maxProfileFacts) ||
+            normalized.behavior.maxProfileFacts <= 0)) {
+        issues.push({
+            field: 'behavior.maxProfileFacts',
+            message: 'behavior.maxProfileFacts must be greater than 0.',
+        });
+    }
+    if (normalized.behavior?.maxFactsPerMessage !== undefined &&
+        (!Number.isFinite(normalized.behavior.maxFactsPerMessage) ||
+            normalized.behavior.maxFactsPerMessage <= 0)) {
+        issues.push({
+            field: 'behavior.maxFactsPerMessage',
+            message: 'behavior.maxFactsPerMessage must be greater than 0.',
+        });
+    }
+    return issues;
+}
+function assertValidTelegramMemoryConfig(config) {
+    const issues = validateTelegramMemoryConfig(config);
+    if (issues.length === 0) {
+        return;
+    }
+    throw new TelegramMemoryConfigError([
+        'Invalid TelegramMemory configuration:',
+        ...issues.map((issue) => `- ${issue.field}: ${issue.message}`),
+    ].join('\n'), issues);
+}
+function telegramMemoryConfigFromEnv(options = {}) {
+    const env = options.env ?? process.env;
+    const openAiHeaders = parseOptionalJsonObject(env.OPENAI_HEADERS_JSON);
+    const providerHeaders = {
+        ...openAiHeaders,
+        ...(env.OPENROUTER_HTTP_REFERER ? { 'HTTP-Referer': env.OPENROUTER_HTTP_REFERER } : {}),
+        ...(env.OPENROUTER_APP_NAME ? { 'X-Title': env.OPENROUTER_APP_NAME } : {}),
+    };
+    const config = {
+        provider: parseProvider(env.TELEGRAM_MEMORY_LLM_PROVIDER),
+        apiKey: env.OPENAI_API_KEY ?? '',
+        model: env.OPENAI_MODEL,
+        baseURL: env.OPENAI_BASE_URL,
+        embeddingModel: env.OPENAI_EMBEDDING_MODEL,
+        headers: Object.keys(providerHeaders).length > 0 ? providerHeaders : undefined,
+        dir: env.TELEGRAM_MEMORY_DIR || undefined,
+        whatToRemember: env.TELEGRAM_MEMORY_POLICY || undefined,
+        anthropic: {
+            apiKey: env.ANTHROPIC_API_KEY ?? '',
+            model: env.ANTHROPIC_MODEL,
+            baseURL: env.ANTHROPIC_BASE_URL,
+            headers: parseOptionalJsonObject(env.ANTHROPIC_HEADERS_JSON),
+        },
+        behavior: {
+            recentDays: parseOptionalInteger(env.TELEGRAM_MEMORY_RECENT_DAYS),
+            maxProfileFacts: parseOptionalInteger(env.TELEGRAM_MEMORY_MAX_PROFILE_FACTS),
+            maxFactsPerMessage: parseOptionalInteger(env.TELEGRAM_MEMORY_MAX_FACTS_PER_MESSAGE),
+            shareProfileAcrossGroups: parseOptionalBoolean(env.TELEGRAM_MEMORY_SHARE_PROFILE_ACROSS_GROUPS),
+        },
+    };
+    return normalizeTelegramMemoryConfig(config);
+}
+async function createTelegramMemoryFromEnv(options = {}, dependencies = {}) {
+    return createTelegramMemory(telegramMemoryConfigFromEnv(options), dependencies);
+}
+function parseOptionalInteger(value) {
+    if (!value?.trim()) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+function parseProvider(value) {
+    if (!value?.trim()) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'openai') {
+        return 'openai';
+    }
+    if (normalized === 'anthropic') {
+        return 'anthropic';
+    }
+    return undefined;
+}
+function parseOptionalBoolean(value) {
+    if (!value?.trim()) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+        return true;
+    }
+    if (['0', 'false', 'no', 'off'].includes(normalized)) {
+        return false;
+    }
+    return undefined;
+}
+function parseOptionalJsonObject(value) {
+    if (!value?.trim()) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        const entries = Object.entries(parsed)
+            .filter(([, entryValue]) => typeof entryValue === 'string')
+            .map(([key, entryValue]) => [key, entryValue]);
+        return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeTelegramMemoryConfig(config) {
+    const provider = config.provider ?? (config.anthropic?.apiKey ? 'anthropic' : 'openai');
+    const apiKey = config.apiKey ?? config.openai?.apiKey ?? '';
+    const model = config.model ?? config.openai?.model;
+    const baseURL = config.baseURL ?? config.openai?.baseURL;
+    const embeddingModel = config.embeddingModel ?? config.openai?.embeddingModel;
+    const headers = config.headers ?? config.openai?.headers;
+    const dir = config.dir ?? config.storage?.rootDir;
+    const shareProfileAcrossGroups = config.behavior?.shareProfileAcrossGroups;
+    const anthropicApiKey = config.anthropic?.apiKey ?? '';
+    const anthropicModel = config.anthropic?.model;
+    const anthropicBaseURL = config.anthropic?.baseURL;
+    const anthropicHeaders = config.anthropic?.headers;
+    return {
+        ...config,
+        provider,
+        apiKey,
+        model,
+        baseURL,
+        embeddingModel,
+        headers,
+        dir,
+        openai: {
+            apiKey,
+            model,
+            baseURL,
+            embeddingModel,
+            headers,
+        },
+        anthropic: {
+            apiKey: anthropicApiKey,
+            model: anthropicModel,
+            baseURL: anthropicBaseURL,
+            headers: anthropicHeaders,
+        },
+        storage: {
+            rootDir: dir,
+        },
+        behavior: {
+            ...config.behavior,
+            shareProfileAcrossGroups,
+        },
+    };
+}