agentmemory-hooks

어떤 스킬인가요?

The agentmemory plugin hooks that capture observations automatically across the agent session lifecycle. Use when explaining how memory gets captured without manual saves, when debugging missing observations, or when tuning what gets recorded.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# agentmemory hooks reference

Generated from `plugin/hooks/hooks.json`. Do not edit the block below by hand; run `npm run skills:gen` after changing the hook registration.

<!-- AUTOGEN:hooks START - generated by scripts/skills/generate.ts, do not edit by hand -->
The Claude Code plugin registers hooks on 12 lifecycle events to capture observations automatically:

- `Notification`
- `PostToolUse`
- `PostToolUseFailure`
- `PreCompact`
- `PreToolUse`
- `SessionEnd`
- `SessionStart`
- `Stop`
- `SubagentStart`
- `SubagentStop`
- `TaskCompleted`
- `UserPromptSubmit`
<!-- AUTOGEN:hooks END -->

---
name: agentmemory-hooks
description: The agentmemory plugin hooks that capture observations automatically across the agent session lifecycle. Use when explaining how memory gets captured without manual saves, when debugging missing observations, or when tuning what gets recorded.
user-invocable: false
---

The agentmemory plugin registers lifecycle hooks so memory is captured automatically. You do not have to call `memory_save` for routine work; the hooks observe tool use, prompts, and session boundaries and write observations for you.

## Quick start

For Claude Code, install its plugin:

```bash
/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory
```

For Devin CLI and Devin Desktop, install the plugin and start a new session:

```bash
devin plugins install rohitg00/agentmemory#plugin
```

Run `/hooks` inside Devin to confirm the agentmemory hooks are loaded. Plugin hooks run only in local Devin sessions, not in cloud sessions.

Pi and OMP install native recall and capture with `agentmemory connect pi --with-mcp` or `agentmemory connect omp --with-mcp`. Reload Pi or restart OMP, then inspect `/agentmemory-status`. DSH requires `agentmemory connect dsh --with-hooks` and a restart. Cursor lifecycle hooks come from its enabled plugin, separately from `connect cursor`'s MCP setup.

Hermes and OpenClaw use their native integrations and lifecycle contracts. Follow the matching integration setup instructions and verify a real turn creates an observation. Installing shared skills or connecting MCP alone does not enable automatic capture. Watch recorded observations in the viewer at `http://localhost:3113` when using the default port. A pending capture queue is not proof that the daemon stored the event.

## What the hooks record

The Claude Code plugin registers 12 hooks. They send what they record to the
local agentmemory server, which stores it on this machine.

- SessionStart and SessionEnd frame each unit of work and let `handoff` resume it. SessionEnd also reads the host transcript file to recover user prompts that a hook missed.
- UserPromptSubmit records each prompt you type.
- PostToolUse and PostToolUseFailure record the tool name, its input, and its output or error. This includes results returned by other connectors and MCP servers. Long output is truncated and `<private>` blocks and common secret formats are redacted before storage.
- PreToolUse does nothing by default. With `AGENTMEMORY_INJECT_CONTEXT=true` it sends the file paths and search patterns from a tool's input to look up related memory and prints what it finds.
- Stop and SubagentStop record the final assistant reply (up to 4,000 characters). SubagentStart, Notification and TaskCompleted record those events.
- PreCompact syncs memory before the host trims context.

If the server is unreachable, events wait in a local capture spool (at most 5 MiB, kept up to 7 days) and are sent when it comes back.

The plugin does not register a git post-commit hook, so commits are linked to sessions only when another integration records them.

## Important

- The plugin hooks capture without an LLM. Nothing they record goes to an outside AI provider unless `AGENTMEMORY_LLM_PROVIDER` or a cloud `EMBEDDING_PROVIDER` is set on the server. Per-observation LLM compression also needs `AGENTMEMORY_AUTO_COMPRESS=true`.
- Hook context injection is off by default. SessionStart, PreToolUse and PreCompact print stored memory into the conversation only with `AGENTMEMORY_INJECT_CONTEXT=true`.
- Hooks send the server secret only to a loopback URL or an `https://` URL. Native integrations have their own recall/capture settings; inspect the host configuration instead of assuming these flags control every plugin.
- If observations are missing, confirm the plugin is enabled and the server is running. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md).

## See also

- agentmemory-config for the capture and injection flags.
- The handoff, recap, and session-history skills consume what these hooks record.

## Reference

The exact registered hook events live in REFERENCE.md, generated from `plugin/hooks/hooks.json`.

<!-- AUTOGEN:troubleshooting START - generated by scripts/skills/generate.ts, do not edit by hand -->
# Troubleshooting agentmemory skills

Recovery steps for separately installed skills. This document is generated into
each skill directory so native skill readers can open it without parent traversal.

## "MCP tool not available"

Missing tools can mean a stopped MCP process, a disconnected daemon, or an
explicitly reduced tool surface. Walk these in order:

1. Identify the host. In Claude Code, inspect `/plugin list` and `/mcp`.
   In Hermes, inspect the configured memory provider and `mcp_servers` separately.
   In OpenClaw, validate the host configuration and inspect its MCP servers and
   native plugins separately. In Pi or OMP, inspect `/agentmemory-status` and the
   MCP inventory separately; native save/search does not prove the broader tools
   are connected. Do not run another host's setup commands.
2. Restart or reload the affected host connection after configuration changes.
3. Inspect the connected tool inventory. Hermes may namespace MCP tools; invoke
   the actual advertised names and schemas. A native memory provider is not
   proof that every MCP tool or shared skill is available.
4. Check `agentmemory status` and the daemon's `AGENTMEMORY_TOOLS` setting.
   Codex's bundled bridge lists the daemon's enabled tools. The standalone shim
   used by other hosts can fall back to seven basic tools with a separate store.
   Do not claim full daemon functionality based on those seven tools.
5. If `agentmemory connect codex` and the Codex plugin are both enabled, choose
   one MCP connection. Check `/hooks` before adding global hook fallbacks.

Hermes, OpenClaw, Pi and OMP connector installations bundle skills; other hosts
may install them separately. Check the host's skill inventory and open this file
from the installed skill directory. Test automatic capture with a real turn and
a recorded observation; tool connectivity alone does not establish lifecycle
capture.

An outage or timeout is not an empty search result. Report the failure. A write
may have committed before the response was lost; inspect state before retrying.

## REST fallback

When the MCP tools stay unavailable but the daemon is running, call the REST
API directly:

1. Set `AGENTMEMORY_URL` to the daemon base URL (default `http://localhost:3111`).
2. The REST API requires a bearer credential by default. Use the host's explicit
   `AGENTMEMORY_SECRET`; for loopback URLs only, fall back to the secret in
   `~/.agentmemory/.env` and then `~/.agentmemory/secret`. Load the value locally
   without displaying it. Never send a local-file secret to a remote URL.
   If `AGENTMEMORY_CREDENTIAL_MODE=explicit`, require the explicit host credential
   and do not read local credential files.
   Authenticated REST fallback requests require HTTPS for non-loopback
   URLs; HTTP is allowed for loopback URLs (`localhost`, `127.0.0.0/8`, or `[::1]`).
   Reject redirects on authenticated requests. Do not print or save the secret.

Endpoint map by skill:

| Skill           | REST call                                                        |
| --------------- | --------------------------------------------------------------- |
| remember        | `POST /agentmemory/remember`                                     |
| recall          | `POST /agentmemory/smart-search`                                 |
| recap           | `GET /agentmemory/sessions` + `POST /agentmemory/smart-search`   |
| handoff         | `GET /agentmemory/sessions` + `POST /agentmemory/smart-search`   |
| session-history | `GET /agentmemory/sessions`                                      |
| commit-context  | `GET /agentmemory/session/by-commit?sha=<sha>`                   |
| commit-history  | `GET /agentmemory/commits` (URL-encode every query param)       |

The MCP host reads the plugin MCP configuration. Restart the daemon after
changing its configuration, then restart or reconnect the host MCP process after
changing its URL or explicit secret. The local bridge reads the credential files
for each request; it does not inherit other daemon `.env` settings.
<!-- AUTOGEN:troubleshooting END -->