@everme/picoclaw

EverMe memory for PicoClaw, as a PicoClaw process hook. Recall goes into each model call, and every finished turn goes to EverMe. The EverMe search tools come through PicoClaw's MCP support.

Install

Run one command:

evercli plugin install picoclaw

Then restart the PicoClaw gateway, or start a new picoclaw agent run.

evercli needs these before it writes anything:

• A PicoClaw config file. Run picoclaw onboard once if you have none.
• Node.js 18 or newer on PATH.

evercli writes these files:

| Path | Content | |---|---| | ~/.picoclaw/everme.env | Agent credentials, mode 0600 | | ~/.picoclaw/everme/ | A staged copy of this package, with its dependencies | | ~/.picoclaw/everme-mcp/ | A staged copy of @everme/memory-mcp; not written when the EverMe Desktop runtime serves MCP | | config.json → hooks.processes.everme | The process hook | | config.json → tools.mcp.servers.everme-memory | The search tools |

PICOCLAW_HOME and PICOCLAW_CONFIG move these paths the same way they move PicoClaw's own files. config.json never holds the token: the hook and the MCP server both read everme.env, the MCP server through PicoClaw's env_file.

To remove everything, run evercli plugin uninstall picoclaw --yes, then restart the gateway.

How it works

PicoClaw starts the hook once per agent loop and speaks JSON-RPC 2.0 to it over stdio (pkg/agent/hook_process.go). The hook registers for these events:

| PicoClaw event | What the hook does | |---|---| | agent.turn.start (observe) | Starts the recall search for the user message | | before_llm (intercept) | Appends the profile and recall blocks to the newest user message | | agent.turn.end (observe) | Starts a detached worker that uploads the turn |

The recall block goes into the user message. PicoClaw rejects a hook change to a system message or to the tool list: it restores the original and logs a warning. The change applies to one model call only. PicoClaw stores the user message before the call. It also rebuilds the call messages from its history on every iteration, so the block never reaches the session file. For the same reason the hook adds the block again on each model call of a turn, and it sends the profile with every turn.

The worker reads the session file <workspace>/sessions/<session key>.jsonl and uploads what the checkpoint has not seen. Each line's created_at is its native identity. PicoClaw keeps that timestamp when it rewrites the file after a summary, so a kept line is never sent twice. A worker uploads only up to the last finished turn, so a turn that is still running is never split across two uploads. Captures of one session wait for each other before the SDK's time budget starts.

Fail-open rules

PicoClaw does not start its agent loop when a process hook cannot start, or when every configured MCP server fails to connect. The plugin therefore follows these rules:

• evercli resolves an absolute Node path and checks its version at install time. The hook entry does not depend on PATH.
• The MCP server runs from the EverMe Desktop runtime or from the staged memory-mcp, never through npx. So a start needs no network access.
• The hook answers hook.hello at once, and any error inside a handler becomes continue.
• A model call waits for recall up to one second less than PicoClaw's hooks.defaults.interceptor_timeout_ms (5000 ms by default). After that the call goes on without recall.
• A modify response larger than 900 KiB becomes continue, because PicoClaw stops reading a hook after a line longer than 1 MiB.

Warning: If you remove Node.js or the staged directories by hand, PicoClaw stops running its agent. Run evercli plugin uninstall picoclaw first.

Knobs

evercli sets these in hooks.processes.everme.env. All are optional.

| Variable | Default | Meaning | |---|---|---| | EVERME_ENV_FILE_PATH | ~/.picoclaw/everme.env | Credentials file | | EVERME_PICOCLAW_WAIT_MS | 4000 | How long a model call waits for recall | | EVERME_PICOCLAW_RECALL_BUDGET_MS | 8000 | Deadline of the recall requests | | EVERME_PICOCLAW_WORKSPACE | none | Workspace used when an event names none | | EVERME_PICOCLAW_LOG_FILE | none | Append diagnostics and worker request IDs to this file |

Without a log file, the hook writes only failures to stderr. PicoClaw logs every hook stderr line as a warning.

Known limits

• PicoClaw logs Hook attempted to modify tool definitions; preserving original tools once for each model call that gets recall. The hook does not change the tools. PicoClaw compares the echoed tool list with its own after a JSON round trip, and the values do not compare equal. The tool list stays correct.
• Everyone who talks to the agent gets the same recall. On a channel with other people (a Telegram group, for example), restrict senders with the channel's allow_from.
• Subagent turns are not uploaded on their own. The parent's session holds the spawn call and its result.
• evercli import conversations does not read PicoClaw sessions yet. On first install the worker uploads only the newest turn of a session.