openclaw-engram 0.2.0

package/dist/types/openclaw.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Local type definitions matching the real OpenClaw Plugin SDK.
+ *
+ * These are locally defined since no SDK package is published.
+ * Shapes match openclaw/openclaw:src/plugins/types.ts (verified via Nia research).
+ */
+/** Logger provided by the SDK on the plugin API. */
+export interface PluginLogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/** Runtime services exposed by the SDK. */
+export interface PluginRuntime {
+    tools: {
+        createMemorySearchTool(): unknown;
+    };
+}
+/** OpenClaw global config (opaque to plugins). */
+export type OpenClawConfig = Record<string, unknown>;
+/** JSON Schema for plugin config (static, declared in plugin definition). */
+export type OpenClawPluginConfigSchema = Record<string, unknown>;
+export interface OpenClawPluginApi {
+    /** Plugin ID. */
+    id: string;
+    /** Plugin display name. */
+    name: string;
+    /** OpenClaw global config. */
+    config: OpenClawConfig;
+    /** Plugin-specific config from the user's OpenClaw settings. */
+    pluginConfig?: Record<string, unknown>;
+    /** Runtime services. */
+    runtime: PluginRuntime;
+    /** Logger scoped to this plugin. */
+    logger: PluginLogger;
+    /** Register a tool or tool factory. */
+    registerTool(toolOrFactory: AnyAgentTool | AnyAgentTool[] | ToolFactory, opts?: {
+        names?: string[];
+    }): void;
+    /** Register a lifecycle hook handler (typed). */
+    on<K extends PluginHookName>(hookName: K, handler: PluginHookHandler<K>, opts?: {
+        priority?: number;
+    }): void;
+    /** Register a CLI extension. */
+    registerCli(registrar: (ctx: {
+        program: CliProgram;
+    }) => void, opts?: {
+        commands?: string[];
+    }): void;
+    /** Register a background service. */
+    registerService(service: OpenClawPluginService): void;
+    /** Register a slash command. */
+    registerCommand(command: OpenClawPluginCommandDefinition): void;
+    /** Resolve a workspace-relative path safely. */
+    resolvePath(input: string): string;
+}
+export interface OpenClawPluginDefinition {
+    /** Unique plugin identifier. */
+    id: string;
+    /** Optional display name. */
+    name?: string;
+    /** Human-readable description. */
+    description?: string;
+    /** Version string. */
+    version?: string;
+    /** Plugin kind — "memory" is an exclusive slot. */
+    kind?: 'memory' | 'context-engine';
+    /** JSON Schema for plugin config (declared statically). */
+    configSchema?: OpenClawPluginConfigSchema;
+    /**
+     * Called once when the plugin is loaded. Register all hooks, tools,
+     * commands, and services here.
+     */
+    register?: (api: OpenClawPluginApi) => void | Promise<void>;
+    /** Optional activation phase (called after all plugins registered). */
+    activate?: (api: OpenClawPluginApi) => void | Promise<void>;
+}
+/** A TSchema-compatible object (from @sinclair/typebox). */
+export type TSchema = Record<string, unknown>;
+export interface AnyAgentTool {
+    name: string;
+    label?: string;
+    description: string;
+    /** TypeBox Type.Object schema for tool parameters. */
+    parameters: TSchema;
+    /** Execute the tool. Returns a string result. */
+    execute(toolCallId: string, params: Record<string, unknown>): Promise<string>;
+}
+/** Tool factory: receives context, returns array of tools. */
+export type ToolFactory = (ctx: OpenClawPluginToolContext) => AnyAgentTool[];
+export interface OpenClawPluginToolContext {
+    config?: OpenClawConfig;
+    workspaceDir?: string;
+    agentDir?: string;
+    agentId?: string;
+    sessionKey?: string;
+    /** Per-conversation ID, regenerated on /new and /reset. */
+    sessionId?: string;
+    messageChannel?: string;
+}
+export type PluginHookName = 'before_model_resolve' | 'before_prompt_build' | 'before_agent_start' | 'llm_input' | 'llm_output' | 'agent_end' | 'before_compaction' | 'after_compaction' | 'before_reset' | 'message_received' | 'message_sending' | 'message_sent' | 'before_tool_call' | 'after_tool_call' | 'tool_result_persist' | 'before_message_write' | 'session_start' | 'session_end' | 'subagent_spawning' | 'subagent_delivery_target' | 'subagent_spawned' | 'subagent_ended' | 'gateway_start' | 'gateway_stop';
+/** Base fields present in every hook event. */
+export interface BaseHookEvent {
+    agentId?: string;
+    sessionId?: string;
+    sessionKey?: string;
+    workspaceDir?: string;
+    timestamp?: string;
+}
+export interface SessionStartEvent extends BaseHookEvent {
+    initialPrompt?: string;
+}
+export interface BeforePromptBuildEvent extends BaseHookEvent {
+    prompt?: string;
+    turnIndex?: number;
+}
+export interface AfterToolCallEvent extends BaseHookEvent {
+    toolName?: string;
+    toolInput?: unknown;
+    toolResult?: unknown;
+    success?: boolean;
+    error?: string;
+}
+export interface BeforeCompactionEvent extends BaseHookEvent {
+    messages?: ConversationMessage[];
+    reason?: string;
+}
+export interface SessionEndEvent extends BaseHookEvent {
+    messages?: ConversationMessage[];
+    reason?: string;
+}
+export interface ConversationMessage {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+}
+export interface PromptBuildResult {
+    prependContext?: string;
+    appendSystemContext?: string;
+}
+export interface SessionStartResult {
+    appendSystemContext?: string;
+}
+export type HookResult = void | PromptBuildResult | SessionStartResult | undefined;
+/** Map hook names to their event types (for hooks we use). */
+export interface HookEventMap {
+    session_start: SessionStartEvent;
+    before_prompt_build: BeforePromptBuildEvent;
+    after_tool_call: AfterToolCallEvent;
+    before_compaction: BeforeCompactionEvent;
+    session_end: SessionEndEvent;
+}
+/** Generic hook handler type. */
+export type PluginHookHandler<K extends PluginHookName> = K extends keyof HookEventMap ? (event: HookEventMap[K]) => HookResult | Promise<HookResult> : (event: BaseHookEvent) => HookResult | Promise<HookResult>;
+export interface OpenClawPluginServiceContext {
+    logger: PluginLogger;
+}
+export interface OpenClawPluginService {
+    id: string;
+    start(ctx: OpenClawPluginServiceContext): Promise<void> | void;
+    stop(ctx: OpenClawPluginServiceContext): Promise<void> | void;
+}
+/**
+ * Context passed to plugin command handlers by the SDK.
+ * Commands are channel-facing (Telegram, Discord, etc.), not agent-facing.
+ */
+export interface PluginCommandContext {
+    senderId?: string;
+    channel: string;
+    channelId?: string;
+    isAuthorizedSender: boolean;
+    /** Raw command arguments after the command name (single string, not array). */
+    args?: string;
+    commandBody: string;
+    config: OpenClawConfig;
+    from?: string;
+    to?: string;
+    accountId?: string;
+    messageThreadId?: number;
+}
+/**
+ * Result returned by a plugin command handler.
+ * Must contain `text` field (not `output`).
+ */
+export interface PluginCommandResult {
+    text: string;
+}
+/**
+ * Handler function for plugin commands.
+ */
+export type PluginCommandHandler = (ctx: PluginCommandContext) => PluginCommandResult | Promise<PluginCommandResult>;
+export interface OpenClawPluginCommandDefinition {
+    name: string;
+    description: string;
+    /** Whether this command accepts arguments. */
+    acceptsArgs?: boolean;
+    /** Whether only authorized senders can use this command (default: true). */
+    requireAuth?: boolean;
+    /** The handler function — SDK checks typeof handler === "function". */
+    handler: PluginCommandHandler;
+}
+export interface CliProgram {
+    command(name: string): CliCommand;
+}
+export interface CliCommand {
+    command(name: string): CliCommand;
+    description(desc: string): CliCommand;
+    argument(name: string, desc?: string): CliCommand;
+    option(flags: string, desc?: string, defaultValue?: unknown): CliCommand;
+    action(fn: (...args: unknown[]) => void | Promise<void>): CliCommand;
+}
+//# sourceMappingURL=openclaw.d.ts.map

package/dist/types/openclaw.d.ts.map

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

package/dist/types/openclaw.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Local type definitions matching the real OpenClaw Plugin SDK.
+ *
+ * These are locally defined since no SDK package is published.
+ * Shapes match openclaw/openclaw:src/plugins/types.ts (verified via Nia research).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=openclaw.js.map

package/dist/types/openclaw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openclaw.js","sourceRoot":"","sources":["../../src/types/openclaw.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/dist/utils/memory-files.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared memory file utilities — used by memory-migrate tool and file-watcher service.
+ *
+ * Provides chunking, marker file I/O, file discovery, and safe file reading.
+ */
+export declare const MARKER_FILE = ".engram-migrated.json";
+export declare const MAX_FILE_SIZE = 50000;
+export interface MigrationMarker {
+    lastMigrated: string;
+    files: Record<string, string>;
+}
+export interface MemoryChunk {
+    title: string;
+    content: string;
+    sourcePath: string;
+    type: string;
+}
+export declare function splitIntoChunks(content: string, sourcePath: string): MemoryChunk[];
+export declare function inferType(_sourcePath: string, content: string): string;
+export declare function loadMarker(path: string): Promise<MigrationMarker | null>;
+export declare function saveMarker(markerPath: string, marker: MigrationMarker): Promise<void>;
+export declare function discoverMemoryFiles(workspaceDir: string): Promise<string[]>;
+export declare function fileExists(path: string): Promise<boolean>;
+export declare function safeReadFile(path: string): Promise<string | null>;
+//# sourceMappingURL=memory-files.d.ts.map

package/dist/utils/memory-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-files.d.ts","sourceRoot":"","sources":["../../src/utils/memory-files.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,aAAa,QAAS,CAAC;AAEpC,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAMD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,EAAE,CA8DlF;AAED,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAMtE;AAMD,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAW9E;AAED,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAW3F;AAMD,wBAAsB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBjF;AA2BD,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQvE"}

package/dist/utils/memory-files.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * Shared memory file utilities — used by memory-migrate tool and file-watcher service.
+ *
+ * Provides chunking, marker file I/O, file discovery, and safe file reading.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_FILE_SIZE = exports.MARKER_FILE = void 0;
+exports.splitIntoChunks = splitIntoChunks;
+exports.inferType = inferType;
+exports.loadMarker = loadMarker;
+exports.saveMarker = saveMarker;
+exports.discoverMemoryFiles = discoverMemoryFiles;
+exports.fileExists = fileExists;
+exports.safeReadFile = safeReadFile;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+exports.MARKER_FILE = '.engram-migrated.json';
+exports.MAX_FILE_SIZE = 50_000; // 50KB limit per file
+// ---------------------------------------------------------------------------
+// Chunking
+// ---------------------------------------------------------------------------
+function splitIntoChunks(content, sourcePath) {
+    const chunks = [];
+    const lines = content.split('\n');
+    // Try splitting by ## headers
+    const sections = [];
+    let currentTitle = '';
+    let currentContent = [];
+    let inFence = false;
+    for (const line of lines) {
+        if (line.startsWith('```')) {
+            inFence = !inFence;
+        }
+        const headerMatch = !inFence ? line.match(/^##\s+(.+)/) : null;
+        if (headerMatch) {
+            if (currentContent.length > 0) {
+                sections.push({
+                    title: currentTitle || sourcePath,
+                    content: currentContent.join('\n').trim(),
+                });
+            }
+            currentTitle = headerMatch[1].trim();
+            currentContent = [];
+        }
+        else {
+            currentContent.push(line);
+        }
+    }
+    // Push last section
+    if (currentContent.length > 0) {
+        sections.push({
+            title: currentTitle || sourcePath,
+            content: currentContent.join('\n').trim(),
+        });
+    }
+    // If no ## headers found, treat whole file as one chunk
+    if (sections.length === 0) {
+        const trimmed = content.trim();
+        if (trimmed) {
+            chunks.push({
+                title: sourcePath,
+                content: trimmed,
+                sourcePath,
+                type: inferType(sourcePath, trimmed),
+            });
+        }
+        return chunks;
+    }
+    // Filter out empty sections and create chunks
+    for (const section of sections) {
+        if (!section.content)
+            continue;
+        chunks.push({
+            title: section.title,
+            content: section.content,
+            sourcePath,
+            type: inferType(sourcePath, section.content),
+        });
+    }
+    return chunks;
+}
+function inferType(_sourcePath, content) {
+    const lower = content.toLowerCase();
+    if (lower.includes('decision') || lower.includes('chose') || lower.includes('decided'))
+        return 'decision';
+    if (lower.includes('bug') || lower.includes('fix') || lower.includes('resolved'))
+        return 'bugfix';
+    if (lower.includes('pattern') || lower.includes('convention'))
+        return 'discovery';
+    return 'change';
+}
+// ---------------------------------------------------------------------------
+// Marker file
+// ---------------------------------------------------------------------------
+async function loadMarker(path) {
+    try {
+        const raw = await (0, promises_1.readFile)(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || typeof parsed.files !== 'object') {
+            return null; // corrupted marker, treat as fresh
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+async function saveMarker(markerPath, marker) {
+    // Atomic write via temp file + rename to reduce race window when
+    // two agents migrate concurrently (last writer wins, no corruption).
+    const tmp = markerPath + '.tmp';
+    try {
+        await (0, promises_1.writeFile)(tmp, JSON.stringify(marker, null, 2), 'utf-8');
+        await (0, promises_1.rename)(tmp, markerPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[engram] failed to save migration marker: ${msg}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// File discovery
+// ---------------------------------------------------------------------------
+async function discoverMemoryFiles(workspaceDir) {
+    const files = [];
+    // Check MEMORY.md
+    const memoryMd = (0, node_path_1.join)(workspaceDir, 'MEMORY.md');
+    if (await fileExists(memoryMd)) {
+        files.push(memoryMd);
+    }
+    // Check memory/ directory recursively
+    const memoryDir = (0, node_path_1.join)(workspaceDir, 'memory');
+    if (await fileExists(memoryDir)) {
+        const mdFiles = await findMdFiles(memoryDir);
+        files.push(...mdFiles);
+    }
+    return files;
+}
+async function findMdFiles(dir, depth = 0) {
+    if (depth > 10)
+        return []; // Guard against excessive nesting
+    const results = [];
+    try {
+        const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue; // Prevent symlink cycles
+            const fullPath = (0, node_path_1.join)(dir, entry.name);
+            if (entry.isDirectory()) {
+                const nested = await findMdFiles(fullPath, depth + 1);
+                results.push(...nested);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                results.push(fullPath);
+            }
+        }
+    }
+    catch {
+        // Directory not readable — skip
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function fileExists(path) {
+    try {
+        await (0, promises_1.stat)(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function safeReadFile(path) {
+    try {
+        const info = await (0, promises_1.stat)(path);
+        if (info.size > exports.MAX_FILE_SIZE)
+            return null;
+        return await (0, promises_1.readFile)(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=memory-files.js.map

package/dist/utils/memory-files.js.map

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

package/openclaw.plugin.json

@@ -0,0 +1,86 @@
+{
+  "name": "engram",
+  "id": "engram",
+  "version": "0.2.0",
+  "displayName": "Engram Memory",
+  "description": "Connects OpenClaw agents to engram persistent memory server for long-term context retention",
+  "kind": "memory",
+  "author": "thebtf",
+  "main": "dist/index.js",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "url": {
+        "type": "string",
+        "description": "Engram server URL (e.g. http://localhost:37777)",
+        "default": "http://localhost:37777"
+      },
+      "token": {
+        "type": "string",
+        "description": "Bearer token for engram API authentication",
+        "uiHints": { "sensitive": true }
+      },
+      "project": {
+        "type": "string",
+        "description": "Project scope override (defaults to auto-detected from workspace)"
+      },
+      "contextLimit": {
+        "type": "number",
+        "description": "Maximum observations to inject per prompt",
+        "default": 10
+      },
+      "sessionContextLimit": {
+        "type": "number",
+        "description": "Maximum observations to inject at session start",
+        "default": 20
+      },
+      "tokenBudget": {
+        "type": "number",
+        "description": "Maximum token budget for context injection (approx 4 chars per token)",
+        "default": 2000
+      },
+      "timeoutMs": {
+        "type": "number",
+        "description": "Per-request timeout in milliseconds",
+        "default": 5000
+      },
+      "autoExtract": {
+        "type": "boolean",
+        "description": "Enable automatic observation extraction on compaction/session-end",
+        "default": true
+      },
+      "logLevel": {
+        "type": "string",
+        "enum": ["debug", "info", "warn", "error"],
+        "description": "Log verbosity level",
+        "default": "warn"
+      }
+    },
+    "required": ["url", "token"]
+  },
+  "hooks": [
+    "session_start",
+    "before_prompt_build",
+    "after_tool_call",
+    "before_compaction",
+    "session_end"
+  ],
+  "tools": [
+    "engram_search",
+    "engram_remember",
+    "engram_decisions",
+    "memory_search",
+    "memory_store",
+    "memory_forget",
+    "memory_get",
+    "memory_migrate"
+  ],
+  "commands": [
+    "memory",
+    "remember",
+    "migrate"
+  ],
+  "cli": {
+    "commands": ["memory"]
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "openclaw-engram",
+  "version": "0.2.0",
+  "description": "OpenClaw plugin that connects to engram persistent memory server",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist/",
+    "openclaw.plugin.json"
+  ],
+  "keywords": [
+    "openclaw",
+    "engram",
+    "memory",
+    "plugin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thebtf/engram.git",
+    "directory": "plugin/openclaw-engram"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0",
+    "chokidar": "^4.0.3",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^18.19.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "dist/index.js"
+    ]
+  }
+}