# Agent integration
clipmem is designed as a JSON-first CLI that agents such as OpenClaw
and Hermes Agent can call directly. You can also install packaged
skills that give agents structured knowledge of clipmem's commands,
filters, and output schemas.
## Install the OpenClaw skill
Install the packaged skill using the CLI rather than copying files
manually:
```bash
clipmem agents openclaw install-skill
```
By default this installs into the active OpenClaw workspace:
```
~/.openclaw/workspace/skills/clipboard-memory
```
The workspace root is resolved from
`openclaw config get agents.defaults.workspace`, falling back to
`~/.openclaw/workspace`.
To install into the shared OpenClaw skills directory instead:
```bash
clipmem agents openclaw install-skill --shared
# writes to ~/.openclaw/skills/clipboard-memory
```
Or to a specific destination:
```bash
clipmem agents openclaw install-skill --dest /path/to/skill --force
```
## Install the Hermes Agent skill
Install the packaged Hermes Agent skill using the CLI rather than
copying files manually:
```bash
clipmem agents hermes install-skill
```
By default this installs into the Hermes local skills tree:
```
~/.hermes/skills/productivity/clipboard-memory
```
To install into a specific destination, pass the exact skill directory:
```bash
clipmem agents hermes install-skill --dest /path/to/clipboard-memory --force
```
Hermes can also scan shared skill directories when they are configured
under `skills.external_dirs` in `~/.hermes/config.yaml`. Use `--dest`
when you want clipmem to write directly into one of those directories.
## What the skill ships
The OpenClaw, Hermes Agent, and portable packages ship the same
command references and setup checker. Runtime-specific package metadata
and troubleshooting guidance live in each package's `SKILL.md` and
`references/troubleshooting.md`.
```
SKILL.md
references/commands.md
references/json-schema.md
references/examples.md
references/setup-check.md
references/troubleshooting.md
scripts/check-setup.sh
```
The packaged skills point agents at the JSON-first retrieval commands:
- `clipmem recall "<query>" --format json` - start here
- `clipmem recall --prefer-recent --hours 24 --format json` - for
recent items without a specific query
- `clipmem timeline ... --format json` - when chronology matters
- `clipmem search ... --format json` - when direct lexical matching
matters
- `clipmem get <snapshot-id> --format json` - when deeper nested
detail is needed
## Manage the skill
Check OpenClaw integration health:
```bash
clipmem agents openclaw doctor
```
Check Hermes Agent integration health:
```bash
clipmem agents hermes doctor
```
Print the packaged OpenClaw SKILL.md for inspection:
```bash
clipmem agents openclaw print-skill
```
Print the packaged Hermes Agent SKILL.md for inspection:
```bash
clipmem agents hermes print-skill
```
Uninstall the OpenClaw skill:
```bash
clipmem agents openclaw uninstall-skill
```
Uninstall the Hermes Agent skill:
```bash
clipmem agents hermes uninstall-skill
```
## Troubleshooting
OpenClaw must be able to run `clipmem` from its own environment, not
just from your interactive shell.
If you installed `clipmem` into `~/.local/bin`, make sure that
directory is on the PATH seen by OpenClaw. If sandboxing is active,
the binary may also need to be available inside the sandbox image or
container.
Start with:
```bash
clipmem agents openclaw doctor
openclaw sandbox explain # when available
```
Hermes must also be able to see both the skill directory and the
`clipmem` binary from its own runtime environment. Start with:
```bash
clipmem agents hermes doctor
hermes skills list # when Hermes is installed
```
For empty results, sandbox visibility, or binary-only snapshots where
exact text isn't available, see
[troubleshooting](troubleshooting.md).
## Example agent prompts
Once the skill is installed, agents can handle prompts like:
- "Find that ffmpeg command I copied yesterday."
- "Search my clipboard history for the SQL migration with WAL mode."
- "What was the URL I copied from Safari about objc2 `NSPasteboard`?"
- "Show me the full clipboard entry for snapshot 128."
## Skill packaging
The skill exists in four locations within the repository:
- `skills/clipboard-memory/` - the canonical cross-agent skill source
that repo-based installers discover from the root.
- `extras/openclaw/clipboard-memory/` - the OpenClaw-native package
installed by `clipmem agents openclaw install-skill`.
- `extras/hermes/clipboard-memory/` - the Hermes Agent-native package
installed by `clipmem agents hermes install-skill`.
- `extras/agent-skills/clipboard-memory/` - a portable packaging mirror
for generic agent-skill runtimes beyond native targets.
For compatibility, `./scripts/install_openclaw_skill.sh` still exists
as a thin wrapper around
`clipmem agents openclaw install-skill --shared --force`.
## Next steps
- [Output formats](output-formats.md) — understand the JSON envelope,
flattened text fields, and TOON skim output
- [Command reference](command-reference.md) — exhaustive flag-level
reference for every command
- [Troubleshooting](troubleshooting.md) — diagnose empty results,
PATH issues, and database problems
