memos-memu-local-memory-tools-for-agent

MCP Server for OpenClaw agents — two-layer local memory: memos (PostgreSQL, raw conversation history) + memuK (SQLite, topic summaries).

Compliance

This package is built to the mcp-creator specification:

• ✅ One-shot enable (install + query)
• ✅ Bootstrap self-check on startup
• ✅ Self-heal (memos_memuk_ensure)
• ✅ Doctor with nextSteps (memos_memuk_doctor)
• ✅ Capability self-discovery (memos_memuk_list_commands)
• ✅ Version + update reporting (memos_memuk_version)
• ✅ Process lock (prevents concurrent ensure)
• ✅ Graceful degradation (structured errors when system is down)
• ✅ Atomic update strategy support (alwaysLatest)
• ✅ Structured logs on every operation

Quick Start

# One-liner (npx — for first install only)
npx @bsbofmusic/memos-memu-local-memory-tools-for-agent

# Production: PM2 resident process (recommended — no cold start)
pm2 start /path/to/memos-memu-local-memory-tools-for-agent/src/index.js --name memos-memu-mcp

# OpenClaw mcporter config (local node, not npx):
{
  "mcpServers": {
    "memos-memu-local-memory-tools-for-agent": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "/path/to/memos-memu-local-memory-tools-for-agent",
      "type": "stdio"
    }
  }
}

Tools (9 total)

System tools (mcp-creator spec)

| Tool | Description | |------|-------------| | memos_memuk_version | Version, latest available, update status, runtime health | | memos_memuk_doctor | Full diagnostic with PASS/FAIL/WARN per component + nextSteps | | memos_memuk_ensure | Idempotent self-heal: repairs all components, optional upgrade | | memos_memuk_list_commands | List all tools with descriptions and usage examples |

Core tools

| Tool | Description | |------|-------------| | install_memory_system | One-shot install: PostgreSQL, memuK, SKILL, cron, credentials | | verify_memory_system | Quick smoke-test of all 7 components | | memos_query | Query memos PostgreSQL for raw conversation history | | memuk_search | Search memuK SQLite for topic summaries | | memos_memuk_query | Query both sources simultaneously (newest first) |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | OPENCLAW_STATE_DIR | ~/.openclaw | Root of OpenClaw state | | MEMOS_DB_PASSWORD | memos_local_20260312 | PostgreSQL password | | OPENAI_API_KEY | — | Required for embedding (if used) | | ALWAYS_LATEST | 1 | Auto-upgrade before each ensure call | | UPDATE_STRATEGY | simple | atomic or simple | | LOG_LEVEL | info | debug, info, warn, error |

Auto-Update Strategy

• Default (ALWAYS_LATEST=1): each ensure call checks npm for new version, upgrades if available.
• Atomic mode (UPDATE_STRATEGY=atomic): uses runtime_active/ + runtime_staging/ directories with smoke test before switching.
• Off (ALWAYS_LATEST=0): no auto-upgrade.

Data Directory

| Component | Path | |-----------|------| | memos PostgreSQL | Docker container memos-postgres | | memuK SQLite | ~/.openclaw/memu.db | | Credentials | ~/.openclaw/secrets/memusync.env (mode 0600) | | Sync checkpoint | ~/.openclaw/.memu_incremental_checkpoint | | SKILL.md | ~/.openclaw/workspace/skills/memory-triple-recall/SKILL.md |

Failure Modes & nextSteps

| Error | Cause | nextSteps | |-------|-------|-----------| | memos-postgres container not running | Docker stopped | docker start memos-postgres | | DB not found ~/.openclaw/memu.db | memuK not initialized | memos_memuk_ensure({}) | | credentials file missing | env not created | install_memory_system({}) | | bootstrap checks failed | multiple | memos_memuk_doctor({}) first | | ensure already running | concurrent call | Wait or kill stuck process |

Verified Setup (per mcp-creator §6)

| Test | Status | |------|--------| | One-shot install | ✅ | | Subagent cold-start recall | ✅ | | PM2 resident process stability | ✅ | | Graceful degradation | ✅ | | Process lock | ✅ |

Architecture

┌─────────────────────────────────────────────┐
│  OpenClaw agent                             │
│  ↓ calls mcporter                           │
│  mcporter → MCP stdio → Node.js server      │
│    ├─ bootstrapEnsure() on startup           │
│    ├─ process lock                           │
│    └─ 9 tools dispatch                      │
│         ├─ memos_query (PostgreSQL)          │
│         ├─ memuk_search (SQLite)            │
│         ├─ memos_memuk_query (parallel)     │
│         ├─ memos_memuk_doctor (diagnostic)  │
│         ├─ memos_memuk_ensure (self-heal)   │
│         ├─ memos_memuk_version (version)    │
│         ├─ memos_memuk_list_commands        │
│         ├─ install_memory_system            │
│         └─ verify_memory_system             │
└─────────────────────────────────────────────┘

License

MIT. Wraps memos (Apache-2.0) and uses @modelcontextprotocol/sdk (MIT).