@agentmemory/agentmemory 0.9.30 → 0.9.31

package/integrations/omp/skills/agentmemory-mcp-tools/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: agentmemory-mcp-tools
+description: Map of every agentmemory MCP tool, what each does, and its parameters. Use when choosing which memory tool to call, when a tool name or argument is unclear, or when answering what agentmemory can do via MCP.
+user-invocable: false
+---
+
+This skill indexes agentmemory's MCP tools. Use the connected server's tool inventory and schemas; a native memory provider may expose a smaller set under different names. Hermes and OpenClaw skills that need the full surface require a separate MCP connection to the running daemon. For Pi and OMP, connect with `--with-mcp` to enable the broader workflows. Pi exposes MCP names with an `mcp__agentmemory__` prefix; OMP exposes MCP operations as `xd://mcp__agentmemory_<tool>` devices through its `write` tool.
+
+## Quick start
+
+Save then recall:
+
+1. `memory_save` with `content` (the insight), `concepts` (comma-separated keywords), `files` (comma-separated paths).
+2. `memory_smart_search` with `query`, `limit`, and `targetLayer: "memory"` to retrieve saved knowledge later. Omit `targetLayer` to also search captured observations. This runs hybrid BM25 plus vector plus graph-expanded search.
+
+## Tool families
+
+- Capture: `memory_save`, `memory_compress_file`. Automatic observations use native hooks or `POST /agentmemory/observe`, not an MCP observation tool.
+- Retrieve: `memory_smart_search`, `memory_recall`, `memory_file_history`, `memory_timeline`, `memory_vision_search`.
+- Sessions and commits: `memory_sessions`, `memory_commits`, `memory_commit_lookup`.
+- Knowledge and graph: `memory_lesson_save`, `memory_lesson_recall`, `memory_graph_query`, `memory_relations`, `memory_patterns`, `memory_crystallize`.
+- Structured slots: `memory_slot_create`, `memory_slot_append`, `memory_slot_get`, `memory_slot_list`, `memory_slot_replace`, `memory_slot_delete`.
+- Governance and health: `memory_governance_delete`, `memory_audit`, `memory_verify`, `memory_heal`, `memory_diagnose`.
+
+## Workflow
+
+1. Pick the narrowest tool for the task. Prefer `memory_smart_search` for open recall, `memory_recall` when you already have a focused query, `memory_sessions` for session listings.
+2. Look up exact parameter names and which are required in REFERENCE.md before calling.
+3. Pass only documented fields. REST handlers whitelist fields and drop unknown ones.
+4. For budgeted `memory_recall`, distinguish `matched_count: 0` from
+   `excluded_by_budget > 0`. Expand clipped or omitted IDs with
+   `memory_smart_search` and `expandIds`, preserving the same scope filters.
+
+## See also
+
+- agentmemory-rest-api for the HTTP equivalents.
+- agentmemory-config for tool-visibility and feature flags.
+- The user-invocable action skills (remember, recall, recap, handoff, forget) wrap the most common tools.
+
+## Reference
+
+Full tool table with parameters and the core-set marking lives in REFERENCE.md, generated from source so it never drifts.

package/integrations/omp/skills/agentmemory-mcp-tools/TROUBLESHOOTING.md

@@ -0,0 +1,70 @@
+<!-- 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 -->

package/integrations/omp/skills/agentmemory-rest-api/REFERENCE.md

@@ -0,0 +1,158 @@
+# agentmemory REST API reference
+
+Generated from `src/triggers/api.ts`. Do not edit the block below by hand; run `npm run skills:gen` after changing the registered endpoints.
+
+<!-- AUTOGEN:rest START - generated by scripts/skills/generate.ts, do not edit by hand -->
+The REST API is the primary surface. All paths are under `http://localhost:3111` (override with `--port`). Send `Authorization: Bearer <secret>`: the value of `AGENTMEMORY_SECRET`, or the one generated into `~/.agentmemory/secret` on first start when it is unset. Writes must use `Content-Type: application/json`.
+
+146 registered endpoints:
+
+| Method | Path |
+| --- | --- |
+| GET | `/agentmemory/actions` |
+| POST | `/agentmemory/actions` |
+| POST | `/agentmemory/actions/edges` |
+| GET | `/agentmemory/actions/get` |
+| POST | `/agentmemory/actions/update` |
+| GET | `/agentmemory/audit` |
+| POST | `/agentmemory/auto-forget` |
+| GET | `/agentmemory/branch/detect` |
+| GET | `/agentmemory/branch/sessions` |
+| GET | `/agentmemory/branch/worktrees` |
+| GET | `/agentmemory/capture` |
+| POST | `/agentmemory/capture/drain` |
+| POST | `/agentmemory/capture/retry` |
+| POST | `/agentmemory/cascade-update` |
+| GET | `/agentmemory/checkpoints` |
+| POST | `/agentmemory/checkpoints` |
+| POST | `/agentmemory/checkpoints/resolve` |
+| GET | `/agentmemory/claude-bridge/read` |
+| POST | `/agentmemory/claude-bridge/sync` |
+| GET | `/agentmemory/commits` |
+| POST | `/agentmemory/compress-file` |
+| GET | `/agentmemory/compression` |
+| POST | `/agentmemory/compression/retry` |
+| GET | `/agentmemory/config/flags` |
+| POST | `/agentmemory/consolidate` |
+| POST | `/agentmemory/consolidate-pipeline` |
+| GET | `/agentmemory/consolidation/status` |
+| POST | `/agentmemory/context` |
+| GET | `/agentmemory/counts` |
+| GET | `/agentmemory/crystals` |
+| POST | `/agentmemory/crystals/auto` |
+| POST | `/agentmemory/crystals/create` |
+| POST | `/agentmemory/diagnostics` |
+| GET | `/agentmemory/diagnostics/followup` |
+| POST | `/agentmemory/diagnostics/heal` |
+| POST | `/agentmemory/enrich` |
+| POST | `/agentmemory/evict` |
+| POST | `/agentmemory/evolve` |
+| GET | `/agentmemory/export` |
+| GET | `/agentmemory/facets` |
+| POST | `/agentmemory/facets` |
+| POST | `/agentmemory/facets/query` |
+| POST | `/agentmemory/facets/remove` |
+| GET | `/agentmemory/facets/stats` |
+| POST | `/agentmemory/file-context` |
+| POST | `/agentmemory/flow/compress` |
+| POST | `/agentmemory/forget` |
+| GET | `/agentmemory/frontier` |
+| POST | `/agentmemory/generate-rules` |
+| POST | `/agentmemory/governance/bulk-delete` |
+| DELETE | `/agentmemory/governance/memories` |
+| POST | `/agentmemory/graph/build` |
+| POST | `/agentmemory/graph/compact` |
+| POST | `/agentmemory/graph/extract` |
+| POST | `/agentmemory/graph/import-graphify` |
+| GET | `/agentmemory/graph/index` |
+| POST | `/agentmemory/graph/index/migrate` |
+| POST | `/agentmemory/graph/index/resume` |
+| GET | `/agentmemory/graph/node` |
+| POST | `/agentmemory/graph/query` |
+| POST | `/agentmemory/graph/reset` |
+| POST | `/agentmemory/graph/snapshot-rebuild` |
+| GET | `/agentmemory/graph/stats` |
+| GET | `/agentmemory/health` |
+| POST | `/agentmemory/import` |
+| GET | `/agentmemory/insights` |
+| POST | `/agentmemory/insights/search` |
+| POST | `/agentmemory/leases/acquire` |
+| POST | `/agentmemory/leases/release` |
+| POST | `/agentmemory/leases/renew` |
+| GET | `/agentmemory/lessons` |
+| POST | `/agentmemory/lessons` |
+| POST | `/agentmemory/lessons/delete` |
+| POST | `/agentmemory/lessons/search` |
+| POST | `/agentmemory/lessons/strengthen` |
+| GET | `/agentmemory/livez` |
+| GET | `/agentmemory/memories` |
+| GET | `/agentmemory/memories/:id` |
+| GET | `/agentmemory/mesh/export` |
+| GET | `/agentmemory/mesh/peers` |
+| POST | `/agentmemory/mesh/peers` |
+| POST | `/agentmemory/mesh/receive` |
+| POST | `/agentmemory/mesh/sync` |
+| POST | `/agentmemory/migrate` |
+| GET | `/agentmemory/next` |
+| GET | `/agentmemory/observations` |
+| GET | `/agentmemory/observations/locate` |
+| POST | `/agentmemory/observe` |
+| POST | `/agentmemory/obsidian/export` |
+| POST | `/agentmemory/patterns` |
+| GET | `/agentmemory/procedural` |
+| GET | `/agentmemory/profile` |
+| POST | `/agentmemory/reflect` |
+| GET | `/agentmemory/relations` |
+| POST | `/agentmemory/relations` |
+| POST | `/agentmemory/remember` |
+| POST | `/agentmemory/replay/import-jsonl` |
+| GET | `/agentmemory/replay/load` |
+| GET | `/agentmemory/replay/sessions` |
+| GET | `/agentmemory/routines` |
+| POST | `/agentmemory/routines` |
+| POST | `/agentmemory/routines/run` |
+| GET | `/agentmemory/routines/status` |
+| POST | `/agentmemory/search` |
+| GET | `/agentmemory/semantic` |
+| GET | `/agentmemory/sentinels` |
+| POST | `/agentmemory/sentinels` |
+| POST | `/agentmemory/sentinels/cancel` |
+| POST | `/agentmemory/sentinels/check` |
+| POST | `/agentmemory/sentinels/trigger` |
+| GET | `/agentmemory/session/by-commit` |
+| POST | `/agentmemory/session/commit` |
+| POST | `/agentmemory/session/end` |
+| POST | `/agentmemory/session/start` |
+| GET | `/agentmemory/sessions` |
+| GET | `/agentmemory/signals` |
+| POST | `/agentmemory/signals/send` |
+| GET | `/agentmemory/sketches` |
+| POST | `/agentmemory/sketches` |
+| POST | `/agentmemory/sketches/add` |
+| POST | `/agentmemory/sketches/discard` |
+| POST | `/agentmemory/sketches/gc` |
+| POST | `/agentmemory/sketches/promote` |
+| DELETE | `/agentmemory/slot` |
+| GET | `/agentmemory/slot` |
+| POST | `/agentmemory/slot` |
+| POST | `/agentmemory/slot/append` |
+| POST | `/agentmemory/slot/reflect` |
+| POST | `/agentmemory/slot/replace` |
+| GET | `/agentmemory/slots` |
+| POST | `/agentmemory/smart-search` |
+| POST | `/agentmemory/snapshot/create` |
+| POST | `/agentmemory/snapshot/restore` |
+| GET | `/agentmemory/snapshots` |
+| GET | `/agentmemory/status` |
+| POST | `/agentmemory/summarize` |
+| GET | `/agentmemory/team/feed` |
+| GET | `/agentmemory/team/profile` |
+| POST | `/agentmemory/team/share` |
+| POST | `/agentmemory/timeline` |
+| POST | `/agentmemory/verify` |
+| GET | `/agentmemory/viewer` |
+| GET | `/agentmemory/viewer/events` |
+| GET | `/agentmemory/viewer/snapshot` |
+| POST | `/agentmemory/vision-embed` |
+| POST | `/agentmemory/vision-search` |
+<!-- AUTOGEN:rest END -->

package/integrations/omp/skills/agentmemory-rest-api/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: agentmemory-rest-api
+description: The agentmemory HTTP REST API surface, the primary protocol for talking to the memory server. Use when calling agentmemory over HTTP, when MCP is unavailable and you need a fallback, or when integrating a host that does not speak MCP.
+user-invocable: false
+---
+
+REST is agentmemory's primary surface. MCP is a bridge on top of it. Every memory operation has an HTTP endpoint under `http://localhost:3111/agentmemory/*`.
+
+## Quick start
+
+```bash
+# liveness
+curl -fsS http://localhost:3111/agentmemory/livez
+
+# For this fixed loopback URL only. Do not print the value or enable shell tracing.
+agentmemory_secret="${AGENTMEMORY_SECRET:-$(cat "$HOME/.agentmemory/secret")}"
+test -n "$agentmemory_secret" || exit 1
+
+# save
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+  -H "Authorization: Bearer $agentmemory_secret" \
+  -H "Content-Type: application/json" \
+  -d '{"content":"chose JWT refresh rotation","concepts":["jwt-refresh-rotation"]}'
+
+# recall
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+  -H "Authorization: Bearer $agentmemory_secret" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"auth token strategy","limit":5}'
+```
+
+## Auth
+
+Protected endpoints require bearer authentication by default, including localhost. Liveness is public. The example uses an explicit environment secret or the generated local secret file; if the daemon uses a secret from its `.env`, load that value locally without displaying it. For a remote daemon, require an explicit credential for that endpoint and HTTPS. Never forward a local-file secret or follow an authenticated redirect to another host. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+
+## Conventions
+
+- Save returns `201`, reads return `200`, validation errors return `400`.
+- Use documented fields only. A successful response does not prove an unsupported field was applied.
+- The REST port defaults to `3111` and is configurable with `--port` or `--instance`. The viewer defaults to `3113`; the internal engine WebSocket defaults to `49134`.
+
+## See also
+
+- agentmemory-mcp-tools for the MCP equivalents.
+- agentmemory-config for local configuration and the secret.
+
+## Reference
+
+The full endpoint list with methods lives in REFERENCE.md, generated from `src/triggers/api.ts`.

package/integrations/omp/skills/agentmemory-rest-api/TROUBLESHOOTING.md

@@ -0,0 +1,70 @@
+<!-- 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 -->

package/integrations/omp/skills/commit-context/EXAMPLES.md

@@ -0,0 +1,71 @@
+# commit-context worked examples
+
+## 1. Line range with a linked session
+
+User: "Why is this retry loop here?" (pointing at lines 40-52 of refresh.ts)
+
+Find the SHA:
+
+```bash
+git blame -L 40,52 src/auth/refresh.ts
+# 9a1b2c3d (dev 2026-06-07) ... retry on revoked token
+```
+
+Look it up:
+
+```json
+memory_commit_lookup { "sha": "9a1b2c3d4e5f60718293a4b5c6d7e8f901234567" }
+```
+
+Response:
+
+```json
+{
+  "commit": { "sha": "9a1b2c3d...", "short": "9a1b2c3", "branch": "main",
+    "author": "dev", "message": "rotate refresh tokens" },
+  "sessions": [ { "id": "7f3a9c21", "project": "app", "observationCount": 14,
+    "summary": "Reworked refresh rotation" } ]
+}
+```
+
+Present:
+
+> `9a1b2c3` on `main` by dev: "rotate refresh tokens". Linked to session
+> `7f3a9c2` "Auth refresh rework" (14 obs). The retry loop handles a token
+> revoked mid-flight, per the session's high-importance observations.
+
+## 2. Function lookup, commit predates linking
+
+User: "What was the agent doing when it wrote validateScope?"
+
+```bash
+git log -L :validateScope:src/auth/scope.ts -n 1
+# 1122aabb ...
+```
+
+```json
+memory_commit_lookup { "sha": "1122aabbccddeeff00112233445566778899aabb" }
+```
+
+Response:
+
+```json
+{ "commit": null }
+```
+
+Present:
+
+> `1122aab` predates agent session linking, so there is no recorded session.
+> From `git show`: it added `validateScope` to enforce per-token scopes. I can
+> show the full diff if useful.
+
+## 3. Bare path
+
+User: "Give me context on src/middleware/limit.ts."
+
+```bash
+git log -n 1 -- src/middleware/limit.ts
+```
+
+Take the SHA, run `memory_commit_lookup`, present commit plus linked session in
+the same shape as example 1.

package/integrations/omp/skills/commit-context/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: commit-context
+description: Trace a file, function, or line back to the agent session that produced its current commit. Use when the user asks "why is this code here", "what was the agent doing when this changed", "who wrote this", or wants context on a specific location in the codebase.
+argument-hint: "[file, function, or line]"
+user-invocable: true
+---
+
+The user wants commit context for: $ARGUMENTS
+
+## Quick start
+
+```bash
+git blame -L 40,52 src/auth/refresh.ts   # -> SHA 9a1b2c3d
+```
+
+```json
+memory_commit_lookup { "sha": "9a1b2c3d4e5f60718293a4b5c6d7e8f901234567" }
+```
+
+Expected output:
+
+```text
+9a1b2c3 on main by dev: "rotate refresh tokens"
+Linked session 7f3a9c2 "Auth refresh rework", 14 obs.
+```
+
+## Why
+
+Report only what git and the lookup return. When the lookup gives `commit: null`,
+the commit predates session linking; do not invent intent.
+
+## Workflow
+
+1. Find the SHA: `git blame -L <start>,<end> <file>` for a line range;
+   `git log -L :<function>:<file>` for a function; `git log -n 1 -- <file>` for a
+   bare path.
+2. Look it up: `memory_commit_lookup { "sha": "<full-sha>" }`.
+3. Present the commit (sha, short sha, branch, author, message), the linked
+   session(s) (id, project, started/ended, observation count, summary), and the
+   importance >= 7 observations via `memory_recall` when available.
+
+## Anti-patterns
+
+WRONG: lookup returns `{ "commit": null }`, you narrate "the agent was
+refactoring auth" from the diff alone.
+
+RIGHT: "This commit predates session linking, so there is no recorded agent
+session. From `git show`: it changed token rotation in refresh.ts."
+
+## Checklist
+
+- SHA came from git blame/log, not a guess.
+- `commit: null` reported as "predates linking", no fabricated session.
+- Session details quote the lookup response verbatim.
+- No intent claimed beyond what observations state.
+
+## See also
+
+- `commit-history`: list many agent-linked commits at once.
+- `recall`: dig deeper into the linked session's observations.
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if `memory_commit_lookup` is not available.

package/integrations/omp/skills/commit-context/TROUBLESHOOTING.md

@@ -0,0 +1,70 @@
+<!-- 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 -->

package/integrations/omp/skills/commit-history/EXAMPLES.md

@@ -0,0 +1,71 @@
+# commit-history worked examples
+
+## 1. Branch filter
+
+User: "Show agent commits on main."
+
+Invocation:
+
+```json
+memory_commits { "branch": "main", "limit": 100 }
+```
+
+Response:
+
+```json
+{
+  "commits": [
+    { "short": "9a1b2c3", "branch": "main", "authoredAt": "2026-06-07T09:12:00Z",
+      "message": "rotate refresh tokens", "sessionIds": ["7f3a9c21"],
+      "observationCount": 14, "files": 3 },
+    { "short": "b21d004", "branch": "main", "authoredAt": "2026-06-05T14:40:00Z",
+      "message": "rate limiter audit", "sessionIds": ["b21d004e"],
+      "observationCount": 9, "files": 1 }
+  ]
+}
+```
+
+Present:
+
+> - `9a1b2c3` main 2026-06-07 "rotate refresh tokens", session `7f3a9c2` (14 obs, 3 files)
+> - `b21d004` main 2026-06-05 "rate limiter audit", session `b21d004` (9 obs, 1 file)
+
+## 2. Bare number as limit
+
+User: "commit-history 5"
+
+Treat `5` as the limit:
+
+```json
+memory_commits { "limit": 5 }
+```
+
+Render the five newest linked commits in the same format.
+
+## 3. Empty result
+
+User: "Show agent commits on release-2.0."
+
+```json
+memory_commits { "branch": "release-2.0", "limit": 100 }
+```
+
+Response:
+
+```json
+{ "commits": [] }
+```
+
+Present:
+
+> No agent-linked commits on `release-2.0`. Drop the branch filter to see all
+> linked commits, or try a different branch.
+
+REST fallback for this same call, with encoding:
+
+```http
+GET /agentmemory/commits?branch=release-2.0&limit=100
+```
+
+Build it with `URLSearchParams` so a branch like `feat/a&b` becomes
+`feat%2Fa%26b` rather than breaking the query.