openclaw-clawmark 0.1.0

package/dist/sources/source.js

@@ -0,0 +1,39 @@
+import { logEvent } from "../db.js";
+import { openLcmSource } from "./lcm.js";
+import { openTranscriptSource } from "./transcripts.js";
+export function selectSource(config, db) {
+    const tryLcm = () => {
+        if (!config.lcmDbPath)
+            return null;
+        const lcm = openLcmSource(config.lcmDbPath);
+        const check = lcm.validate();
+        if (check.ok)
+            return lcm;
+        logEvent(db, {
+            eventType: "source_fallback",
+            memoryKey: "source.lcm",
+            newValue: check.reason,
+            source: "selectSource",
+        });
+        return null;
+    };
+    if (config.source === "lcm") {
+        const lcm = tryLcm();
+        if (!lcm)
+            throw new Error("Clawmark: CLAWMARK_SOURCE=lcm but the LCM database failed validation");
+        return lcm;
+    }
+    if (config.source === "transcripts") {
+        if (!config.transcriptsDir)
+            throw new Error("Clawmark: transcripts source requires CLAWMARK_TRANSCRIPTS_DIR");
+        return openTranscriptSource(config.transcriptsDir);
+    }
+    // auto
+    const lcm = tryLcm();
+    if (lcm)
+        return lcm;
+    if (!config.transcriptsDir) {
+        throw new Error("Clawmark: no usable message source (LCM invalid/missing and no CLAWMARK_TRANSCRIPTS_DIR)");
+    }
+    return openTranscriptSource(config.transcriptsDir);
+}

package/dist/sources/transcripts.d.ts

@@ -0,0 +1,2 @@
+import type { MessageSource } from "./source.js";
+export declare function openTranscriptSource(dir: string): MessageSource;

package/dist/sources/transcripts.js

@@ -0,0 +1,171 @@
+import fs from "node:fs";
+import path from "node:path";
+function parseCursor(cursor) {
+    if (cursor === null)
+        return null;
+    const idx = cursor.lastIndexOf(":");
+    if (idx <= 0)
+        return null;
+    return { file: cursor.slice(0, idx), offset: Number(cursor.slice(idx + 1)) };
+}
+function extractText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => typeof part === "string"
+            ? part
+            : part && typeof part === "object" && typeof part.text === "string"
+                ? part.text
+                : "")
+            .filter(Boolean)
+            .join("\n");
+    }
+    return "";
+}
+function parseLine(raw, file, lineOffset, sessionId) {
+    let entry;
+    try {
+        entry = JSON.parse(raw);
+    }
+    catch {
+        return { message: null };
+    }
+    const type = entry.type;
+    if (type !== "message" && type !== "custom_message")
+        return { message: null };
+    // Message payloads either carry role/content at the top level or under `message`.
+    const payload = entry.message && typeof entry.message === "object"
+        ? entry.message
+        : entry;
+    const role = typeof payload.role === "string" ? payload.role : null;
+    if (role !== "user" && role !== "assistant")
+        return { message: null };
+    const text = extractText(payload.content ?? payload.text);
+    if (!text.trim())
+        return { message: null };
+    const ts = typeof entry.timestamp === "string"
+        ? entry.timestamp
+        : typeof entry.timestamp === "number"
+            ? new Date(entry.timestamp).toISOString()
+            : new Date(0).toISOString();
+    return {
+        message: {
+            ref: `${file}:${lineOffset}`,
+            conversationId: sessionId,
+            role,
+            text,
+            ts,
+        },
+    };
+}
+function sessionIdOf(file) {
+    return path.basename(file).replace(/\.jsonl$/, "");
+}
+export function openTranscriptSource(dir) {
+    const listFiles = () => {
+        try {
+            return fs
+                .readdirSync(dir)
+                .filter((f) => f.endsWith(".jsonl"))
+                .sort();
+        }
+        catch {
+            return [];
+        }
+    };
+    const readFrom = (file, startOffset, limit, out) => {
+        const full = path.join(dir, file);
+        let buf;
+        try {
+            buf = fs.readFileSync(full);
+        }
+        catch {
+            return startOffset;
+        }
+        let offset = startOffset;
+        const sessionId = sessionIdOf(file);
+        while (offset < buf.length && out.length < limit) {
+            let end = buf.indexOf(0x0a, offset);
+            if (end === -1) {
+                // No trailing newline yet — the writer may still be mid-line; wait for the flush.
+                break;
+            }
+            const raw = buf.subarray(offset, end).toString("utf8").trim();
+            if (raw) {
+                const { message } = parseLine(raw, file, offset, sessionId);
+                if (message)
+                    out.push(message);
+            }
+            offset = end + 1;
+        }
+        return offset;
+    };
+    return {
+        name: "transcripts",
+        validate() {
+            if (!fs.existsSync(dir))
+                return { ok: false, reason: `transcripts dir not found: ${dir}` };
+            return { ok: true };
+        },
+        messagesAfter(cursor, limit) {
+            const files = listFiles();
+            if (files.length === 0)
+                return { messages: [], nextCursor: null };
+            const parsed = parseCursor(cursor);
+            const out = [];
+            let curFile = parsed?.file ?? files[0];
+            let curOffset = parsed?.offset ?? 0;
+            // If the cursor's file vanished (shouldn't happen — append-only), restart after it by name.
+            if (!files.includes(curFile)) {
+                const next = files.find((f) => f > curFile);
+                if (!next)
+                    return { messages: [], nextCursor: null };
+                curFile = next;
+                curOffset = 0;
+            }
+            let advanced = false;
+            for (let i = files.indexOf(curFile); i < files.length && out.length < limit; i++) {
+                const file = files[i];
+                const start = file === curFile ? curOffset : 0;
+                const newOffset = readFrom(file, start, limit, out);
+                if (newOffset > start || file !== curFile)
+                    advanced = true;
+                curFile = file;
+                curOffset = newOffset;
+                if (out.length >= limit)
+                    break;
+            }
+            if (out.length === 0 && !advanced)
+                return { messages: [], nextCursor: null };
+            return { messages: out, nextCursor: `${curFile}:${curOffset}` };
+        },
+        getMessages(refs) {
+            const out = [];
+            for (const ref of refs) {
+                const parsed = parseCursor(ref);
+                if (!parsed)
+                    continue;
+                const full = path.join(dir, parsed.file);
+                let buf;
+                try {
+                    buf = fs.readFileSync(full);
+                }
+                catch {
+                    continue;
+                }
+                const end = buf.indexOf(0x0a, parsed.offset);
+                const raw = buf
+                    .subarray(parsed.offset, end === -1 ? buf.length : end)
+                    .toString("utf8")
+                    .trim();
+                if (!raw)
+                    continue;
+                const { message } = parseLine(raw, parsed.file, parsed.offset, sessionIdOf(parsed.file));
+                if (message)
+                    out.push(message);
+            }
+            return out;
+        },
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,58 @@
+import type { ClawmarkConfig } from "./config.js";
+import type { Db } from "./db.js";
+import type { EmbeddingClient } from "./embeddings.js";
+import type { MessageSource } from "./sources/source.js";
+interface ToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: unknown;
+}
+export interface ClawmarkRuntime {
+    db: Db;
+    source: MessageSource;
+    embedder: EmbeddingClient;
+    config: ClawmarkConfig;
+}
+/**
+ * Tool definitions in the OpenClaw AgentTool shape. `clawmark_` prefix avoids
+ * collisions with native memory tools and other memory plugins. Runtime is resolved
+ * lazily so tools registered before gateway_start still work.
+ */
+export declare function buildTools(getRuntime: () => ClawmarkRuntime | null): ({
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        key: import("@sinclair/typebox").TString;
+        value: import("@sinclair/typebox").TString;
+    }>;
+    execute(_id: string, params: {
+        key: string;
+        value: string;
+    }): Promise<ToolResult>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        query: import("@sinclair/typebox").TString;
+        limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    }>;
+    execute(_id: string, params: {
+        query: string;
+        limit?: number;
+    }): Promise<ToolResult>;
+} | {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        key: import("@sinclair/typebox").TString;
+    }>;
+    execute(_id: string, params: {
+        key: string;
+    }): Promise<ToolResult>;
+})[];
+export {};

package/dist/tools.js

@@ -0,0 +1,79 @@
+import { Type } from "@sinclair/typebox";
+import { deleteFact, listFacts, setFact } from "./facts.js";
+import { recall } from "./recall.js";
+function text(value) {
+    return {
+        content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }],
+        details: {},
+    };
+}
+/**
+ * Tool definitions in the OpenClaw AgentTool shape. `clawmark_` prefix avoids
+ * collisions with native memory tools and other memory plugins. Runtime is resolved
+ * lazily so tools registered before gateway_start still work.
+ */
+export function buildTools(getRuntime) {
+    const requireRuntime = () => {
+        const rt = getRuntime();
+        if (!rt)
+            throw new Error("Clawmark is not initialized (gateway not started or config invalid)");
+        return rt;
+    };
+    return [
+        {
+            name: "clawmark_set",
+            label: "Clawmark: remember fact",
+            description: "Store a durable fact about the user (preference, decision, project, correction). " +
+                "Key must be lowercase dot-separated starting with pref./project./user./lesson., " +
+                'e.g. "pref.editor". User-set facts always win over extracted ones.',
+            parameters: Type.Object({
+                key: Type.String({ description: "Fact key, e.g. pref.editor" }),
+                value: Type.String({ description: "The fact itself, one or two sentences" }),
+            }),
+            async execute(_id, params) {
+                const { db, config } = requireRuntime();
+                const result = setFact(db, params.key, params.value, 1.0, "user", config.confidenceThreshold);
+                if (!result.ok)
+                    throw new Error(`clawmark_set rejected (${result.code}): ${result.reason}`);
+                return text(`Remembered ${params.key} (${result.action}).`);
+            },
+        },
+        {
+            name: "clawmark_search",
+            label: "Clawmark: search memory",
+            description: "Search stored facts and past conversation history. Returns matching facts and " +
+                "relevant excerpts from prior sessions.",
+            parameters: Type.Object({
+                query: Type.String({ description: "What to look for" }),
+                limit: Type.Optional(Type.Number({ description: "Max recall excerpts (default 6)" })),
+            }),
+            async execute(_id, params) {
+                const { db, source, embedder, config } = requireRuntime();
+                const q = params.query.toLowerCase();
+                const tokens = q.match(/[a-z0-9_]{2,}/g) ?? [];
+                const facts = listFacts(db).filter((f) => {
+                    const hay = `${f.key} ${f.value}`.toLowerCase();
+                    return tokens.some((t) => hay.includes(t));
+                });
+                const excerpts = await recall(db, source, embedder, params.query, params.limit ?? config.recallLimit);
+                return text({
+                    facts: facts.map((f) => ({ key: f.key, value: f.value, confidence: f.confidence })),
+                    recalled: excerpts.map((r) => ({ date: r.ts.slice(0, 10), role: r.role, excerpt: r.excerpt })),
+                });
+            },
+        },
+        {
+            name: "clawmark_forget",
+            label: "Clawmark: forget fact",
+            description: "Delete a stored fact by key. Use clawmark_search first to find the key.",
+            parameters: Type.Object({
+                key: Type.String({ description: "Fact key to delete" }),
+            }),
+            async execute(_id, params) {
+                const { db } = requireRuntime();
+                const deleted = deleteFact(db, params.key, "user");
+                return text(deleted ? `Forgot ${params.key}.` : `No fact stored under ${params.key}.`);
+            },
+        },
+    ];
+}

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "clawmark",
+  "name": "Clawmark",
+  "description": "Durable facts and semantic recall for OpenClaw, derived from the message history you already keep. No duplicate message store; crash-safe by design.",
+  "version": "0.1.0",
+  "contracts": {
+    "tools": ["clawmark_set", "clawmark_search", "clawmark_forget"]
+  }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "openclaw-clawmark",
+  "version": "0.1.0",
+  "description": "Clawmark — durable facts and semantic recall for OpenClaw, derived from the message history you already keep. No duplicate message store; crash-safe by design.",
+  "type": "module",
+  "license": "MIT",
+  "repository": "github:namitsingal/clawmark",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "memory",
+    "recall",
+    "embeddings"
+  ],
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.5.28"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "better-sqlite3": "^12.2.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.0.0",
+    "openclaw": "2026.6.11",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  }
+}