@bsbofmusic/memos-memu-local-memory-tools-for-agent 1.0.0

package/README.md

@@ -0,0 +1,187 @@
+# memos-memu-local-memory-tools-for-agent
+
+**One-shot install + query tools for a local memos + memuK memory system, powered by MCP (Model Context Protocol).**
+
+Designed for [OpenClaw](https://openclaw.ai) agents that need persistent, queryable memory beyond Markdown files — a three-layer stack:
+
+| Layer | Store | What it's for |
+|-------|-------|--------------|
+| File brain | `MEMORY.md` / `memory/*.md` | Stable facts, rules, decisions |
+| memos | PostgreSQL (Docker) | Original quotes, timing, commitments |
+| memuK | SQLite | Topic summaries, cross-session recall |
+
+---
+
+## Quick start
+
+### 1. Add to MCPorter config (`~/.openclaw/mcporter.json`)
+
+```json
+{
+  "servers": {
+    "memos-memu-local-memory-tools-for-agent": {
+      "command": "npx",
+      "args": ["-y", "@bsbofmusic/memos-memu-local-memory-tools-for-agent"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+### 2. Tell your agent
+
+> "Install the memory system using `install_memory_system` tool."
+
+The agent will call `install_memory_system` — and the MCP server will set up everything automatically.
+
+### 3. Verify
+
+```bash
+npx @bsbofmusic/memos-memu-local-memory-tools-for-agent
+# then ask your agent to call verify_memory_system
+```
+
+---
+
+## Tools
+
+### `install_memory_system`
+One-shot install of the full memory system. Safe to re-run — detects existing components and skips them.
+
+What it sets up:
+- **Docker `memos-postgres` container** (PostgreSQL 15 alpine + memos schema)
+- **memuK SQLite database** (`~/.openclaw/memu.db`) with three tables
+- **`memory-triple-recall` SKILL** for OpenClaw agents
+- **Sync cron** (`*/15 * * * *`) that syncs memos → memuK every 15 minutes
+- **MCPorter MCP entry** (merged into your existing `mcporter.json`)
+
+### `verify_memory_system`
+Smoke-test all installed components. Returns PASS/FAIL for each:
+- Docker availability
+- memos-postgres container status
+- memos PostgreSQL queryability
+- memuK SQLite accessibility
+- memory-triple-recall SKILL presence
+- MCPorter MCP config entry
+- Sync cron installation
+
+### `memos_query`
+Search memos PostgreSQL by keyword.
+
+```
+query: string   // required — case-insensitive keywords
+limit?: number  // default 10, max 20
+```
+
+### `memuk_search`
+Search memuK SQLite memory summaries.
+
+```
+query: string   // required — topic / keywords
+limit?: number  // default 5, max 10
+```
+
+---
+
+## Requirements
+
+| Dependency | Version | Notes |
+|------------|---------|-------|
+| Node.js | ≥ 18 | Built-in on most systems |
+| Docker | any | Required for memos PostgreSQL |
+| sqlite3 CLI | any | For memuK access |
+
+### Docker setup (if not already installed)
+
+```bash
+# Linux
+curl -fsSL https://get.docker.com | sh
+
+# macOS
+brew install --cask docker
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  OpenClaw Agent                                          │
+│  (K / any OpenClaw agent)                               │
+└────────────────┬────────────────────────────────────────┘
+                 │ MCP stdio
+                 ▼
+┌─────────────────────────────────────────────────────────┐
+│  MCP Server                                             │
+│  memos-memu-local-memory-tools-for-agent                │
+│  (this package)                                         │
+│                                                          │
+│  ┌──────────────┐  ┌──────────────┐                   │
+│  │ install_*    │  │ memos_query  │                   │
+│  │ verify_*     │  │ memuk_search │                   │
+│  └──────────────┘  └──────────────┘                   │
+└────────┬─────────────────┬──────────────────────────────┘
+         │ docker exec     │ sqlite3 CLI
+         ▼                 ▼
+┌─────────────────┐  ┌─────────────────┐
+│ memos-postgres  │  │ ~/.openclaw/    │
+│ (Docker PG)     │  │ memu.db        │
+│                 │  │ (SQLite)       │
+│  memo table     │  │                │
+│  raw history    │  │ memu_memory_   │
+│                 │  │   items        │
+└─────────────────┘  └─────────────────┘
+```
+
+---
+
+## Sync mechanism
+
+Every 15 minutes, a cron job runs `sync_memos_to_memuk.py` which:
+
+1. Reads the last synced `memo.id` from `memu_sync_checkpoint`
+2. Fetches all newer memos from PostgreSQL
+3. Inserts summaries into `memu_memory_items`
+4. Updates the checkpoint
+
+This keeps memuK as a lightweight, queryable cache of memos history without touching the DB on every recall.
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEMOS_CONTAINER` | `memos-postgres` | Docker container name |
+| `MEMOS_DB` | `memos` | PostgreSQL database name |
+| `MEMOS_USER` | `memos` | PostgreSQL username |
+| `MEMOS_PASSWORD` | `memos_local_20260312` | PostgreSQL password |
+| `MEMUK_PATH` | `~/.openclaw/memu.db` | memuK SQLite file path |
+| `OPENCLAW_STATE_DIR` | `~/.openclaw` | OpenClaw state directory |
+
+---
+
+## Uninstall / reset
+
+```bash
+# Remove Docker containers
+docker stop memos-postgres && docker rm memos-postgres
+
+# Remove memuK SQLite
+rm ~/.openclaw/memu.db
+
+# Remove SKILL
+rm -rf ~/.openclaw/workspace/skills/memory-triple-recall
+
+# Remove cron
+sudo rm /etc/cron.d/memuk-sync || crontab -e  # delete memuk-sync line
+
+# Remove MCPorter entry (edit mcporter.json and delete the server entry)
+```
+
+---
+
+## License
+
+MIT — use freely, modify freely.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@bsbofmusic/memos-memu-local-memory-tools-for-agent",
+  "version": "1.0.0",
+  "description": "MCP server — one-shot install + query for memos (PostgreSQL) and memuK (SQLite) local memory. Designed for OpenClaw agents.",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "memos-memu-local-memory-tools-for-agent": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node src/tools/verify.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "openclaw",
+    "memos",
+    "memory",
+    "local-memory",
+    "sqlite",
+    "postgresql"
+  ],
+  "author": "K / bsbofmusic",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/index.js

@@ -0,0 +1,138 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { install_memory_system } from './tools/install.js';
+import { memos_query } from './tools/memos.js';
+import { memuk_search } from './tools/memuk.js';
+import { verify_memory_system } from './tools/verify.js';
+
+const SERVER_NAME = 'memos-memu-local-memory-tools-for-agent';
+const SERVER_VERSION = '1.0.0';
+
+export const tools = [
+  {
+    name: 'install_memory_system',
+    description:
+      'One-shot install of the full memos + memuK local memory system. ' +
+      'Sets up: Docker memos-postgres container, PostgreSQL DB, memuK SQLite schema, ' +
+      'memory-triple-recall SKILL, sync cron, and mcporter MCP config. ' +
+      'Safe to re-run — detects existing components and skips what\'s already there. ' +
+      'Returns a step-by-step status report.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'verify_memory_system',
+    description:
+      'Smoke-test the installed memory system. Checks: memos PostgreSQL connectivity, ' +
+      'memuK SQLite connectivity, cron sync status, and mcporter config presence. ' +
+      'Returns PASS/FAIL for each component plus a summary.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'memos_query',
+    description:
+      'Query the memos PostgreSQL database for raw conversation history, original wording, ' +
+      'and past context. Use for: original quotes, exact wording, timing of events, commitments. ' +
+      'Returns formatted memo entries with content and metadata.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Keywords to search in memo content (case-insensitive)',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results to return (default 10, max 20)',
+          default: 10,
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'memuk_search',
+    description:
+      'Search the memuK SQLite memory store for topic summaries and cross-session recall. ' +
+      'Use for: "did we talk about X", topic-level memory lookups. ' +
+      'Returns memory summaries with type and timestamp.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Topic / keywords to search in memory summaries',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results to return (default 5, max 10)',
+          default: 5,
+        },
+      },
+      required: ['query'],
+    },
+  },
+];
+
+const server = new Server(
+  { name: SERVER_NAME, version: SERVER_VERSION },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'install_memory_system':
+        return await install_memory_system(args);
+      case 'verify_memory_system':
+        return await verify_memory_system(args);
+      case 'memos_query':
+        return await memos_query(args);
+      case 'memuk_search':
+        return await memuk_search(args);
+      default:
+        return {
+          content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `❌ Tool error [${name}]: ${err.message}\n\n${err.stack}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error('Server fatal error:', err);
+  process.exit(1);
+});
+
+export default server;

package/src/shared/db.js

@@ -0,0 +1,114 @@
+import { execSync, exec } from 'child_process';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export function detectEnv() {
+  const home = os.homedir();
+  const openclawState =
+    process.env.OPENCLAW_STATE_DIR ||
+    path.join(home, '.openclaw');
+
+  return {
+    memosContainer: process.env.MEMOS_CONTAINER || 'memos-postgres',
+    memosDb: process.env.MEMOS_DB || 'memos',
+    memosUser: process.env.MEMOS_USER || 'memos',
+    memosPassword: process.env.MEMOS_PASSWORD || 'memos_local_20260312',
+    memukPath: process.env.MEMUK_PATH || path.join(openclawState, 'memu.db'),
+    workspaceDir: openclawState,
+    skillDir: path.join(openclawState, 'workspace', 'skills'),
+  };
+}
+
+export function psql(sql, container) {
+  const env = detectEnv();
+  const c = container || env.memosContainer;
+  const safeSql = sql.replace(/"/g, '\\"');
+  try {
+    const out = execSync(
+      `docker exec ${c} psql -U ${env.memosUser} -d ${env.memosDb} -t -A -c "${safeSql}"`,
+      { timeout: 15000, maxBuffer: 512 * 1024 }
+    ).toString();
+    return out;
+  } catch (err) {
+    throw new Error(`psql failed: ${err.message}`);
+  }
+}
+
+export function sqlite(sql, dbPath) {
+  const env = detectEnv();
+  const db = dbPath || env.memukPath;
+  const safeSql = sql.replace(/"/g, '""');
+  try {
+    const out = execSync(
+      `/usr/bin/sqlite3 "${db}" "${safeSql}"`,
+      { timeout: 10000 }
+    ).toString();
+    return out;
+  } catch (err) {
+    throw new Error(`sqlite3 failed: ${err.message}`);
+  }
+}
+
+export function sh(cmd, opts = {}) {
+  return new Promise((resolve, reject) => {
+    exec(cmd, { timeout: opts.timeout || 300000 }, (err, stdout, stderr) => {
+      if (err) reject(new Error(`${cmd}\n→ ${err.message}`));
+      else resolve(stdout.toString());
+    });
+  });
+}
+
+export function shSync(cmd, opts = {}) {
+  try {
+    return execSync(cmd, { timeout: opts.timeout || 300000, ...opts }).toString();
+  } catch (err) {
+    throw new Error(`shSync failed: ${err.message}`);
+  }
+}
+
+export function dockerAvailable() {
+  try {
+    execSync('docker info', { timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function dockerContainerRunning(name) {
+  try {
+    const out = execSync(
+      `docker inspect -f '{{.State.Running}}' ${name} 2>/dev/null`,
+      { timeout: 5000 }
+    ).toString().trim();
+    return out === 'true';
+  } catch {
+    return false;
+  }
+}
+
+export function parseSqlite(output) {
+  const lines = output.split('\n').filter(l => l.trim() && !l.startsWith('--'));
+  return lines.map(line => {
+    const pipe = line.split('|');
+    return {
+      id: pipe[0]?.trim() ?? '',
+      summary: pipe[1]?.trim() ?? '',
+      memory_type: pipe[2]?.trim() ?? '',
+      happened_at: pipe[3]?.trim() ?? '',
+    };
+  });
+}
+
+export function parsePsqlJson(output) {
+  try {
+    const rows = JSON.parse(output.trim());
+    return Array.isArray(rows) ? rows : [];
+  } catch {
+    return [];
+  }
+}

package/src/shared/install-steps.js

@@ -0,0 +1,37 @@
+export const STEPS = [
+  {
+    id: 'docker',
+    name: 'Docker availability',
+    description: 'Checks if Docker is installed and running.',
+  },
+  {
+    id: 'memos-container',
+    name: 'memos-postgres Docker container',
+    description: 'Creates or starts the PostgreSQL + memos Docker container.',
+  },
+  {
+    id: 'memos-db',
+    name: 'memos PostgreSQL schema',
+    description: 'Verifies the memo table is accessible.',
+  },
+  {
+    id: 'memuk-db',
+    name: 'memuK SQLite database',
+    description: 'Creates the memuK SQLite schema with three tables.',
+  },
+  {
+    id: 'skill',
+    name: 'memory-triple-recall SKILL',
+    description: 'Installs the SKILL.md into the OpenClaw workspace skills directory.',
+  },
+  {
+    id: 'cron',
+    name: 'Sync cron job',
+    description: 'Installs a */15 cron that syncs memos → memuK.',
+  },
+  {
+    id: 'mcporter-config',
+    name: 'MCPorter MCP server entry',
+    description: 'Merges the MCP server config into ~/.openclaw/mcporter.json.',
+  },
+];

package/src/tools/install.js

@@ -0,0 +1,303 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import {
+  detectEnv,
+  sh,
+  shSync,
+  dockerAvailable,
+  dockerContainerRunning,
+  psql,
+  sqlite,
+} from '../shared/db.js';
+
+const indent = s => s.split('\n').map(l => `  ${l}`).join('\n');
+
+class InstallReport {
+  constructor() {
+    this.steps = [];
+    this.summary = { passed: 0, skipped: 0, failed: 0 };
+  }
+  ok(name, detail = '') {
+    this.steps.push({ status: '✅', name, detail });
+    this.summary.passed++;
+  }
+  skip(name, reason) {
+    this.steps.push({ status: '⏭️', name, detail: reason });
+    this.summary.skipped++;
+  }
+  fail(name, reason) {
+    this.steps.push({ status: '❌', name, detail: reason });
+    this.summary.failed++;
+  }
+  toText() {
+    const lines = this.steps.map(
+      s => `${s.status} ${s.name}${s.detail ? '\n' + indent(s.detail) : ''}`
+    );
+    const t = this.summary.passed + this.summary.skipped + this.summary.failed;
+    lines.push(`\n─── ${this.summary.passed}/${t} passed · ${this.summary.skipped} skipped · ${this.summary.failed} failed ───`);
+    return lines.join('\n');
+  }
+}
+
+export async function install_memory_system() {
+  const env = detectEnv();
+  const report = new InstallReport();
+
+  // ── Docker ────────────────────────────────────────────────────────────────
+  if (!dockerAvailable()) {
+    report.fail('Docker', 'Docker is not installed or not running. Install: https://docs.docker.com/get-docker/');
+    return { content: [{ type: 'text', text: report.toText() }] };
+  }
+  report.ok('Docker', 'Docker is available');
+
+  // ── Container ────────────────────────────────────────────────────────────
+  if (dockerContainerRunning(env.memosContainer)) {
+    report.skip('memos-postgres container', 'Already running — skipping');
+  } else {
+    const containerExists = (() => {
+      try {
+        shSync(`docker inspect ${env.memosContainer}`, { timeout: 5000 });
+        return true;
+      } catch { return false; }
+    })();
+
+    if (containerExists) {
+      try {
+        shSync(`docker start ${env.memosContainer}`, { timeout: 15000 });
+        report.ok('memos-postgres container', 'Started existing stopped container');
+      } catch (err) {
+        report.fail('memos-postgres container', `docker start failed: ${err.message}`);
+        return { content: [{ type: 'text', text: report.toText() }] };
+      }
+    } else {
+      try {
+        // Pull and start postgres alpine
+        shSync(
+          `docker run -d --name ${env.memosContainer} ` +
+          `-e POSTGRES_USER=${env.memosUser} ` +
+          `-e POSTGRES_PASSWORD=${env.memosPassword} ` +
+          `-e POSTGRES_DB=${env.memosDb} ` +
+          `-v memos-pgdata:/var/lib/postgresql/data ` +
+          `postgres:15-alpine`,
+          { timeout: 60000 }
+        );
+        report.ok('memos-postgres container', 'Created and started postgres:15-alpine');
+      } catch (err) {
+        report.fail('memos-postgres container', `docker run failed: ${err.message}`);
+        return { content: [{ type: 'text', text: report.toText() }] };
+      }
+    }
+  }
+
+  // Wait for postgres to be ready (up to 30s)
+  let pgReady = false;
+  for (let i = 0; i < 20; i++) {
+    await new Promise(r => setTimeout(r, 1500));
+    try {
+      shSync(`docker exec ${env.memosContainer} pg_isready -U ${env.memosUser}`, { timeout: 3000 });
+      pgReady = true;
+      break;
+    } catch {}
+  }
+  if (!pgReady) {
+    report.fail('memos-postgres', 'PostgreSQL did not become ready in 30s');
+    return { content: [{ type: 'text', text: report.toText() }] };
+  }
+  report.ok('memos-postgres', 'PostgreSQL is ready');
+
+  // ── memos DB ─────────────────────────────────────────────────────────────
+  try {
+    const testQ = psql('SELECT 1 AS ok;');
+    if (testQ.includes('1')) {
+      report.ok('memos PostgreSQL', 'Database is accessible');
+    } else {
+      throw new Error('Unexpected query result');
+    }
+  } catch (err) {
+    report.fail('memos PostgreSQL', err.message);
+    return { content: [{ type: 'text', text: report.toText() }] };
+  }
+
+  // ── memuK SQLite ─────────────────────────────────────────────────────────
+  const memukDir = path.dirname(env.memukPath);
+  if (!fs.existsSync(memukDir)) {
+    fs.mkdirSync(memukDir, { recursive: true });
+  }
+
+  const schema = `
+CREATE TABLE IF NOT EXISTS memu_memory_items (
+  id TEXT PRIMARY KEY,
+  summary TEXT NOT NULL,
+  memory_type TEXT DEFAULT 'imported',
+  happened_at TEXT,
+  user_id TEXT DEFAULT 'default',
+  created_at TEXT DEFAULT (datetime('now', 'localtime'))
+);
+CREATE TABLE IF NOT EXISTS memu_sync_checkpoint (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  updated_at TEXT DEFAULT (datetime('now', 'localtime'))
+);
+CREATE TABLE IF NOT EXISTS memu_raw_memos (
+  id INTEGER PRIMARY KEY,
+  content TEXT NOT NULL,
+  raw_json TEXT,
+  created_ts INTEGER,
+  synced_at TEXT DEFAULT (datetime('now', 'localtime'))
+);
+`.trim();
+
+  try {
+    if (fs.existsSync(env.memukPath)) {
+      const fd = fs.openSync(env.memukPath, 'a');
+      fs.writeSync(fd, '\n' + schema + '\n');
+      fs.closeSync(fd);
+    } else {
+      fs.writeFileSync(env.memukPath, schema + '\n');
+    }
+    const testCount = sqlite('SELECT COUNT(*) FROM memu_memory_items;', env.memukPath).trim();
+    report.ok('memuK SQLite', `Schema initialized · ${testCount} memory_items`);
+  } catch (err) {
+    report.fail('memuK SQLite', err.message);
+    return { content: [{ type: 'text', text: report.toText() }] };
+  }
+
+  // ── SKILL ────────────────────────────────────────────────────────────────
+  const skillDir = path.join(env.skillDir, 'memory-triple-recall');
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  const today = new Date().toISOString().split('T')[0];
+
+  const skillContent = `---
+name: memory-triple-recall
+description: |
+  Three-layer memory recall stack: MEMORY.md → memos (PostgreSQL) → memuK (SQLite).
+  Use for: original quotes, timing, commitments, topic recall, historical context.
+triggers: 回忆|回想|记得|原话|哪天|什么时候|答应过|之前|历史|进展
+version: 1.0.0
+updated: ${today}
+---
+
+# Memory Triple Recall
+
+## Architecture
+| Layer | Store | Access |
+|-------|-------|--------|
+| File brain | MEMORY.md / memory/*.md | File system |
+| memos | PostgreSQL Docker | memos_query MCP tool |
+| memuK | SQLite | memuk_search MCP tool |
+
+## Fast path
+Do NOT trigger layered recall for atomic facts in USER.md / IDENTITY.md / injected context.
+
+## NEVER fast-path (always do Layer 1+2)
+- 喜欢、最爱、最喜欢的X
+- 女友、crush、个人偏好、私人事实
+
+## Default order
+1. File brain: stable facts, rules, decisions
+2. memos: original wording, timing, commitments (memos_query)
+3. memuK: fuzzy topic recall (memuk_search)
+
+## Output shape
+- 已确认事实
+- 原话·证据
+- 仍不确定点
+
+## Zero-evidence fallback
+已确认事实 → [空]
+原话·证据 → [空]
+仍不确定点 → 此话题在三层记忆中均无记录。
+`;
+
+  try {
+    fs.mkdirSync(skillDir, { recursive: true });
+    if (!fs.existsSync(skillFile)) {
+      fs.writeFileSync(skillFile, skillContent);
+      report.ok('memory-triple-recall SKILL', `Installed → ${skillFile}`);
+    } else {
+      report.skip('memory-triple-recall SKILL', 'Already exists — not overwriting');
+    }
+  } catch (err) {
+    report.fail('memory-triple-recall SKILL', err.message);
+  }
+
+  // ── Cron ─────────────────────────────────────────────────────────────────
+  const cronContent = `\
+# memos → memuK sync every 15 minutes
+*/15 * * * * root /var/lib/openclaw/.openclaw/workspace/scripts/sync_memos_to_memuk.py >> /var/lib/openclaw/.openclaw/workspace/logs/memuk-sync.log 2>&1
+`.trim();
+
+  const cronPath = '/etc/cron.d/memuk-sync';
+  try {
+    fs.mkdirSync(path.dirname(cronPath), { recursive: true });
+    fs.writeFileSync(cronPath, cronContent + '\n', { mode: 0o644 });
+    report.ok('Sync cron', `Installed → ${cronPath}`);
+  } catch {
+    try {
+      await sh(
+        `(crontab -l 2>/dev/null | grep -v "memuk-sync"; echo "*/15 * * * * /var/lib/openclaw/.openclaw/workspace/scripts/sync_memos_to_memuk.py >> /var/lib/openclaw/.openclaw/workspace/logs/memuk-sync.log 2>&1") | crontab -`,
+        { timeout: 5000 }
+      );
+      report.ok('Sync cron', 'Installed via user crontab');
+    } catch (err) {
+      report.fail('Sync cron', err.message);
+    }
+  }
+
+  // ── MCPorter config ────────────────────────────────────────────────────────
+  const pkgName = 'memos-memu-local-memory-tools-for-agent';
+  const mcporterConfigPath = path.join(env.workspaceDir, 'mcporter.json');
+  let existingConfig = {};
+  if (fs.existsSync(mcporterConfigPath)) {
+    try {
+      existingConfig = JSON.parse(fs.readFileSync(mcporterConfigPath, 'utf8'));
+    } catch {}
+  }
+
+  const newEntry = {
+    args: ['-y', `@bsbofmusic/${pkgName}`],
+    command: 'npx',
+    type: 'stdio',
+  };
+
+  const merged = {
+    ...existingConfig,
+    servers: {
+      ...(existingConfig.servers || {}),
+      [pkgName]: newEntry,
+    },
+  };
+
+  try {
+    fs.mkdirSync(path.dirname(mcporterConfigPath), { recursive: true });
+    fs.writeFileSync(mcporterConfigPath, JSON.stringify(merged, null, 2) + '\n');
+    report.ok('MCPorter MCP config', `Updated ${mcporterConfigPath}`);
+  } catch (err) {
+    report.fail('MCPorter MCP config', err.message);
+  }
+
+  // ── Final check ───────────────────────────────────────────────────────────
+  try {
+    psql('SELECT 1;');
+    report.ok('Final memos check', 'Responds OK');
+  } catch (err) {
+    report.fail('Final memos check', err.message);
+  }
+
+  try {
+    sqlite('SELECT 1;', env.memukPath);
+    report.ok('Final memuK check', 'Responds OK');
+  } catch (err) {
+    report.fail('Final memuK check', err.message);
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `🛠️  memory-system install complete\n\n${report.toText()}`,
+      },
+    ],
+  };
+}

package/src/tools/memos.js

@@ -0,0 +1,61 @@
+import { detectEnv, psql, parsePsqlJson } from '../shared/db.js';
+
+export async function memos_query({ query, limit = 10 }) {
+  if (!query || typeof query !== 'string') {
+    return {
+      content: [{ type: 'text', text: '❌ memos_query requires a non-empty "query" string.' }],
+      isError: true,
+    };
+  }
+
+  const safe = s => s.replace(/'/g, "''");
+  const lim = Math.min(parseInt(limit) || 10, 20);
+
+  const sql = `
+SELECT jsonb_agg(q ORDER BY created_ts DESC)
+FROM (
+  SELECT
+    id,
+    substr(content, 1, 500) AS content,
+    created_ts,
+    visibility
+  FROM memo
+  WHERE content ILIKE '%${safe(query)}%'
+  ORDER BY created_ts DESC
+  LIMIT ${lim}
+) q;`.trim();
+
+  let raw;
+  try {
+    raw = psql(sql);
+  } catch (err) {
+    return {
+      content: [{
+        type: 'text',
+        text: `❌ memos PostgreSQL query failed: ${err.message}\n\nIs the memos-postgres container running?`,
+      }],
+    };
+  }
+
+  const rows = parsePsqlJson(raw);
+
+  if (!rows.length) {
+    return {
+      content: [{ type: 'text', text: `✅ memos query "${query}" returned 0 results.` }],
+    };
+  }
+
+  const lines = rows.map((r, i) => {
+    const ts = new Date(Number(r.created_ts)).toLocaleString('zh-CN', {
+      timeZone: 'Asia/Shanghai',
+    });
+    return `─── ${i + 1}. [id:${r.id}] ${ts} (${r.visibility}) ───\n${r.content}`;
+  });
+
+  return {
+    content: [{
+      type: 'text',
+      text: `📋 memos results for "${query}" (${rows.length}):\n\n${lines.join('\n\n')}`,
+    }],
+  };
+}

package/src/tools/memuk.js

@@ -0,0 +1,55 @@
+import { detectEnv, sqlite, parseSqlite } from '../shared/db.js';
+
+export async function memuk_search({ query, limit = 5 }) {
+  if (!query || typeof query !== 'string') {
+    return {
+      content: [{ type: 'text', text: '❌ memuk_search requires a non-empty "query" string.' }],
+      isError: true,
+    };
+  }
+
+  const safe = s => s.replace(/'/g, "''");
+  const lim = Math.min(parseInt(limit) || 5, 10);
+  const env = detectEnv();
+
+  const sql = `
+SELECT
+  id,
+  substr(summary, 1, 300) AS summary,
+  memory_type,
+  happened_at
+FROM memu_memory_items
+WHERE summary LIKE '%${safe(query)}%' OR memory_type LIKE '%${safe(query)}%'
+ORDER BY happened_at DESC
+LIMIT ${lim};`.trim();
+
+  let rows;
+  try {
+    const out = sqlite(sql, env.memukPath);
+    rows = parseSqlite(out);
+  } catch (err) {
+    return {
+      content: [{
+        type: 'text',
+        text: `❌ memuK SQLite search failed: ${err.message}\n\nIs ${env.memukPath} accessible?`,
+      }],
+    };
+  }
+
+  if (!rows.length) {
+    return {
+      content: [{ type: 'text', text: `✅ memuK search "${query}" returned 0 results.` }],
+    };
+  }
+
+  const lines = rows.map(
+    (r, i) => `─── ${i + 1}. [${r.memory_type}] ${r.happened_at || 'n/a'} ───\n${r.summary}`
+  );
+
+  return {
+    content: [{
+      type: 'text',
+      text: `🧠 memuK results for "${query}" (${rows.length}):\n\n${lines.join('\n\n')}`,
+    }],
+  };
+}

package/src/tools/verify.js

@@ -0,0 +1,133 @@
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import {
+  detectEnv,
+  psql,
+  sqlite,
+  dockerAvailable,
+  dockerContainerRunning,
+} from '../shared/db.js';
+
+export async function verify_memory_system() {
+  const env = detectEnv();
+  const results = [];
+
+  const check = (component, fn) => {
+    try {
+      const result = fn();
+      results.push(result);
+    } catch (err) {
+      results.push({ component, status: 'FAIL', detail: err.message });
+    }
+  };
+
+  // 1. Docker
+  check('Docker', () => ({
+    component: 'Docker',
+    status: dockerAvailable() ? 'PASS' : 'FAIL',
+    detail: dockerAvailable() ? 'Docker is available' : 'Docker is not available',
+  }));
+
+  // 2. Container
+  check('memos-postgres container', () => {
+    const running = dockerContainerRunning(env.memosContainer);
+    return {
+      component: 'memos-postgres container',
+      status: running ? 'PASS' : 'FAIL',
+      detail: running ? `Container "${env.memosContainer}" is running` : `Container "${env.memosContainer}" is not running`,
+    };
+  });
+
+  // 3. memos PostgreSQL
+  check('memos PostgreSQL', () => {
+    const out = psql('SELECT COUNT(*) FROM memo;').trim();
+    return { component: 'memos PostgreSQL', status: 'PASS', detail: `${out} memos in DB` };
+  });
+
+  // 4. memuK SQLite
+  check('memuK SQLite', () => {
+    if (!fs.existsSync(env.memukPath)) {
+      return { component: 'memuK SQLite', status: 'FAIL', detail: `DB not found at ${env.memukPath}` };
+    }
+    try {
+      const count = sqlite('SELECT COUNT(*) FROM memu_memory_items;', env.memukPath).trim();
+      let checkpoint = 'unset';
+      try {
+        checkpoint = sqlite("SELECT value FROM memu_sync_checkpoint WHERE key='last_memo_id';", env.memukPath).trim() || 'unset';
+      } catch { /* checkpoint table may not exist yet */ }
+      return {
+        component: 'memuK SQLite',
+        status: 'PASS',
+        detail: `${count} memory items · checkpoint: ${checkpoint}`,
+      };
+    } catch (err) {
+      return { component: 'memuK SQLite', status: 'FAIL', detail: err.message };
+    }
+  });
+
+  // 5. SKILL
+  check('memory-triple-recall SKILL', () => {
+    const skillFile = path.join(env.skillDir, 'memory-triple-recall', 'SKILL.md');
+    return {
+      component: 'memory-triple-recall SKILL',
+      status: fs.existsSync(skillFile) ? 'PASS' : 'FAIL',
+      detail: fs.existsSync(skillFile) ? skillFile : `SKILL.md not found at ${skillFile}`,
+    };
+  });
+
+  // 6. MCPorter config
+  check('MCPorter config', () => {
+    const cfgPath = path.join(env.workspaceDir, 'mcporter.json');
+    if (!fs.existsSync(cfgPath)) {
+      return { component: 'MCPorter config', status: 'FAIL', detail: `${cfgPath} not found` };
+    }
+    try {
+      const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+      const hasEntry = cfg?.servers?.['memos-memu-local-memory-tools-for-agent'];
+      return {
+        component: 'MCPorter config',
+        status: hasEntry ? 'PASS' : 'FAIL',
+        detail: hasEntry ? 'MCP server entry found' : 'MCP server entry missing',
+      };
+    } catch (err) {
+      return { component: 'MCPorter config', status: 'FAIL', detail: `JSON parse error: ${err.message}` };
+    }
+  });
+
+  // 7. Cron
+  check('Sync cron', () => {
+    try {
+      const out = execSync(
+        'crontab -l 2>/dev/null | grep memuk-sync; cat /etc/cron.d/memuk-sync 2>/dev/null || echo ""',
+        { timeout: 5000 }
+      ).toString();
+      return {
+        component: 'Sync cron',
+        status: out.includes('sync_memos') ? 'PASS' : 'FAIL',
+        detail: out.includes('sync_memos') ? 'Cron entry found' : 'No sync cron entry found',
+      };
+    } catch {
+      return { component: 'Sync cron', status: 'FAIL', detail: 'Cron check failed' };
+    }
+  });
+
+  const passed = results.filter(r => r.status === 'PASS').length;
+  const failed = results.filter(r => r.status === 'FAIL').length;
+  const summary = failed === 0
+    ? `✅ All checks passed (${passed}/${passed})`
+    : `⚠️  ${passed} passed · ${failed} failed`;
+
+  const lines = results.map(
+    r => `${r.status} ${r.component}\n  → ${r.detail}`
+  );
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `🔬 memory-system verify\n\n${lines.join('\n\n')}\n\n${'─'.repeat(50)}\n${summary}`,
+      },
+    ],
+  };
+}