iobroker.assistant 0.1.2

package/build/lib/memory.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * Long-term memory (roadmap #6) — durable facts the assistant remembers across sessions/restarts
+ * ("meine Tochter heißt Lena", "das WLAN-Passwort steht im Flur"). Storage is ioBroker-first: this store
+ * holds the facts in memory and emits an `onChange` callback; `main.ts` mirrors them into `memory.*` states
+ * (+ one editable object per entry) and, before each cloud-LLM call, injects them compactly into the system
+ * prompt (retrieval = "inject all", capped — enough for the handful of household facts a home assistant
+ * accumulates; semantic search can be added later without touching the storage format).
+ *
+ * The store itself is transport-agnostic and testable (CRUD + dedup + caps + persistence round-trip).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryStore = void 0;
+exports.buildMemoryPrompt = buildMemoryPrompt;
+/** In-memory long-term fact store with dedup, size caps and JSON persistence (no scheduling). */
+class MemoryStore {
+    opts;
+    entries = new Map();
+    seq = 0;
+    now;
+    maxEntries;
+    maxTextLength;
+    constructor(opts) {
+        this.opts = opts;
+        this.now = opts.now || Date.now;
+        this.maxEntries = opts.maxEntries ?? 100;
+        this.maxTextLength = opts.maxTextLength ?? 500;
+    }
+    /**
+     * Remember a fact. If `key` is given and already exists (or, without a key, an identical text exists),
+     * the existing entry is updated instead of duplicated. Enforces the size cap by dropping the oldest.
+     * Returns the stored entry, or null for empty text.
+     */
+    add(o) {
+        const text = (o.text || '').trim().slice(0, this.maxTextLength);
+        if (!text) {
+            return null;
+        }
+        const key = (o.key || '').trim().toLowerCase();
+        const source = o.source || '';
+        const now = this.now();
+        // Dedup: same key, or (keyless) identical text → update in place.
+        const existing = key
+            ? [...this.entries.values()].find(e => e.key === key)
+            : [...this.entries.values()].find(e => e.text.toLowerCase() === text.toLowerCase());
+        if (existing) {
+            existing.text = text;
+            existing.source = source || existing.source;
+            existing.updatedAt = now;
+            this.emitChange();
+            return existing;
+        }
+        const entry = { id: this.genId(now), text, key, source, createdAt: now, updatedAt: now };
+        this.entries.set(entry.id, entry);
+        this.enforceCap();
+        this.opts.log?.debug(`memory added: ${entry.id}${key ? ` [${key}]` : ''} "${text}"`);
+        this.emitChange();
+        return entry;
+    }
+    /** Update an entry's text by id. Returns true if it existed. */
+    update(id, text) {
+        const e = this.entries.get(id);
+        if (!e) {
+            return false;
+        }
+        const t = (text || '').trim().slice(0, this.maxTextLength);
+        if (!t) {
+            return this.forgetById(id);
+        }
+        e.text = t;
+        e.updatedAt = this.now();
+        this.emitChange();
+        return true;
+    }
+    /** Forget entries matching an id or a key. Returns the number removed. */
+    forget(idOrKey) {
+        const needle = (idOrKey || '').trim().toLowerCase();
+        if (!needle) {
+            return 0;
+        }
+        const victims = [...this.entries.values()].filter(e => e.id.toLowerCase() === needle || (e.key && e.key === needle));
+        for (const v of victims) {
+            this.entries.delete(v.id);
+        }
+        if (victims.length) {
+            this.emitChange();
+        }
+        return victims.length;
+    }
+    /** Remove exactly one entry by id (no key match). Returns true if it existed. */
+    forgetById(id) {
+        if (!this.entries.delete(id)) {
+            return false;
+        }
+        this.emitChange();
+        return true;
+    }
+    /** Forget everything. Returns the number removed. */
+    clear() {
+        const n = this.entries.size;
+        if (n) {
+            this.entries.clear();
+            this.emitChange();
+        }
+        return n;
+    }
+    /** All facts, newest-updated first. */
+    list() {
+        return [...this.entries.values()].sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    get(id) {
+        return this.entries.get(id);
+    }
+    size() {
+        return this.entries.size;
+    }
+    /** Load persisted facts (replacing the current set). Returns how many were restored. */
+    restore(list) {
+        this.entries.clear();
+        let n = 0;
+        for (const e of Array.isArray(list) ? list : []) {
+            if (!e || typeof e.id !== 'string' || typeof e.text !== 'string' || !e.text.trim()) {
+                continue;
+            }
+            this.entries.set(e.id, {
+                id: e.id,
+                text: e.text,
+                key: e.key || '',
+                source: e.source || '',
+                createdAt: e.createdAt || this.now(),
+                updatedAt: e.updatedAt || e.createdAt || this.now(),
+            });
+            n++;
+        }
+        this.enforceCap();
+        this.emitChange();
+        return n;
+    }
+    enforceCap() {
+        if (this.entries.size <= this.maxEntries) {
+            return;
+        }
+        // Drop the oldest (least-recently-updated) until within the cap.
+        const byAge = [...this.entries.values()].sort((a, b) => a.updatedAt - b.updatedAt);
+        for (const e of byAge) {
+            if (this.entries.size <= this.maxEntries) {
+                break;
+            }
+            this.entries.delete(e.id);
+        }
+    }
+    genId(now) {
+        return `m${now.toString(36)}${(this.seq++).toString(36)}`;
+    }
+    emitChange() {
+        try {
+            this.opts.onChange(this.list());
+        }
+        catch (e) {
+            this.opts.log?.warn(`memory onChange failed: ${e.message}`);
+        }
+    }
+}
+exports.MemoryStore = MemoryStore;
+/**
+ * Compact system-prompt block of all remembered facts (retrieval = "inject all"), localized header. Returns
+ * '' when there is nothing to inject. `budget` caps the number of characters to keep the prompt bounded.
+ */
+function buildMemoryPrompt(entries, lang, budget = 4000) {
+    if (!entries.length) {
+        return '';
+    }
+    const header = lang === 'ru'
+        ? 'Известные факты о пользователе/доме (используй их, если уместно; не выдумывай новые):'
+        : lang === 'de'
+            ? 'Bekannte Fakten über den Nutzer/Haushalt (nutze sie, wenn relevant; erfinde keine neuen):'
+            : 'Known facts about the user/household (use them when relevant; do not invent new ones):';
+    const lines = [];
+    let used = header.length;
+    for (const e of entries) {
+        const line = `- ${e.text}`;
+        if (used + line.length + 1 > budget) {
+            break;
+        }
+        lines.push(line);
+        used += line.length + 1;
+    }
+    return `${header}\n${lines.join('\n')}`;
+}
+//# sourceMappingURL=memory.js.map

package/build/lib/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/lib/memory.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Long-term memory (roadmap #6) — durable facts the assistant remembers across sessions/restarts\n * (\"meine Tochter heißt Lena\", \"das WLAN-Passwort steht im Flur\"). Storage is ioBroker-first: this store\n * holds the facts in memory and emits an `onChange` callback; `main.ts` mirrors them into `memory.*` states\n * (+ one editable object per entry) and, before each cloud-LLM call, injects them compactly into the system\n * prompt (retrieval = \"inject all\", capped — enough for the handful of household facts a home assistant\n * accumulates; semantic search can be added later without touching the storage format).\n *\n * The store itself is transport-agnostic and testable (CRUD + dedup + caps + persistence round-trip).\n */\n\n/** One remembered fact. Plain data so it round-trips through JSON for persistence. */\nexport interface MemoryEntry {\n    /** Short unique id (also the `memory.items.<id>` state-object segment). */\n    id: string;\n    /** The fact text. */\n    text: string;\n    /** Optional short key/topic (\"tochter\", \"wlan\") used for dedup and targeted forgetting; '' if none. */\n    key: string;\n    /** Where it came from (satellite / 'chat' / '' …), for context. */\n    source: string;\n    createdAt: number;\n    updatedAt: number;\n}\n\nexport interface MemoryStoreOptions {\n    /** Called whenever the list changes (add/update/forget/clear/restore) with the new list. */\n    onChange: (entries: MemoryEntry[]) => void;\n    /** Max number of stored facts; the oldest (by updatedAt) are dropped past this. Default 100. */\n    maxEntries?: number;\n    /** Max characters per fact (longer is truncated). Default 500. */\n    maxTextLength?: number;\n    log?: Pick<ioBroker.Log, 'debug' | 'info' | 'warn'>;\n    /** Injectable clock (tests). Defaults to `Date.now`. */\n    now?: () => number;\n}\n\n/** In-memory long-term fact store with dedup, size caps and JSON persistence (no scheduling). */\nexport class MemoryStore {\n    private readonly entries = new Map<string, MemoryEntry>();\n    private seq = 0;\n    private readonly now: () => number;\n    private readonly maxEntries: number;\n    private readonly maxTextLength: number;\n\n    constructor(private readonly opts: MemoryStoreOptions) {\n        this.now = opts.now || Date.now;\n        this.maxEntries = opts.maxEntries ?? 100;\n        this.maxTextLength = opts.maxTextLength ?? 500;\n    }\n\n    /**\n     * Remember a fact. If `key` is given and already exists (or, without a key, an identical text exists),\n     * the existing entry is updated instead of duplicated. Enforces the size cap by dropping the oldest.\n     * Returns the stored entry, or null for empty text.\n     */\n    add(o: { text: string; key?: string; source?: string }): MemoryEntry | null {\n        const text = (o.text || '').trim().slice(0, this.maxTextLength);\n        if (!text) {\n            return null;\n        }\n        const key = (o.key || '').trim().toLowerCase();\n        const source = o.source || '';\n        const now = this.now();\n\n        // Dedup: same key, or (keyless) identical text → update in place.\n        const existing = key\n            ? [...this.entries.values()].find(e => e.key === key)\n            : [...this.entries.values()].find(e => e.text.toLowerCase() === text.toLowerCase());\n        if (existing) {\n            existing.text = text;\n            existing.source = source || existing.source;\n            existing.updatedAt = now;\n            this.emitChange();\n            return existing;\n        }\n\n        const entry: MemoryEntry = { id: this.genId(now), text, key, source, createdAt: now, updatedAt: now };\n        this.entries.set(entry.id, entry);\n        this.enforceCap();\n        this.opts.log?.debug(`memory added: ${entry.id}${key ? ` [${key}]` : ''} \"${text}\"`);\n        this.emitChange();\n        return entry;\n    }\n\n    /** Update an entry's text by id. Returns true if it existed. */\n    update(id: string, text: string): boolean {\n        const e = this.entries.get(id);\n        if (!e) {\n            return false;\n        }\n        const t = (text || '').trim().slice(0, this.maxTextLength);\n        if (!t) {\n            return this.forgetById(id);\n        }\n        e.text = t;\n        e.updatedAt = this.now();\n        this.emitChange();\n        return true;\n    }\n\n    /** Forget entries matching an id or a key. Returns the number removed. */\n    forget(idOrKey: string): number {\n        const needle = (idOrKey || '').trim().toLowerCase();\n        if (!needle) {\n            return 0;\n        }\n        const victims = [...this.entries.values()].filter(\n            e => e.id.toLowerCase() === needle || (e.key && e.key === needle),\n        );\n        for (const v of victims) {\n            this.entries.delete(v.id);\n        }\n        if (victims.length) {\n            this.emitChange();\n        }\n        return victims.length;\n    }\n\n    /** Remove exactly one entry by id (no key match). Returns true if it existed. */\n    forgetById(id: string): boolean {\n        if (!this.entries.delete(id)) {\n            return false;\n        }\n        this.emitChange();\n        return true;\n    }\n\n    /** Forget everything. Returns the number removed. */\n    clear(): number {\n        const n = this.entries.size;\n        if (n) {\n            this.entries.clear();\n            this.emitChange();\n        }\n        return n;\n    }\n\n    /** All facts, newest-updated first. */\n    list(): MemoryEntry[] {\n        return [...this.entries.values()].sort((a, b) => b.updatedAt - a.updatedAt);\n    }\n\n    get(id: string): MemoryEntry | undefined {\n        return this.entries.get(id);\n    }\n\n    size(): number {\n        return this.entries.size;\n    }\n\n    /** Load persisted facts (replacing the current set). Returns how many were restored. */\n    restore(list: MemoryEntry[]): number {\n        this.entries.clear();\n        let n = 0;\n        for (const e of Array.isArray(list) ? list : []) {\n            if (!e || typeof e.id !== 'string' || typeof e.text !== 'string' || !e.text.trim()) {\n                continue;\n            }\n            this.entries.set(e.id, {\n                id: e.id,\n                text: e.text,\n                key: e.key || '',\n                source: e.source || '',\n                createdAt: e.createdAt || this.now(),\n                updatedAt: e.updatedAt || e.createdAt || this.now(),\n            });\n            n++;\n        }\n        this.enforceCap();\n        this.emitChange();\n        return n;\n    }\n\n    private enforceCap(): void {\n        if (this.entries.size <= this.maxEntries) {\n            return;\n        }\n        // Drop the oldest (least-recently-updated) until within the cap.\n        const byAge = [...this.entries.values()].sort((a, b) => a.updatedAt - b.updatedAt);\n        for (const e of byAge) {\n            if (this.entries.size <= this.maxEntries) {\n                break;\n            }\n            this.entries.delete(e.id);\n        }\n    }\n\n    private genId(now: number): string {\n        return `m${now.toString(36)}${(this.seq++).toString(36)}`;\n    }\n\n    private emitChange(): void {\n        try {\n            this.opts.onChange(this.list());\n        } catch (e) {\n            this.opts.log?.warn(`memory onChange failed: ${(e as Error).message}`);\n        }\n    }\n}\n\n/**\n * Compact system-prompt block of all remembered facts (retrieval = \"inject all\"), localized header. Returns\n * '' when there is nothing to inject. `budget` caps the number of characters to keep the prompt bounded.\n */\nexport function buildMemoryPrompt(entries: MemoryEntry[], lang: string, budget = 4000): string {\n    if (!entries.length) {\n        return '';\n    }\n    const header =\n        lang === 'ru'\n            ? 'Известные факты о пользователе/доме (используй их, если уместно; не выдумывай новые):'\n            : lang === 'de'\n              ? 'Bekannte Fakten über den Nutzer/Haushalt (nutze sie, wenn relevant; erfinde keine neuen):'\n              : 'Known facts about the user/household (use them when relevant; do not invent new ones):';\n    const lines: string[] = [];\n    let used = header.length;\n    for (const e of entries) {\n        const line = `- ${e.text}`;\n        if (used + line.length + 1 > budget) {\n            break;\n        }\n        lines.push(line);\n        used += line.length + 1;\n    }\n    return `${header}\\n${lines.join('\\n')}`;\n}\n"]}