memory-mimir 1.0.0

package/README.md

@@ -0,0 +1,90 @@
+# memory-mimir
+
+OpenClaw plugin that connects to [Mimir](https://github.com/TripleWhite/Mimir-Go) — a unified long-term memory engine. Gives your OpenClaw agent persistent, searchable memory across sessions.
+
+## How It Works
+
+```
+User message → auto-recall (search Mimir) → inject <memories> → Agent runs → auto-capture (ingest new messages)
+```
+
+**Auto-recall**: Before each agent turn, extracts keywords from the user message (supports English + CJK), searches Mimir with agentic retrieval, and injects the most relevant memories into the LLM context.
+
+**Auto-capture**: After each agent turn, incrementally captures new conversation messages and sends them to Mimir for extraction (episodes, entities, relations, events).
+
+## Features
+
+- Agentic search with query classification and strategy routing
+- CJK (Chinese/Japanese/Korean) keyword extraction
+- Time range extraction from natural language ("last week", "昨天")
+- Score-ordered compact memory formatting (2000 char budget)
+- Incremental capture — no duplicate ingestion across agent turns
+- Two tool definitions: `mimir_search` and `mimir_ingest` for manual use
+
+## Setup
+
+### Prerequisites
+
+A running [Mimir](https://github.com/TripleWhite/Mimir-Go) server.
+
+### Install
+
+```bash
+npm install
+npm run build
+```
+
+### Configure
+
+In your OpenClaw plugin config:
+
+```json
+{
+  "mimirUrl": "http://localhost:8766",
+  "userId": "your-user-id",
+  "groupId": "your-group-id",
+  "autoRecall": true,
+  "autoCapture": true,
+  "maxRecallItems": 8,
+  "maxRecallTokens": 2000
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `mimirUrl` | string | — | Mimir server URL |
+| `userId` | string | — | User ID for memory isolation |
+| `groupId` | string | — | Group ID for memory scoping |
+| `autoRecall` | boolean | `true` | Inject memories before each turn |
+| `autoCapture` | boolean | `true` | Capture conversations after each turn |
+| `maxRecallItems` | number | `8` | Max memory items per recall |
+| `maxRecallTokens` | number | `2000` | Max chars for memory context |
+
+## Architecture
+
+```
+memory-mimir (this plugin)          Mimir-Go (engine)
+┌─────────────────────┐            ┌──────────────────────┐
+│  extractKeywords()  │            │  Agentic Search      │
+│  extractTimeRange() │──search──→ │  ├─ Query Analyzer   │
+│  formatResults()    │←─results── │  ├─ BM25 + Vector    │
+│                     │            │  └─ Graph Traverse   │
+│  auto-capture       │──ingest──→ │  Pipeline            │
+│  (incremental)      │            │  ├─ Narrative Extract │
+│                     │            │  └─ Graph Extract    │
+└─────────────────────┘            └──────────────────────┘
+```
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Build
+npm run build
+```
+
+## License
+
+MIT

package/dist/formatter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Format Mimir search results into compact, agent-friendly text.
+ * Items are rendered in server-computed score order (no grouping by type).
+ * Token budget: ~500 tokens max for auto-recall context.
+ */
+import type { SearchResponse, GraphTraverseResult } from "./mimir-client.js";
+export interface FormatterOptions {
+    /** Max characters for the entire formatted block. ~500 tokens ≈ 2000 chars. */
+    readonly maxChars: number;
+    /** Max individual memory items to show. */
+    readonly maxItems: number;
+}
+/** Format search results as a compact memory context block.
+ *  Items are rendered in score order (as returned by server), not grouped by type.
+ */
+export declare function formatSearchResults(response: SearchResponse, options?: Partial<FormatterOptions>): string;
+/** Format graph traverse results as a relationship summary. */
+export declare function formatGraphResults(result: GraphTraverseResult): string;

package/dist/formatter.js

@@ -0,0 +1,129 @@
+/**
+ * Format Mimir search results into compact, agent-friendly text.
+ * Items are rendered in server-computed score order (no grouping by type).
+ * Token budget: ~500 tokens max for auto-recall context.
+ */
+const DEFAULT_OPTIONS = {
+    maxChars: 2000,
+    maxItems: 8,
+};
+// ─── Main Formatter ──────────────────────────────────────────
+/** Format search results as a compact memory context block.
+ *  Items are rendered in score order (as returned by server), not grouped by type.
+ */
+export function formatSearchResults(response, options) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const { results } = response;
+    if (results.length === 0) {
+        return "";
+    }
+    const lines = [];
+    let charCount = 0;
+    let itemCount = 0;
+    for (const item of results) {
+        if (itemCount >= opts.maxItems)
+            break;
+        const line = formatItem(item);
+        if (!line)
+            continue;
+        // Check char budget before adding (account for newline)
+        if (charCount + line.length + 1 > opts.maxChars)
+            break;
+        lines.push(line);
+        charCount += line.length + 1;
+        itemCount++;
+    }
+    // Append foresight_context if present
+    if (response.foresight_context) {
+        const fLine = `> ${response.foresight_context}`;
+        if (charCount + fLine.length + 1 <= opts.maxChars) {
+            lines.push(fLine);
+        }
+    }
+    return lines.join("\n");
+}
+/** Format graph traverse results as a relationship summary. */
+export function formatGraphResults(result) {
+    if (result.entities.length === 0) {
+        return "";
+    }
+    const lines = ["## Entity Relationships"];
+    // Format entities with their summaries
+    for (const entity of result.entities.slice(0, 5)) {
+        const aliases = entity.aliases?.length ? ` (aka ${entity.aliases.join(", ")})` : "";
+        lines.push(`- **${entity.name}**${aliases}: ${entity.summary || entity.entity_type}`);
+    }
+    // Format relations as "A → relation → B"
+    if (result.relations.length > 0) {
+        lines.push("");
+        const entityById = new Map();
+        for (const e of result.entities) {
+            entityById.set(e.id, e);
+        }
+        for (const rel of result.relations.slice(0, 5)) {
+            const source = entityById.get(rel.source_entity_id)?.name ?? "?";
+            const target = entityById.get(rel.target_entity_id)?.name ?? "?";
+            lines.push(`- ${source} → ${rel.relation_type} → ${target}: ${rel.fact}`);
+        }
+    }
+    return lines.join("\n");
+}
+// ─── Item Dispatcher ─────────────────────────────────────────
+/** Format a single result item with a type-specific prefix. */
+function formatItem(item) {
+    const data = item.data;
+    switch (item.type) {
+        case "episode":
+        case "raw_doc": {
+            const date = formatDate(data.occurred_at);
+            const title = data.title || "";
+            const content = data.content || "";
+            const summary = title || firstLine(content);
+            return `- [${date}] ${truncate(summary, 150)}`;
+        }
+        case "event_log": {
+            const date = formatDate(data.timestamp);
+            const fact = data.fact || "";
+            return `- [${date}] ${truncate(fact, 150)}`;
+        }
+        case "entity": {
+            const name = data.name || "";
+            const entityType = data.entity_type || "";
+            const summary = data.summary || "";
+            return `- [entity] ${name} (${entityType}): ${truncate(summary, 150)}`;
+        }
+        case "relation": {
+            const fact = data.fact || "";
+            const relType = data.relation_type || "";
+            return `- [relation] ${relType}: ${truncate(fact, 150)}`;
+        }
+        case "foresight": {
+            const content = data.content || "";
+            return `- [upcoming] ${truncate(content, 150)}`;
+        }
+        default:
+            return "";
+    }
+}
+// ─── Helpers ─────────────────────────────────────────────────
+function formatDate(isoDate) {
+    if (!isoDate)
+        return "unknown";
+    try {
+        const d = new Date(isoDate);
+        return d.toISOString().slice(0, 10); // "2023-07-15"
+    }
+    catch {
+        return "unknown";
+    }
+}
+function truncate(s, maxLen) {
+    if (s.length <= maxLen)
+        return s;
+    return s.slice(0, maxLen - 3) + "...";
+}
+function firstLine(s) {
+    const idx = s.indexOf("\n");
+    return idx >= 0 ? s.slice(0, idx) : s;
+}
+//# sourceMappingURL=formatter.js.map

package/dist/formatter.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * memory-mimir: OpenClaw plugin entry point.
+ *
+ * Replaces OpenClaw's built-in file-backed memory with Mimir
+ * as a full long-term memory backend (graph + vector + BM25).
+ */
+interface OpenClawPluginApi {
+    pluginConfig: Record<string, unknown>;
+    logger: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+    resolvePath: (path: string) => string;
+    on: (event: string, handler: (event: Record<string, unknown>) => Promise<Record<string, unknown> | void>) => void;
+    registerTool: (definition: Record<string, unknown>, options: {
+        name: string;
+    }) => void;
+    registerCli: (factory: (ctx: {
+        program: CommanderProgram;
+    }) => void, options: {
+        commands: string[];
+    }) => void;
+    registerService: (definition: {
+        id: string;
+        start: () => void;
+        stop: () => void;
+    }) => void;
+}
+interface CommanderProgram {
+    command: (name: string) => CommanderCommand;
+}
+interface CommanderCommand {
+    description: (desc: string) => CommanderCommand;
+    argument: (name: string, desc: string) => CommanderCommand;
+    option: (flags: string, desc: string, defaultVal?: string) => CommanderCommand;
+    action: (fn: (...args: unknown[]) => Promise<void>) => CommanderCommand;
+    command: (name: string) => CommanderCommand;
+}
+/**
+ * Extract plain text from a message content block (string or array).
+ * Handles mixed content: text, tool_use, tool_result, image, document.
+ * - text blocks: included as-is
+ * - tool_use: "[工具: name(args)]" so we know what was invoked
+ * - tool_result: recursively extract text (web fetch results, file reads, etc.)
+ * - image: "[图片]" placeholder — OpenClaw's reply will describe it
+ * - document: "[文档]" placeholder
+ */
+export declare function extractMessageText(content: unknown): string;
+/** Extract searchable topics from user message — pure heuristic, no LLM.
+ *  For CJK text: pass first 200 chars directly (server has LLMTranslator + RuleAnalyzer).
+ *  For English: extract up to 8 non-stop-word tokens.
+ */
+export declare function extractKeywords(message: string): string;
+interface TimeRangeResult {
+    readonly start: string;
+    readonly end: string;
+}
+/** Extract time range from user message using keyword matching.
+ *  Returns undefined if no temporal reference is found.
+ */
+export declare function extractTimeRange(message: string): TimeRangeResult | undefined;
+declare const memoryMimirPlugin: {
+    id: string;
+    name: string;
+    description: string;
+    kind: "memory";
+    configSchema: {
+        type: string;
+        additionalProperties: boolean;
+        properties: {
+            mimirUrl: {
+                type: string;
+                description: string;
+            };
+            userId: {
+                type: string;
+                description: string;
+            };
+            groupId: {
+                type: string;
+                description: string;
+            };
+            autoRecall: {
+                type: string;
+                description: string;
+            };
+            autoCapture: {
+                type: string;
+                description: string;
+            };
+            maxRecallItems: {
+                type: string;
+                description: string;
+            };
+            maxRecallTokens: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+    register(api: OpenClawPluginApi): void;
+};
+export default memoryMimirPlugin;