Metacognitive Memory — OpenClaw Plugin

L0~L6 six-layer 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
• Automatic L0 capture — registers message:received, message:sent, session:patch hooks so every conversation is journaled without any extra calls
• 20 independent tools — one per memory operation, no monolithic "remember" tool
• Configurable extraction — everyNConversations and idleTimeoutSeconds tune when L1 fires
• Self-diagnostic — l6_self_check returns a JSON summary of error counts and capability categories
• Per-session isolation — every row is scoped by session_id so multi-agent workloads don't mix

One-shot install (ClawHub)

# 1. Install
openclaw plugins install metacognitive-memory

# 2. Enable + register the memory slot + grant hook policy.
#    Edit ~/.openclaw/openclaw.json:

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

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

Expected: Status: loaded, Origin: config, Registered 20 tools + 3 hooks 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 — why these flags matter

The two flags in entries.metacognitive-memory.hooks are not optional if you want automatic L0 capture:

• allowConversationAccess: true — required. The plugin reads the raw inbound/outbound message bodies from message:received / message:sent events. Without it, those hooks are blocked by core's safety gate and the database stays empty.
• allowPromptInjection: true — optional but recommended. Lets the plugin mutate prompts through typed hooks (e.g. injecting recalled context). Safe for this plugin because it only injects, never replaces.

If you'd rather not auto-capture, set allowConversationAccess: false — the 20 tools still work, you just have to call l0_capture yourself.

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>/
└── .metacognitive_memory/
    └── memory.db            # single-file SQLite, portable

Tables:

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

The .metacognitive_memory subdirectory is intentional — it lets multiple plugins share a parent stateDir without colliding.

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

Validation workflow

After install, run these to confirm everything works:

# 1. Plugin loaded
openclaw plugins inspect metacognitive-memory
#   → Status: loaded

# 2. Gateway registered tools
openclaw gateway restart
grep "metacognitive-memory" ~/.openclaw/logs/openclaw.log | tail
#   → "[metacognitive-memory] Registered 20 tools + 3 hooks"

# 3. DB is created on first call
ls -la ~/.openclaw/state/metacognitive-memory/.metacognitive_memory/memory.db

# 4. Quick end-to-end smoke test from a node REPL
node -e "
import('metacognitive-memory-plugin').then(async (m) => {
  const core = new m.MetaCore({ stateDir: '~/.openclaw/state/metacognitive-memory/.metacognitive_memory' });
  await core.initialize();
  const id = core.l0Capture({ sessionId: 'smoke', role: 'user', content: 'hello' });
  console.log('L0 row:', id);
  console.log('L0 list:', core.l0List('smoke').length, 'rows');
  await core.close();
});
"

Common pitfalls

Architecture

metacognitive-memory-plugin/
├── openclaw.plugin.json     # manifest: 20 contract tool names + configSchema
├── package.json             # npm + openclaw.extensions + peer dep
├── tsconfig.json            # portable: no absolute paths
├── src/
│   ├── index.ts             # default entry: definePluginEntry + 20 tools + 3 hooks
│   ├── plugin-entry.ts      # alt entry with the same surface (used by some loaders)
│   ├── core/
│   │   ├── types.ts         # L0~L6 shared types
│   │   ├── meta-core.ts     # L0~L6 orchestration facade
│   │   └── store.ts         # sql.js SQLite store (schema + queries)
│   ├── adapters/openclaw/
│   │   └── host-adapter.ts  # stateDir resolution (config → runtime → default)
│   └── types/
│       └── openclaw-plugin-sdk.d.ts   # ambient shim for `openclaw/plugin-sdk/core`
└── dist/                    # build output (npm `files` includes this)

Data flow

message:received ─┐
message:sent     ─┼─→ l0Capture ─→ memory_l0_raw
session:patch    ─┘
                                  │
                          everyNConversations / idleTimeout
                                  │
                                  ▼
                            l1Extract ─→ memory_l1_extracted
                                  │
                  ┌───────────────┼───────────────┐
                  ▼               ▼               ▼
            l2CreateScene   l3UpdateGraph   l5AddFact
                  │               │               │
                  ▼               ▼               ▼
        memory_l2_scenes  kg_entity/kg_rel  knowledge_fact
                                  │
                                  ▼
                            l4CreateGoal ─→ goal
                                  │
                                  ▼
                       l6_log_error / l6_self_check
                                  │
                                  ▼
                            error_log

Development

npm install              # one-time
npm run build            # tsc → dist/
npm run build:watch      # rebuild on save

# Type-check only
npx tsc --project tsconfig.json --noEmit

# Validate the dist entry OpenClaw will load
openclaw plugins validate --entry ./dist/index.js

# Run unit tests
npm test

To work on a live OpenClaw instance:

openclaw plugins install . --link   # link mode
# ...edit src/...
npm run build                       # rebuild dist/
openclaw gateway restart            # pick up new dist/

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