@ixo/oracle-runtime 0.0.1

package/dist/plugins/matrix-group-chats/channel-memory.service.d.ts

@@ -0,0 +1,89 @@
+import { MatrixManager } from '@ixo/matrix';
+import { type OnModuleDestroy, type OnModuleInit } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { type Summarizer } from './channel-memory.summarizer.js';
+import { type ChannelMember, type ChannelMemoryChunk, type ObservedMessage, type PinnedFact } from './channel-memory.types.js';
+export interface ChannelMemoryServiceConfig {
+    dbPath?: string;
+    syncDebounceMs?: number;
+    oracleDid?: string;
+    /** Disable Matrix sync entirely (e.g. unit tests). */
+    matrixSyncDisabled?: boolean;
+}
+export declare const CHANNEL_MEMORY_SERVICE_CONFIG: unique symbol;
+export declare const CHANNEL_MEMORY_SUMMARIZER: unique symbol;
+/**
+ * Channel memory pipeline. One SQLite DB per Matrix room (under
+ * `dbPath/channel_memory/`), each synced as encrypted media to its own
+ * Matrix room. On first access the service tries to download the latest
+ * snapshot from the room before opening locally; on writes it schedules a
+ * debounced upload back to the room.
+ *
+ * Compaction triggers when the buffer hits a threshold, an idle timeout
+ * elapses, or the agent is about to be engaged (`compactJustInTime`).
+ */
+export declare class ChannelMemoryService implements OnModuleInit, OnModuleDestroy {
+    private readonly config;
+    private readonly overrides;
+    private readonly summarizer;
+    private static singleton;
+    private readonly buffer;
+    private readonly compactionInFlight;
+    private readonly rooms;
+    private readonly opening;
+    private rootDir;
+    private oracleDid;
+    private syncDebounceMs;
+    private matrixSyncDisabled;
+    constructor(config: ConfigService | null, overrides: ChannelMemoryServiceConfig | null, summarizer?: Summarizer);
+    static getInstance(): ChannelMemoryService | undefined;
+    /** Test-only — wipe the singleton so a fresh instance can register. */
+    static resetSingleton(): void;
+    onModuleInit(): void;
+    onModuleDestroy(): Promise<void>;
+    private dbPathFor;
+    private getRoom;
+    /**
+     * Restore from Matrix when the local file is missing. The snapshot is
+     * gzipped on upload (mirrors the user-DB pattern), so we gunzip on
+     * download and fall back to using the raw buffer when it's already a
+     * valid SQLite header (legacy snapshots).
+     */
+    private maybeRestoreFromMatrix;
+    private markDirty;
+    private syncToMatrix;
+    /** Public for the tier scheduler — force-flush all known rooms to Matrix. */
+    flushAll(): Promise<void>;
+    observeMessage(roomId: string, message: ObservedMessage): void;
+    compactJustInTime(roomId: string): Promise<void>;
+    private compact;
+    private compactInner;
+    /** Used by the tier scheduler — drives a rollup transaction for one room. */
+    rollupTier(roomId: string, sourceTier: number, olderThanTs: number, bucketMs: number, minChunksPerBucket: number): Promise<number>;
+    listOpenRoomIds(): string[];
+    recentChunks(roomId: string, limit?: number): Promise<ChannelMemoryChunk[]>;
+    oldestChunks(roomId: string, limit?: number): Promise<ChannelMemoryChunk[]>;
+    search(roomId: string, query: string, limit?: number): Promise<ChannelMemoryChunk[]>;
+    listPinnedFacts(roomId: string): Promise<PinnedFact[]>;
+    pinFact(args: {
+        roomId: string;
+        fact: string;
+        pinnedByDid: string;
+        sourceEventId?: string;
+    }): Promise<PinnedFact>;
+    unpinFact(roomId: string, factId: string): Promise<boolean>;
+    getMembers(roomId: string): Promise<ChannelMember[]>;
+    /**
+     * Pull the room member roster from Matrix (display names + matrix user IDs),
+     * upsert into the local DB. Returns the freshly fetched list — falls back
+     * to the cached roster if Matrix fetch fails.
+     */
+    refreshMembers(roomId: string, matrixManager?: MatrixManager): Promise<ChannelMember[]>;
+    /**
+     * Build the system-prompt-ready context block injected at the start of a
+     * group-room session. Combines member roster, pinned facts, recent +
+     * oldest summary chunks, and the last K verbatim messages.
+     */
+    buildSessionContext(roomId: string, matrixManager?: MatrixManager): Promise<string>;
+}
+//# sourceMappingURL=channel-memory.service.d.ts.map

package/dist/plugins/matrix-group-chats/channel-memory.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-memory.service.d.ts","sourceRoot":"","sources":["../../../src/plugins/matrix-group-chats/channel-memory.service.ts"],"names":[],"mappings":"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"}

package/dist/plugins/matrix-group-chats/channel-memory.service.js

@@ -0,0 +1,565 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var ChannelMemoryService_1;
+import { MatrixManager } from '@ixo/matrix';
+import { Inject, Injectable, Logger, Optional, } from '@nestjs/common';
+import { File } from 'node:buffer';
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { promisify } from 'node:util';
+import { gunzip, gzip } from 'node:zlib';
+import { getMediaFromRoomByStorageKey, uploadMediaToRoom, } from '../../matrix/checkpointer/matrix-upload-utils.js';
+import { ChannelMemoryRepo } from './channel-memory.repo.js';
+import { ChannelMemorySummarizer, } from './channel-memory.summarizer.js';
+const gzipAsync = promisify(gzip);
+const gunzipAsync = promisify(gunzip);
+const SQLITE_MAGIC = Buffer.from('SQLite format 3\0');
+const logger = new Logger('ChannelMemoryService');
+const COMPACT_BUFFER_THRESHOLD = 20;
+const COMPACT_IDLE_MS = 5 * 60 * 1000;
+const COMPACT_JIT_MIN = 5;
+const COMPACT_JIT_TIMEOUT_MS = 3000;
+const BUFFER_HARD_CAP = 40;
+const SESSION_INJECT_RECENT_CHUNKS = 8;
+const SESSION_INJECT_OLDEST_CHUNKS = 2;
+const SESSION_INJECT_LAST_MESSAGES = 15;
+const MATRIX_STORAGE_KEY = 'qiforge.channel_memory.v1';
+const DEFAULT_SYNC_DEBOUNCE_MS = 60 * 1000;
+const DEFAULT_DB_PATH = './data/channel_memory';
+export const CHANNEL_MEMORY_SERVICE_CONFIG = Symbol.for('CHANNEL_MEMORY_SERVICE_CONFIG');
+export const CHANNEL_MEMORY_SUMMARIZER = Symbol.for('CHANNEL_MEMORY_SUMMARIZER');
+/**
+ * Channel memory pipeline. One SQLite DB per Matrix room (under
+ * `dbPath/channel_memory/`), each synced as encrypted media to its own
+ * Matrix room. On first access the service tries to download the latest
+ * snapshot from the room before opening locally; on writes it schedules a
+ * debounced upload back to the room.
+ *
+ * Compaction triggers when the buffer hits a threshold, an idle timeout
+ * elapses, or the agent is about to be engaged (`compactJustInTime`).
+ */
+let ChannelMemoryService = class ChannelMemoryService {
+    static { ChannelMemoryService_1 = this; }
+    config;
+    overrides;
+    summarizer;
+    static singleton;
+    buffer = new Map();
+    compactionInFlight = new Map();
+    rooms = new Map();
+    opening = new Map();
+    rootDir;
+    oracleDid;
+    syncDebounceMs;
+    matrixSyncDisabled = false;
+    constructor(config, overrides, summarizer = new ChannelMemorySummarizer()) {
+        this.config = config;
+        this.overrides = overrides;
+        this.summarizer = summarizer;
+    }
+    static getInstance() {
+        return ChannelMemoryService_1.singleton;
+    }
+    /** Test-only — wipe the singleton so a fresh instance can register. */
+    static resetSingleton() {
+        ChannelMemoryService_1.singleton = undefined;
+    }
+    onModuleInit() {
+        const cfg = this.overrides ?? {};
+        const baseDir = cfg.dbPath ??
+            this.config?.get('SQLITE_DATABASE_PATH') ??
+            DEFAULT_DB_PATH;
+        this.rootDir = path.resolve(baseDir);
+        fs.mkdirSync(this.rootDir, { recursive: true });
+        this.oracleDid =
+            cfg.oracleDid ??
+                this.config?.get('ORACLE_ENTITY_DID') ??
+                this.config?.get('ORACLE_DID') ??
+                'unknown-oracle';
+        this.syncDebounceMs =
+            cfg.syncDebounceMs ??
+                Number(this.config?.get('CHANNEL_MEMORY_SYNC_INTERVAL_MS') ??
+                    DEFAULT_SYNC_DEBOUNCE_MS);
+        this.matrixSyncDisabled = cfg.matrixSyncDisabled ?? false;
+        ChannelMemoryService_1.singleton = this;
+        logger.log(`DB root ready at ${this.rootDir}`);
+    }
+    async onModuleDestroy() {
+        for (const entry of this.buffer.values()) {
+            if (entry.idleTimer)
+                clearTimeout(entry.idleTimer);
+        }
+        this.buffer.clear();
+        const flushes = [];
+        for (const [roomId, room] of this.rooms) {
+            if (room.syncTimer) {
+                clearTimeout(room.syncTimer);
+                room.syncTimer = null;
+            }
+            if (room.dirty || room.uploadInFlight) {
+                flushes.push(this.syncToMatrix(roomId).catch(() => undefined));
+            }
+        }
+        await Promise.allSettled(flushes);
+        for (const room of this.rooms.values()) {
+            try {
+                room.repo.close();
+            }
+            catch {
+                // ignore — best-effort shutdown
+            }
+        }
+        this.rooms.clear();
+        if (ChannelMemoryService_1.singleton === this) {
+            ChannelMemoryService_1.singleton = undefined;
+        }
+    }
+    // ── Per-room DB lifecycle ───────────────────────────────────────────────
+    dbPathFor(roomId) {
+        const hash = crypto
+            .createHash('sha256')
+            .update(`${roomId}|${this.oracleDid}`)
+            .digest('hex')
+            .slice(0, 24);
+        return path.join(this.rootDir, `${hash}.db`);
+    }
+    async getRoom(roomId) {
+        const existing = this.rooms.get(roomId);
+        if (existing)
+            return existing;
+        const opening = this.opening.get(roomId);
+        if (opening)
+            return opening;
+        const promise = (async () => {
+            const dbPath = this.dbPathFor(roomId);
+            await this.maybeRestoreFromMatrix(roomId, dbPath);
+            const repo = new ChannelMemoryRepo(dbPath);
+            const entry = {
+                repo,
+                dbPath,
+                dirty: false,
+                syncTimer: null,
+                uploadInFlight: null,
+                lastUploadedChecksum: undefined,
+            };
+            this.rooms.set(roomId, entry);
+            return entry;
+        })().finally(() => {
+            this.opening.delete(roomId);
+        });
+        this.opening.set(roomId, promise);
+        return promise;
+    }
+    /**
+     * Restore from Matrix when the local file is missing. The snapshot is
+     * gzipped on upload (mirrors the user-DB pattern), so we gunzip on
+     * download and fall back to using the raw buffer when it's already a
+     * valid SQLite header (legacy snapshots).
+     */
+    async maybeRestoreFromMatrix(roomId, dbPath) {
+        if (this.matrixSyncDisabled)
+            return;
+        if (fs.existsSync(dbPath))
+            return;
+        let remote;
+        try {
+            remote = await getMediaFromRoomByStorageKey(roomId, MATRIX_STORAGE_KEY);
+        }
+        catch (err) {
+            logger.warn(`Restore from Matrix failed for room=${roomId}; starting fresh. ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        if (!remote) {
+            logger.log(`No prior DB in Matrix for room=${roomId}; starting fresh`);
+            return;
+        }
+        let buffer;
+        try {
+            buffer = await gunzipAsync(remote.mediaBuffer);
+        }
+        catch {
+            if (remote.mediaBuffer.length >= 16 &&
+                remote.mediaBuffer.subarray(0, 16).equals(SQLITE_MAGIC)) {
+                buffer = remote.mediaBuffer;
+            }
+            else {
+                logger.warn(`Restored payload for room=${roomId} is neither valid gzip nor SQLite — starting fresh`);
+                return;
+            }
+        }
+        if (buffer.length < 16 || !buffer.subarray(0, 16).equals(SQLITE_MAGIC)) {
+            logger.warn(`Restored DB for room=${roomId} has invalid SQLite header — starting fresh`);
+            return;
+        }
+        const tmp = `${dbPath}.tmp`;
+        try {
+            await fsp.writeFile(tmp, buffer);
+            await fsp.rename(tmp, dbPath);
+            logger.log(`Restored channel-memory DB for room=${roomId} (${buffer.length} bytes)`);
+        }
+        catch (err) {
+            await fsp.unlink(tmp).catch(() => undefined);
+            throw err;
+        }
+    }
+    markDirty(roomId) {
+        const room = this.rooms.get(roomId);
+        if (!room)
+            return;
+        room.dirty = true;
+        if (this.matrixSyncDisabled)
+            return;
+        if (room.syncTimer)
+            clearTimeout(room.syncTimer);
+        room.syncTimer = setTimeout(() => {
+            this.syncToMatrix(roomId).catch((err) => {
+                logger.warn(`debounced sync failed for ${roomId}: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }, this.syncDebounceMs);
+    }
+    async syncToMatrix(roomId) {
+        if (this.matrixSyncDisabled)
+            return;
+        const room = this.rooms.get(roomId);
+        if (!room)
+            return;
+        if (room.uploadInFlight) {
+            await room.uploadInFlight;
+            if (!room.dirty)
+                return;
+        }
+        if (!room.dirty)
+            return;
+        const upload = (async () => {
+            room.repo.checkpoint();
+            const snapshotPath = `${room.dbPath}.snap-${Date.now()}`;
+            try {
+                await fsp.copyFile(room.dbPath, snapshotPath);
+                const raw = await fsp.readFile(snapshotPath);
+                const checksum = crypto.createHash('sha256').update(raw).digest('hex');
+                if (checksum === room.lastUploadedChecksum) {
+                    room.dirty = false;
+                    return;
+                }
+                const compressed = await gzipAsync(raw);
+                const file = new File([compressed], `${MATRIX_STORAGE_KEY}.db.gz`, {
+                    type: 'application/gzip',
+                    lastModified: Date.now(),
+                });
+                await uploadMediaToRoom(roomId, file, MATRIX_STORAGE_KEY);
+                room.dirty = false;
+                room.lastUploadedChecksum = checksum;
+                logger.log(`Uploaded DB to room=${roomId} (${raw.length}B raw, ${compressed.length}B gz)`);
+            }
+            finally {
+                await fsp.unlink(snapshotPath).catch(() => undefined);
+            }
+        })();
+        room.uploadInFlight = upload;
+        try {
+            await upload;
+        }
+        finally {
+            room.uploadInFlight = null;
+        }
+    }
+    /** Public for the tier scheduler — force-flush all known rooms to Matrix. */
+    async flushAll() {
+        const ids = Array.from(this.rooms.keys());
+        await Promise.allSettled(ids.map((id) => this.syncToMatrix(id)));
+    }
+    // ── Capture + compaction ────────────────────────────────────────────────
+    observeMessage(roomId, message) {
+        let entry = this.buffer.get(roomId);
+        if (!entry) {
+            entry = { messages: [], idleTimer: null };
+            this.buffer.set(roomId, entry);
+        }
+        entry.messages.push(message);
+        if (entry.idleTimer)
+            clearTimeout(entry.idleTimer);
+        entry.idleTimer = setTimeout(() => {
+            this.compact(roomId).catch((err) => logger.warn(`idle compaction failed for ${roomId}: ${err instanceof Error ? err.message : String(err)}`));
+        }, COMPACT_IDLE_MS);
+        if (entry.messages.length >= COMPACT_BUFFER_THRESHOLD) {
+            void this.compact(roomId).catch((err) => logger.warn(`threshold compaction failed for ${roomId}: ${err instanceof Error ? err.message : String(err)}`));
+        }
+        else if (entry.messages.length >= BUFFER_HARD_CAP) {
+            void this.compact(roomId);
+        }
+    }
+    async compactJustInTime(roomId) {
+        const entry = this.buffer.get(roomId);
+        if (!entry || entry.messages.length < COMPACT_JIT_MIN)
+            return;
+        const timeout = new Promise((resolve) => setTimeout(resolve, COMPACT_JIT_TIMEOUT_MS));
+        await Promise.race([this.compact(roomId), timeout]).catch((err) => logger.warn(`JIT compaction error for ${roomId}: ${err instanceof Error ? err.message : String(err)}`));
+    }
+    async compact(roomId) {
+        const inFlight = this.compactionInFlight.get(roomId);
+        if (inFlight)
+            return inFlight;
+        const promise = this.compactInner(roomId).finally(() => {
+            this.compactionInFlight.delete(roomId);
+        });
+        this.compactionInFlight.set(roomId, promise);
+        return promise;
+    }
+    async compactInner(roomId) {
+        const entry = this.buffer.get(roomId);
+        if (!entry || entry.messages.length === 0)
+            return;
+        const drained = entry.messages.slice();
+        entry.messages.length = 0;
+        if (entry.idleTimer) {
+            clearTimeout(entry.idleTimer);
+            entry.idleTimer = null;
+        }
+        const first = drained[0];
+        const last = drained[drained.length - 1];
+        if (!first || !last)
+            return;
+        const summary = await this.summarizer.summarize(drained);
+        if (!summary) {
+            entry.messages.unshift(...drained);
+            logger.warn(`summary unavailable; ${drained.length} msgs requeued for ${roomId}`);
+            return;
+        }
+        const chunk = {
+            id: crypto.randomUUID(),
+            roomId,
+            summary,
+            fromEventId: first.eventId,
+            toEventId: last.eventId,
+            fromTimestamp: first.timestamp,
+            toTimestamp: last.timestamp,
+            messageCount: drained.length,
+            participants: Array.from(new Set(drained.map((m) => m.senderDid))),
+            threadIds: Array.from(new Set(drained.map((m) => m.threadId))),
+            tier: 1,
+            createdAt: Date.now(),
+        };
+        try {
+            const room = await this.getRoom(roomId);
+            room.repo.insertChunk(chunk);
+            this.markDirty(roomId);
+            logger.log(`room=${roomId} chunk=${chunk.id} msgs=${chunk.messageCount} totalChunks=${room.repo.countChunks(roomId)}`);
+        }
+        catch (err) {
+            logger.error(`insertChunk failed for ${roomId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /** Used by the tier scheduler — drives a rollup transaction for one room. */
+    async rollupTier(roomId, sourceTier, olderThanTs, bucketMs, minChunksPerBucket) {
+        const room = await this.getRoom(roomId);
+        const candidates = room.repo.findRollupCandidates(roomId, {
+            sourceTier,
+            olderThanTs,
+            bucketMs,
+            minChunksPerBucket,
+        });
+        if (candidates.length === 0)
+            return 0;
+        let rolledUp = 0;
+        for (const candidate of candidates) {
+            const rollup = await this.summarizer.rollup(candidate.chunks.map((c) => c.summary));
+            if (!rollup)
+                continue;
+            const first = candidate.chunks[0];
+            const last = candidate.chunks[candidate.chunks.length - 1];
+            if (!first || !last)
+                continue;
+            const participants = Array.from(new Set(candidate.chunks.flatMap((c) => c.participants)));
+            const threadIds = Array.from(new Set(candidate.chunks.flatMap((c) => c.threadIds)));
+            const messageCount = candidate.chunks.reduce((n, c) => n + c.messageCount, 0);
+            const consolidated = {
+                id: crypto.randomUUID(),
+                roomId,
+                summary: rollup,
+                fromEventId: first.fromEventId,
+                toEventId: last.toEventId,
+                fromTimestamp: first.fromTimestamp,
+                toTimestamp: last.toTimestamp,
+                messageCount,
+                participants,
+                threadIds,
+                tier: candidate.toTier,
+                createdAt: Date.now(),
+            };
+            room.repo.replaceWithRollup(candidate.chunks.map((c) => c.id), consolidated);
+            rolledUp += candidate.chunks.length;
+        }
+        if (rolledUp > 0)
+            this.markDirty(roomId);
+        return rolledUp;
+    }
+    listOpenRoomIds() {
+        return Array.from(this.rooms.keys());
+    }
+    // ── Read APIs ───────────────────────────────────────────────────────────
+    async recentChunks(roomId, limit = SESSION_INJECT_RECENT_CHUNKS) {
+        const room = await this.getRoom(roomId);
+        return room.repo.recentChunks(roomId, limit);
+    }
+    async oldestChunks(roomId, limit = SESSION_INJECT_OLDEST_CHUNKS) {
+        const room = await this.getRoom(roomId);
+        return room.repo.oldestChunks(roomId, limit);
+    }
+    async search(roomId, query, limit = 10) {
+        const room = await this.getRoom(roomId);
+        return room.repo.searchChunks(roomId, query, limit);
+    }
+    async listPinnedFacts(roomId) {
+        const room = await this.getRoom(roomId);
+        return room.repo.listPinnedFacts(roomId);
+    }
+    async pinFact(args) {
+        const fact = {
+            id: crypto.randomUUID(),
+            roomId: args.roomId,
+            fact: args.fact,
+            pinnedByDid: args.pinnedByDid,
+            sourceEventId: args.sourceEventId,
+            createdAt: Date.now(),
+        };
+        const room = await this.getRoom(args.roomId);
+        room.repo.insertPinnedFact(fact);
+        this.markDirty(args.roomId);
+        return fact;
+    }
+    async unpinFact(roomId, factId) {
+        const room = await this.getRoom(roomId);
+        const ok = room.repo.deletePinnedFact(roomId, factId);
+        if (ok)
+            this.markDirty(roomId);
+        return ok;
+    }
+    async getMembers(roomId) {
+        const room = await this.getRoom(roomId);
+        return room.repo.getMembers(roomId);
+    }
+    /**
+     * Pull the room member roster from Matrix (display names + matrix user IDs),
+     * upsert into the local DB. Returns the freshly fetched list — falls back
+     * to the cached roster if Matrix fetch fails.
+     */
+    async refreshMembers(roomId, matrixManager = MatrixManager.getInstance()) {
+        try {
+            const info = await matrixManager.getRoomInfo(roomId);
+            const botUserId = matrixManager.getBotMatrixUserId();
+            const members = [];
+            for (const userId of info.joinedMemberIds) {
+                if (userId === botUserId)
+                    continue;
+                const displayName = await matrixManager.getCachedDisplayName(userId, roomId);
+                members.push({ matrixUserId: userId, displayName });
+            }
+            const room = await this.getRoom(roomId);
+            room.repo.upsertMembers(roomId, members);
+            this.markDirty(roomId);
+            return members;
+        }
+        catch (err) {
+            logger.warn(`refreshMembers failed for ${roomId}: ${err instanceof Error ? err.message : String(err)}`);
+            try {
+                const room = await this.getRoom(roomId);
+                return room.repo.getMembers(roomId);
+            }
+            catch {
+                return [];
+            }
+        }
+    }
+    /**
+     * Build the system-prompt-ready context block injected at the start of a
+     * group-room session. Combines member roster, pinned facts, recent +
+     * oldest summary chunks, and the last K verbatim messages.
+     */
+    async buildSessionContext(roomId, matrixManager = MatrixManager.getInstance()) {
+        const [members, recent, oldest, facts, recentMsgs] = await Promise.all([
+            this.refreshMembers(roomId, matrixManager),
+            this.recentChunks(roomId),
+            this.oldestChunks(roomId),
+            this.listPinnedFacts(roomId),
+            matrixManager
+                .getRecentRoomMessages(roomId, { limit: SESSION_INJECT_LAST_MESSAGES })
+                .catch((err) => {
+                logger.warn(`live recent fetch failed for ${roomId}: ${err instanceof Error ? err.message : String(err)}`);
+                return {
+                    messages: [],
+                };
+            }),
+        ]);
+        const sections = [];
+        sections.push(`You are participating in a Matrix group chat. User messages are prefixed with "[DisplayName]:" so you know who is speaking. Address users by their display name when relevant. Stay quiet unless explicitly mentioned, replied to, or already in an active thread with you.`);
+        if (members.length > 0) {
+            const lines = members
+                .map((m) => `- ${m.displayName} (${m.matrixUserId})`)
+                .join('\n');
+            sections.push(`## Members in this room\n${lines}`);
+        }
+        if (facts.length > 0) {
+            const lines = facts.map((f) => `- ${f.fact}`).join('\n');
+            sections.push(`## Pinned facts\n${lines}`);
+        }
+        const seen = new Set();
+        const ordered = [];
+        for (const c of oldest) {
+            if (!seen.has(c.id)) {
+                ordered.push(c);
+                seen.add(c.id);
+            }
+        }
+        for (const c of recent) {
+            if (!seen.has(c.id)) {
+                ordered.push(c);
+                seen.add(c.id);
+            }
+        }
+        if (ordered.length > 0) {
+            const lines = ordered
+                .map((c) => {
+                const when = new Date(c.toTimestamp).toISOString();
+                const tierTag = c.tier > 1 ? ` tier=${c.tier}` : '';
+                return `### [${when}${tierTag}] ${c.messageCount} msgs\n${c.summary}`;
+            })
+                .join('\n\n');
+            sections.push(`## Channel memory\n${lines}`);
+        }
+        if (recentMsgs.messages.length > 0) {
+            const lines = await Promise.all(recentMsgs.messages.map(async (m) => {
+                const dn = await matrixManager
+                    .getCachedDisplayName(m.sender, roomId)
+                    .catch(() => m.sender);
+                const when = new Date(m.timestamp).toISOString();
+                const thread = m.threadId ? ` thread=${m.threadId.slice(0, 10)}` : '';
+                return `[${dn} @ ${when}${thread}]: ${m.body}`;
+            }));
+            sections.push(`## Recent messages (verbatim)\n${lines.join('\n')}`);
+        }
+        sections.push(`Tools available for this room: search_channel_memory, recall_channel_memory, pin_room_fact, unpin_room_fact.`);
+        return sections.join('\n\n');
+    }
+};
+ChannelMemoryService = ChannelMemoryService_1 = __decorate([
+    Injectable(),
+    __param(0, Optional()),
+    __param(1, Optional()),
+    __param(1, Inject(CHANNEL_MEMORY_SERVICE_CONFIG)),
+    __param(2, Optional()),
+    __param(2, Inject(CHANNEL_MEMORY_SUMMARIZER)),
+    __metadata("design:paramtypes", [Object, Object, Object])
+], ChannelMemoryService);
+export { ChannelMemoryService };

package/dist/plugins/matrix-group-chats/channel-memory.summarizer.d.ts

@@ -0,0 +1,18 @@
+import { type ObservedMessage } from './channel-memory.types.js';
+export interface Summarizer {
+    summarize(messages: ObservedMessage[]): Promise<string | null>;
+    rollup(summaries: string[]): Promise<string | null>;
+}
+export declare class ChannelMemorySummarizer implements Summarizer {
+    /**
+     * Compact a batch of observed messages into a summary string.
+     * Returns null if the LLM call fails — caller should keep the buffer.
+     */
+    summarize(messages: ObservedMessage[]): Promise<string | null>;
+    /**
+     * Consolidate multiple tier-N summaries into a single tier-(N+1) summary.
+     * Used by the tier scheduler for week/month rollups.
+     */
+    rollup(summaries: string[]): Promise<string | null>;
+}
+//# sourceMappingURL=channel-memory.summarizer.d.ts.map

package/dist/plugins/matrix-group-chats/channel-memory.summarizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-memory.summarizer.d.ts","sourceRoot":"","sources":["../../../src/plugins/matrix-group-chats/channel-memory.summarizer.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAkDjE,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/D,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACrD;AAED,qBAAa,uBAAwB,YAAW,UAAU;IACxD;;;OAGG;IACG,SAAS,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA+BpE;;;OAGG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAiC1D"}