@everme/zeroclaw

EverMe memory for ZeroClaw, the Rust agent runtime.

ZeroClaw has no hook API and no Node plugin API. Its WASM memory plugins cannot reach the network. This package uses the one extension point that can: the lucid memory backend, which runs an external command each time ZeroClaw stores a memory.

What it does

Install with evercli plugin install zeroclaw. The installer does these steps:

1. Stages this bundle at ~/.zeroclaw/everme/ and writes the credentials to ~/.zeroclaw/everme.env (mode 0600).
2. Writes the wrapper ~/.zeroclaw/everme-lucid, which runs bin/lucid.js with an absolute node path.
3. Points [storage.lucid.everme] at the wrapper, and sets memory.backend = "lucid.everme" when the backend was sqlite or unset.
4. Adds the everme-memory MCP server and the everme-memory skill to every agent through [mcp_bundles.everme] and [skill_bundles.everme].
5. Adds the three read-only memory tools to auto_approve on each agent's risk profile below level full.

No token goes into config.toml. The Lucid bridge and the MCP launcher both read everme.env, so a token rotation rewrites one file.

Capture

ZeroClaw calls everme-lucid store "<key>: <content>" --type=<type> --project=<data dir> after each memory store. The bridge writes the event to a spool under ~/.everme/state/zeroclaw/, starts a detached uploader and exits. ZeroClaw awaits this command inside the turn, so the turn waits only for the spool write.

• The bridge sends an autosaved user message (key user_msg_<uuid>) as a user message.
• The bridge sends a memory_store fact (any other key) as an assistant note: Remembered <key>: <content>.
• The bridge skips text that ZeroClaw generates itself: cron and heartbeat prompts, and recalled memory blocks.

The uploader sends every pending event to /mem/agent-memory without a flush, one request per conversation. A conversation is one ZeroClaw install on one local day (zeroclaw:<hash of the data dir>:<YYYY-MM-DD>), because the Lucid protocol carries no session id. A failed upload keeps its events for the next uploader. The uploader drops events older than seven days.

ZeroClaw passes only stored memories to the backend. Assistant replies and tool calls do not reach the bridge, so they are not captured.

Recall

In ZeroClaw 0.8.x the bridge's context command does not run in a normal session. Every agent's memory is agent-scoped, and LucidMemory::recall_for_agents reads only the local SQLite mirror. Recall therefore uses two other parts of this package:

• bin/mcp.js loads everme.env and runs the EverMe MCP server that evercli resolved at install time (the EverMe private runtime, or npx -y @everme/memory-mcp@latest). The agent gets everme-memory__mem_search, everme-memory__mem_context and, where the server offers it, everme-memory__mem_skill.
• skills/everme-memory/SKILL.md is an always: true skill. It tells the model three things:
  • load the profile in the first reply;
  • search before it answers a question about the user's history;
  • save durable facts with memory_store.

The bridge still implements context, so recall becomes automatic as soon as ZeroClaw's scoped recall path calls the remote leg. The upstream change is one method: make recall_for_agents consult the external command when the local hits are below the threshold, as recall already does.

Limits

• Capture needs memory.auto_save = true (the ZeroClaw default). With it off, only memory_store facts reach EverMe.
• When memory.backend is not sqlite (for example postgres.work), the installer leaves it alone and capture is off. Recall through MCP still works.
• An agent added after install gets neither the MCP server nor the skill. Run evercli plugin install zeroclaw again to grant them.
• zeroclaw service restart (or a new session) is necessary after install, uninstall and upgrade.

Files

| Path | Role | |---|---| | bin/lucid.js | Lucid protocol entry: store spools and starts the uploader; context prints a <lucid-context> block | | bin/worker.js | Detached uploader; waits 1.5 s (EVERME_ZEROCLAW_COALESCE_MS) so one turn's events go out together | | bin/mcp.js | MCP launcher: loads everme.env, then runs the MCP server command given after -- | | src/ | Protocol parsing, spool and upload, credentials, bounded diagnostics (~/.everme/state/zeroclaw/bridge.log) | | skills/everme-memory/SKILL.md | The recall skill the installer copies to ~/.zeroclaw/shared/skills/everme/ |

Test

npm test --workspace @everme/zeroclaw

tests/fixtures/zeroclaw-0.8.6-lucid-argv.jsonl holds the argv that ZeroClaw 0.8.6 passed to the backend command in a live run, with the install path replaced.