Metacognitive Memory — OpenClaw Plugin

L0~L6 cognitive memory system for OpenClaw agents. Pure sql.js WASM SQLite — zero native dependencies, cross-device portable, single-file portable.

Why

OpenClaw agents start fresh every session. This plugin gives them a long-term, structured memory that mirrors how humans consolidate experience:

Each layer is exposed as an independent tool (20 in total) so the agent can compose memory operations just like any other tool call.

Features

• Zero native dependencies — sql.js is a WASM-compiled SQLite, runs anywhere Node.js runs
• Cross-device portable — copy the single .db file between machines and your memory travels
• Opt-in conversation capture — set allowConversationAccess: true to enable automatic L0 capture via message:received/message:sent hooks
• 20 independent tools — one per memory operation, no monolithic "remember" tool
• Sensitive data redaction — API keys, passwords, tokens are automatically redacted before storage
• Per-session isolation — all mutating operations enforce session_id constraints to prevent cross-session access
• Configurable extraction — everyNConversations and idleTimeoutSeconds tune when L1 fires
• Self-diagnostic — l6_self_check returns a JSON summary of error counts and capability categories

Privacy & Security

⚠️ WARNING: This plugin captures and stores conversation content. Review before enabling:

• DO NOT enable allowConversationAccess: true in workspaces handling credentials, regulated data, or proprietary prompts
• Disable automatic capture and use manual l0_capture for sensitive contexts
• Sensitive data (API keys, passwords, tokens, SSN, credit cards) are automatically redacted, but manual review is still recommended
• All mutation operations enforce session isolation to prevent cross-session data access

One-shot install (ClawHub)

# 1. Install
openclaw plugins install metacognitive-memory

# 2. Configure (OPT-IN for conversation capture).
#    Edit ~/.openclaw/openclaw.json:

{
  "plugins": {
    "slots": {
      "memory": "metacognitive-memory"
    },
    "entries": {
      "metacognitive-memory": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": false
        },
        "config": {
          "stateDir": "~/.openclaw/metacognitive_memory",
          "everyNConversations": 3,
          "idleTimeoutSeconds": 60
        }
      }
    }
  }
}

⚠️ Security: allowConversationAccess: false by default. Only set to true if you want automatic conversation capture. Do NOT enable in sensitive workspaces.

# 3. Restart the gateway and verify
openclaw gateway restart
openclaw plugins inspect metacognitive-memory

Expected: Status: loaded, Origin: config, Registered 20 tools in ~/.openclaw/logs/openclaw.log.

From source (developer / local link)

git clone <this-repo>
cd metacognitive-memory-plugin
npm install
npm run build                       # tsc → dist/
openclaw plugins install . --link  # link instead of copy; restart picks up source edits

The --link flag means dist/ edits are picked up after a gateway restart — no need to re-install.

Hook policy

The allowConversationAccess flag controls automatic L0 capture:

• allowConversationAccess: true — OPT-IN. The plugin reads raw inbound/outbound message bodies from message:received/message:sent events and stores them in L0. Only enable in non-sensitive workspaces.
• allowConversationAccess: false (default) — Only manual l0_capture tool works; hooks are not registered.

⚠️ Security Notice: This plugin stores conversation content locally. Avoid enabling automatic capture in workspaces handling credentials, regulated data, or proprietary prompts.

Configuration reference

Pass under plugins.entries.metacognitive-memory.config:

The values are read by the plugin at startup; restart the gateway to apply changes.

Storage layout

<stateDir>/
└── memory.db # single-file SQLite, portable

Tables:

Backup = copy memory.db. The plugin auto-saves on every write.

Tools reference

All 20 tools take session_id as the primary key. L4 and L5 also expose id-based update/verify tools.

L0 — Raw Capture

L1 — Extraction

L2 — Scene Blocks

L3 — Cognitive Graph

L4 — Goal Tree

L5 — Knowledge Base

L6 — Self-Model

Memory type reference

L1 Memory Types: preference · fact · decision · context · instruction

L2 Scene Types: project · decision · interaction · error · growth

L3 Entity Types: person · project · supplier · decision · event · concept

L4 Goal Status: pending · in_progress · blocked · done · cancelled

L6 Error Types: sql_error · config_error · logic_error · tool_error · recall_error

Compatibility

• OpenClaw >= 2026.5.17
• Node.js >= 22.16.0 (sql.js WASM requires modern Node)
• No native build step; works on Windows / macOS / Linux identically

License

MIT