daemora 1.0.0-alpha.0

package/dist/memory/DeclarativeMemoryStore.js

@@ -0,0 +1,195 @@
+/**
+ * DeclarativeMemoryStore — hermes-pattern two-file declarative memory.
+ *
+ *   data/memory/MEMORY.md   — your notes about the environment / project
+ *   data/memory/USER.md     — facts about the user
+ *
+ * Why two files, not one table:
+ *   - Human-editable. The user can open MEMORY.md and read it, fix it.
+ *   - Declarative format (one fact per entry, §-separated) discourages
+ *     task/TODO pollution.
+ *   - Char-bounded per target (USER: 1375, MEMORY: 2200). Full files
+ *     force the agent to prioritise what really matters — old items get
+ *     replaced rather than appended.
+ *   - Frozen snapshot at load() → mid-session writes DO touch disk but
+ *     the system-prompt copy doesn't change. Preserves the prefix cache
+ *     across an entire session.
+ *
+ * API mirrors hermes: add / replace / remove × target ∈ {memory, user}.
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { readFile, rename, writeFile, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { scanContent } from "../skills/SecurityScanner.js";
+import { createLogger } from "../util/logger.js";
+const log = createLogger("memory.declarative");
+const ENTRY_DELIMITER = "\n§\n";
+export const CHAR_LIMITS = {
+    memory: 2200,
+    user: 1375,
+};
+export const FILENAMES = {
+    memory: "MEMORY.md",
+    user: "USER.md",
+};
+export class DeclarativeMemoryStore {
+    memoryDir;
+    entries = { memory: [], user: [] };
+    snapshot = { memory: "", user: "" };
+    constructor(memoryDir) {
+        this.memoryDir = memoryDir;
+    }
+    /**
+     * Load from disk and capture a frozen system-prompt snapshot.
+     * Must be called before `formatForSystemPrompt`.
+     */
+    async load() {
+        if (!existsSync(this.memoryDir))
+            mkdirSync(this.memoryDir, { recursive: true });
+        for (const target of ["memory", "user"]) {
+            this.entries[target] = await this.readFileEntries(target);
+            this.snapshot[target] = this.renderBlock(target, this.entries[target]);
+        }
+        log.info({
+            memoryEntries: this.entries.memory.length,
+            userEntries: this.entries.user.length,
+        }, "declarative memory loaded");
+    }
+    /** Frozen system-prompt block. Empty string if the target is empty. */
+    formatForSystemPrompt(target) {
+        return this.snapshot[target];
+    }
+    async add(target, content) {
+        const trimmed = content.trim();
+        if (!trimmed)
+            return { success: false, message: "content must not be empty" };
+        const scan = scanContent(trimmed);
+        if (scan.blocked)
+            return { success: false, message: `rejected: ${scan.reason}` };
+        // Dedup
+        if (this.entries[target].includes(trimmed)) {
+            return {
+                success: false,
+                message: "duplicate entry — already present",
+                entryCount: this.entries[target].length,
+            };
+        }
+        const next = [...this.entries[target], trimmed];
+        const limitCheck = this.checkLimit(target, next);
+        if (!limitCheck.ok)
+            return { success: false, message: limitCheck.reason };
+        this.entries[target] = next;
+        await this.writeFileEntries(target);
+        return this.okResult(target, "added");
+    }
+    async replace(target, oldText, newContent) {
+        const oldTrim = oldText.trim();
+        const newTrim = newContent.trim();
+        if (!oldTrim || !newTrim)
+            return { success: false, message: "old_text and content are required" };
+        const scan = scanContent(newTrim);
+        if (scan.blocked)
+            return { success: false, message: `rejected: ${scan.reason}` };
+        const idx = this.entries[target].findIndex((e) => e === oldTrim);
+        if (idx < 0)
+            return { success: false, message: "old_text not found as an entry" };
+        const next = [...this.entries[target]];
+        next[idx] = newTrim;
+        const limitCheck = this.checkLimit(target, next);
+        if (!limitCheck.ok)
+            return { success: false, message: limitCheck.reason };
+        this.entries[target] = next;
+        await this.writeFileEntries(target);
+        return this.okResult(target, "replaced");
+    }
+    async remove(target, oldText) {
+        const oldTrim = oldText.trim();
+        if (!oldTrim)
+            return { success: false, message: "old_text is required" };
+        const idx = this.entries[target].findIndex((e) => e === oldTrim);
+        if (idx < 0)
+            return { success: false, message: "old_text not found as an entry" };
+        const next = [...this.entries[target]];
+        next.splice(idx, 1);
+        this.entries[target] = next;
+        await this.writeFileEntries(target);
+        return this.okResult(target, "removed");
+    }
+    listEntries(target) {
+        return [...this.entries[target]];
+    }
+    // ── internals ─────────────────────────────────────────────────────────
+    path(target) {
+        return join(this.memoryDir, FILENAMES[target]);
+    }
+    async readFileEntries(target) {
+        try {
+            const raw = await readFile(this.path(target), "utf-8");
+            const parts = raw
+                .split(ENTRY_DELIMITER)
+                .map((e) => e.trim())
+                .filter((e) => e.length > 0);
+            // Dedup preserving first-seen order
+            return Array.from(new Set(parts));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Atomic write via temp file + rename (safe under concurrent readers). */
+    async writeFileEntries(target) {
+        const file = this.path(target);
+        const content = this.entries[target].join(ENTRY_DELIMITER);
+        const dir = dirname(file);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const tmp = join(dir, `.${randomUUID()}.tmp`);
+        try {
+            await writeFile(tmp, content, { encoding: "utf-8" });
+            await rename(tmp, file);
+        }
+        catch (e) {
+            try {
+                await unlink(tmp);
+            }
+            catch { }
+            throw e;
+        }
+    }
+    renderBlock(target, entries) {
+        if (entries.length === 0)
+            return "";
+        const content = entries.join(ENTRY_DELIMITER);
+        const limit = CHAR_LIMITS[target];
+        const pct = Math.min(100, Math.round((content.length / limit) * 100));
+        const header = target === "user"
+            ? `USER PROFILE (who the user is) [${pct}% — ${content.length}/${limit} chars]`
+            : `MEMORY (your persistent notes) [${pct}% — ${content.length}/${limit} chars]`;
+        const sep = "=".repeat(46);
+        return `${sep}\n${header}\n${sep}\n${content}`;
+    }
+    checkLimit(target, entries) {
+        const total = entries.join(ENTRY_DELIMITER).length;
+        const limit = CHAR_LIMITS[target];
+        if (total > limit) {
+            return {
+                ok: false,
+                reason: `total ${total} chars exceeds ${target} limit ${limit} — remove or replace older entries first`,
+            };
+        }
+        return { ok: true };
+    }
+    okResult(target, verb) {
+        const entries = this.entries[target];
+        const chars = entries.join(ENTRY_DELIMITER).length;
+        return {
+            success: true,
+            message: `entry ${verb}`,
+            entryCount: entries.length,
+            chars,
+            limit: CHAR_LIMITS[target],
+        };
+    }
+}
+//# sourceMappingURL=DeclarativeMemoryStore.js.map

package/dist/memory/DeclarativeMemoryStore.js.map

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

package/dist/memory/MemoryStore.d.ts

@@ -0,0 +1,65 @@
+/**
+ * MemoryStore — long-term keyword memory for the agent.
+ *
+ * What this is
+ * ------------
+ *   A pair of tools — `memory_save` and `memory_recall` — let the agent
+ *   commit durable facts ("Zain's birthday is Oct 2", "we use pnpm, not
+ *   npm") and retrieve them across conversations.
+ *
+ * What this isn't
+ * ---------------
+ *   - Not episodic chat history. That's SessionStore.
+ *   - Not embeddings. Semantic recall is a separate tier that plugs in
+ *     later without migrating this table (just add a column).
+ *
+ * Ranking — BM25 via SQLite FTS5. Good enough for "remember the thing
+ * I told you last week" recall with no external dep.
+ */
+import type Database from "better-sqlite3";
+export interface MemoryEntry {
+    readonly id: string;
+    readonly content: string;
+    readonly tags: readonly string[];
+    readonly source: string;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export interface MemoryHit extends MemoryEntry {
+    /** FTS5 rank (lower is better — raw BM25 output). */
+    readonly rank: number;
+}
+export declare class MemoryStore {
+    private readonly db;
+    private readonly insertEntry;
+    private readonly selectOne;
+    private readonly deleteOne;
+    private readonly recall;
+    private readonly listRecent;
+    constructor(db: Database.Database);
+    save(opts: {
+        content: string;
+        tags?: readonly string[];
+        source?: string;
+    }): MemoryEntry;
+    /**
+     * BM25 recall. Query can be natural language — FTS5 tokenises it the
+     * same way as stored content so you don't need MATCH operators unless
+     * you want them.
+     *
+     *   tagsAny: at least one of these tags must be present (OR)
+     *   tagsAll: all of these tags must be present (AND)
+     */
+    search(query: string, opts?: {
+        limit?: number;
+        tagsAny?: readonly string[];
+        tagsAll?: readonly string[];
+    }): readonly MemoryHit[];
+    getById(id: string): MemoryEntry | null;
+    delete(id: string): boolean;
+    listRecentEntries(opts?: {
+        limit?: number;
+        offset?: number;
+    }): readonly MemoryEntry[];
+}
+//# sourceMappingURL=MemoryStore.d.ts.map

package/dist/memory/MemoryStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryStore.d.ts","sourceRoot":"","sources":["../../src/memory/MemoryStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAM3C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC5C,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AA2CD,qBAAa,WAAW;IAOV,OAAO,CAAC,QAAQ,CAAC,EAAE;IAN/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAEnB,EAAE,EAAE,QAAQ,CAAC,QAAQ;IAgClD,IAAI,CAAC,IAAI,EAAE;QACT,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,WAAW;IAaf;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE;QAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACxB,GAAG,SAAS,SAAS,EAAE;IAoB7B,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAgBvC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI3B,iBAAiB,CAAC,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,SAAS,WAAW,EAAE;CAgB1F"}

package/dist/memory/MemoryStore.js

@@ -0,0 +1,189 @@
+/**
+ * MemoryStore — long-term keyword memory for the agent.
+ *
+ * What this is
+ * ------------
+ *   A pair of tools — `memory_save` and `memory_recall` — let the agent
+ *   commit durable facts ("Zain's birthday is Oct 2", "we use pnpm, not
+ *   npm") and retrieve them across conversations.
+ *
+ * What this isn't
+ * ---------------
+ *   - Not episodic chat history. That's SessionStore.
+ *   - Not embeddings. Semantic recall is a separate tier that plugs in
+ *     later without migrating this table (just add a column).
+ *
+ * Ranking — BM25 via SQLite FTS5. Good enough for "remember the thing
+ * I told you last week" recall with no external dep.
+ */
+import { randomUUID } from "node:crypto";
+import { createLogger } from "../util/logger.js";
+const log = createLogger("memory.store");
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS memory_entries (
+  id          TEXT PRIMARY KEY,
+  content     TEXT NOT NULL,
+  tags_json   TEXT NOT NULL DEFAULT '[]',
+  source      TEXT NOT NULL DEFAULT 'agent',
+  created_at  INTEGER NOT NULL,
+  updated_at  INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS memory_entries_by_created
+  ON memory_entries (created_at DESC);
+
+-- Full-text search index — content + tags, tokenized with unicode61
+-- (lowercases, strips diacritics, splits on non-alphanum).
+CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5 (
+  content,
+  tags,
+  content='memory_entries',
+  content_rowid='rowid',
+  tokenize = 'unicode61 remove_diacritics 2'
+);
+
+-- Keep FTS in sync via triggers. FTS rebuild is O(N); we only need
+-- incremental maintenance here because entries are small + frequent.
+CREATE TRIGGER IF NOT EXISTS memory_ai AFTER INSERT ON memory_entries BEGIN
+  INSERT INTO memory_fts (rowid, content, tags)
+  VALUES (new.rowid, new.content, new.tags_json);
+END;
+CREATE TRIGGER IF NOT EXISTS memory_ad AFTER DELETE ON memory_entries BEGIN
+  INSERT INTO memory_fts (memory_fts, rowid, content, tags)
+  VALUES ('delete', old.rowid, old.content, old.tags_json);
+END;
+CREATE TRIGGER IF NOT EXISTS memory_au AFTER UPDATE ON memory_entries BEGIN
+  INSERT INTO memory_fts (memory_fts, rowid, content, tags)
+  VALUES ('delete', old.rowid, old.content, old.tags_json);
+  INSERT INTO memory_fts (rowid, content, tags)
+  VALUES (new.rowid, new.content, new.tags_json);
+END;
+`;
+export class MemoryStore {
+    db;
+    insertEntry;
+    selectOne;
+    deleteOne;
+    recall;
+    listRecent;
+    constructor(db) {
+        this.db = db;
+        db.exec(SCHEMA);
+        this.insertEntry = db.prepare(`INSERT INTO memory_entries (id, content, tags_json, source, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?)`);
+        this.selectOne = db.prepare(`SELECT id, content, tags_json AS tagsJson, source,
+              created_at AS createdAt, updated_at AS updatedAt
+       FROM memory_entries WHERE id = ?`);
+        this.deleteOne = db.prepare(`DELETE FROM memory_entries WHERE id = ?`);
+        this.recall = db.prepare(`SELECT e.id, e.content, e.tags_json AS tagsJson, e.source,
+              e.created_at AS createdAt, e.updated_at AS updatedAt,
+              m.rank
+       FROM memory_fts m
+       JOIN memory_entries e ON e.rowid = m.rowid
+       WHERE memory_fts MATCH ?
+       ORDER BY m.rank
+       LIMIT ?`);
+        this.listRecent = db.prepare(`SELECT id, content, tags_json AS tagsJson, source,
+              created_at AS createdAt, updated_at AS updatedAt
+       FROM memory_entries
+       ORDER BY created_at DESC
+       LIMIT ? OFFSET ?`);
+    }
+    save(opts) {
+        const id = randomUUID();
+        const now = Date.now();
+        const tags = Array.from(new Set((opts.tags ?? []).map((t) => t.trim()).filter(Boolean)));
+        const tagsJson = JSON.stringify(tags);
+        const content = opts.content.trim();
+        if (!content)
+            throw new Error("memory content cannot be empty");
+        const source = opts.source?.trim() || "agent";
+        this.insertEntry.run(id, content, tagsJson, source, now, now);
+        log.debug({ id, tagCount: tags.length, source }, "memory saved");
+        return { id, content, tags, source, createdAt: now, updatedAt: now };
+    }
+    /**
+     * BM25 recall. Query can be natural language — FTS5 tokenises it the
+     * same way as stored content so you don't need MATCH operators unless
+     * you want them.
+     *
+     *   tagsAny: at least one of these tags must be present (OR)
+     *   tagsAll: all of these tags must be present (AND)
+     */
+    search(query, opts = {}) {
+        const q = sanitiseFtsQuery(query);
+        if (!q)
+            return [];
+        const limit = Math.max(1, Math.min(opts.limit ?? 10, 100));
+        const rows = this.recall.all(q, limit);
+        const hits = rows.map((r) => ({
+            id: r.id,
+            content: r.content,
+            tags: JSON.parse(r.tagsJson),
+            source: r.source,
+            createdAt: r.createdAt,
+            updatedAt: r.updatedAt,
+            rank: r.rank,
+        }));
+        return applyTagFilters(hits, opts);
+    }
+    getById(id) {
+        const row = this.selectOne.get(id);
+        if (!row)
+            return null;
+        return {
+            id: row.id,
+            content: row.content,
+            tags: JSON.parse(row.tagsJson),
+            source: row.source,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+        };
+    }
+    delete(id) {
+        return this.deleteOne.run(id).changes > 0;
+    }
+    listRecentEntries(opts = {}) {
+        const limit = Math.max(1, Math.min(opts.limit ?? 50, 500));
+        const offset = Math.max(0, opts.offset ?? 0);
+        const rows = this.listRecent.all(limit, offset);
+        return rows.map((r) => ({
+            id: r.id,
+            content: r.content,
+            tags: JSON.parse(r.tagsJson),
+            source: r.source,
+            createdAt: r.createdAt,
+            updatedAt: r.updatedAt,
+        }));
+    }
+}
+/**
+ * FTS5 has its own query syntax. If we pass raw user text containing
+ * `:`, `(`, `"`, or stray `AND`/`OR` we get syntax errors. Escape each
+ * token individually and OR them together — that gives "hit if any of
+ * these words match" which matches user intuition for recall.
+ */
+function sanitiseFtsQuery(raw) {
+    const cleaned = raw
+        .split(/\s+/)
+        .map((t) => t.replace(/["'`]/g, "").trim())
+        .filter((t) => t.length > 0 && /[\p{L}\p{N}]/u.test(t));
+    if (cleaned.length === 0)
+        return "";
+    return cleaned.map((t) => `"${t}"`).join(" OR ");
+}
+function applyTagFilters(hits, opts) {
+    const any = opts.tagsAny?.map((t) => t.toLowerCase());
+    const all = opts.tagsAll?.map((t) => t.toLowerCase());
+    if (!any && !all)
+        return hits;
+    return hits.filter((h) => {
+        const lower = h.tags.map((t) => t.toLowerCase());
+        if (any && !any.some((t) => lower.includes(t)))
+            return false;
+        if (all && !all.every((t) => lower.includes(t)))
+            return false;
+        return true;
+    });
+}
+//# sourceMappingURL=MemoryStore.js.map

package/dist/memory/MemoryStore.js.map

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