@agentmemory/agentmemory 0.9.30 → 0.9.31

package/plugin/skills/agentmemory-hooks/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/plugin/skills/agentmemory-mcp-tools/REFERENCE.md

@@ -18,7 +18,7 @@ agentmemory exposes 54 MCP tools. 8 are in the lean core set (`--tools core` or
 | `memory_consolidate` | yes | `tier`: string | Run the 4-tier memory consolidation pipeline (working -> episodic -> semantic -> procedural). |
 | `memory_crystallize` |  | `actionIds`*: string, `project`: string, `sessionId`: string | Compress completed action chains into compact crystal digests using LLM summarization. Extracts narrative, key outcomes, files affected, and lessons. |
 | `memory_diagnose` | yes | `categories`: string | Run health checks across all subsystems (actions, leases, sentinels, sketches, signals, sessions, memories, mesh). Identifies stuck, orphaned, and inconsistent state. |
-| `memory_export` |  | none | Export all memory data as JSON. |
+| `memory_export` |  | `maxSessions`: number, `offset`: number, `collectionLimit`: number, `collectionOffset`: number, `collections`: string | Export memory data as JSON. Past the transport size limit the export is refused, so use the paging arguments on a large store. |
 | `memory_facet_query` |  | `matchAll`: string, `matchAny`: string, `targetType`: string | Query targets by facet tags with AND/OR logic. Find all actions tagged priority:urgent AND team:backend. |
 | `memory_facet_tag` |  | `targetId`*: string, `targetType`*: string, `dimension`*: string, `value`*: string | Attach a structured tag (dimension:value) to an action, memory, or observation for multi-dimensional categorization. |
 | `memory_file_history` |  | `files`*: string, `sessionId`: string | Get past observations about specific files. |
@@ -36,14 +36,14 @@ agentmemory exposes 54 MCP tools. 8 are in the lean core set (`--tools core` or
 | `memory_obsidian_export` |  | `vaultDir`: string, `types`: string | Export memories, lessons, and crystals as Obsidian-compatible Markdown files with YAML frontmatter and wikilinks for graph view. |
 | `memory_patterns` |  | `project`: string, `limit`: integer | Detect recurring patterns across sessions. |
 | `memory_profile` |  | `project`*: string, `refresh`: string | User/project profile with top concepts and file patterns. |
-| `memory_recall` | yes | `query`*: string, `limit`: number, `format`: string, `token_budget`: number | Search past session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before. |
+| `memory_recall` | yes | `query`*: string, `limit`: number, `format`: string, `token_budget`: number, `targetLayer`: string, `project`: string, `cwd`: string, `agentId`: string | Search stored memories and session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before. |
 | `memory_reflect` | yes | `project`: string, `maxClusters`: number | Traverse the knowledge graph, group related memories by concept clusters, and synthesize higher-order insights via LLM. Returns new and reinforced insights. |
 | `memory_relations` |  | `memoryId`*: string, `maxHops`: number, `minConfidence`: number | Query the memory relationship graph. |
 | `memory_routine_run` |  | `routineId`*: string, `project`: string, `initiatedBy`: string | Instantiate a frozen workflow routine, creating actions for each step with proper dependencies. |
 | `memory_save` | yes | `content`*: string, `type`: string, `concepts`: string, `files`: string, `project`: string, `agentId`: string | Explicitly save an important insight, decision, or pattern to long-term memory. |
 | `memory_sentinel_create` |  | `name`*: string, `type`*: string, `config`: string, `linkedActionIds`: string, `expiresInMs`: number | Create an event-driven sentinel that watches for conditions (webhook, timer, threshold, pattern, approval) and auto-unblocks gated actions when triggered. |
 | `memory_sentinel_trigger` |  | `sentinelId`*: string, `result`: string | Externally fire a sentinel, providing an optional result payload. Unblocks any gated actions. |
-| `memory_sessions` | yes | none | List recent sessions with their status and observation counts. |
+| `memory_sessions` | yes | `project`: string, `agentId`: string, `limit`: integer, `cursor`: string | List recent sessions with status, observation counts, summaries and a continuation cursor. Filters apply before pagination; retain them when requesting the next page. |
 | `memory_signal_read` |  | `agentId`*: string, `unreadOnly`: string, `threadId`: string, `limit`: number | Read messages for an agent. Marks delivered messages as read. |
 | `memory_signal_send` |  | `from`*: string, `to`: string, `content`*: string, `type`: string, `replyTo`: string | Send a message to another agent or broadcast. Supports threading, typed messages, and TTL expiration. |
 | `memory_sketch_create` |  | `title`*: string, `description`: string, `expiresInMs`: number, `project`: string | Create an ephemeral action graph for exploratory work. Auto-expires after TTL. Can be promoted to permanent actions or discarded. |
@@ -54,7 +54,7 @@ agentmemory exposes 54 MCP tools. 8 are in the lean core set (`--tools core` or
 | `memory_slot_get` |  | `label`*: string | Read a single slot by label. |
 | `memory_slot_list` |  | none | List all memory slots (pinned + project + global). Slots are editable, size-limited memory units the agent can read and modify across sessions. |
 | `memory_slot_replace` |  | `label`*: string, `content`*: string | Replace slot content in place. Fails if content exceeds sizeLimit. |
-| `memory_smart_search` | yes | `query`*: string, `expandIds`: string, `limit`: number | Hybrid semantic+keyword search with progressive disclosure. |
+| `memory_smart_search` | yes | `query`: string, `expandIds`: string, `limit`: number, `targetLayer`: string, `project`: string, `agentId`: string, `includeLessons`: boolean | Hybrid semantic+keyword search with progressive disclosure. Pass query to search, or expandIds to recover full results. |
 | `memory_snapshot_create` |  | `message`: string | Create a git-versioned snapshot of current memory state. |
 | `memory_team_feed` |  | `limit`: number | Get recent shared items from all team members. |
 | `memory_team_share` |  | `itemId`*: string, `itemType`*: string | Share a memory or observation with team members. |

package/plugin/skills/agentmemory-mcp-tools/SKILL.md

@@ -4,18 +4,18 @@ description: Map of every agentmemory MCP tool, what each does, and its paramete
 user-invocable: false
 ---
 
-agentmemory exposes its full capability set as MCP tools. This skill is the index: it tells you which tool to reach for and where to find exact parameters.
+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` and `limit` to retrieve it later. This runs hybrid BM25 plus vector plus graph-expanded search.
+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_observe` flows, `memory_compress_file`.
+- 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`.
@@ -27,6 +27,9 @@ Save then recall:
 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
 

package/plugin/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/plugin/skills/agentmemory-rest-api/REFERENCE.md

@@ -5,7 +5,7 @@ Generated from `src/triggers/api.ts`. Do not edit the block below by hand; run `
 <!-- 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`.
 
-138 registered endpoints:
+146 registered endpoints:
 
 | Method | Path |
 | --- | --- |
@@ -30,11 +30,14 @@ The REST API is the primary surface. All paths are under `http://localhost:3111`
 | 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` |
@@ -61,6 +64,9 @@ The REST API is the primary surface. All paths are under `http://localhost:3111`
 | 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` |
@@ -145,6 +151,8 @@ The REST API is the primary surface. All paths are under `http://localhost:3111`
 | 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/plugin/skills/agentmemory-rest-api/SKILL.md

@@ -12,31 +12,37 @@ REST is agentmemory's primary surface. MCP is a bridge on top of it. Every memor
 # 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 -X POST http://localhost:3111/agentmemory/remember \
+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 -X POST http://localhost:3111/agentmemory/smart-search \
+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
 
-By default localhost is open and no auth is needed. When `AGENTMEMORY_SECRET` is set, every request needs `Authorization: Bearer $AGENTMEMORY_SECRET`. See agentmemory-config.
+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`.
-- Handlers whitelist body fields and drop unknown ones, so passing extra keys is safe but ignored.
-- The port is configurable with `--port` or `--instance`; streams, viewer, and engine derive from it.
+- 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 the port quartet and the secret.
+- agentmemory-config for local configuration and the secret.
 
 ## Reference
 

package/plugin/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/plugin/skills/commit-context/SKILL.md

@@ -61,4 +61,4 @@ session. From `git show`: it changed token rotation in refresh.ts."
 
 ## Troubleshooting
 
-See ../_shared/TROUBLESHOOTING.md if `memory_commit_lookup` is not available.
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if `memory_commit_lookup` is not available.

package/plugin/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/plugin/skills/commit-history/SKILL.md

@@ -59,4 +59,4 @@ appending to `GET /agentmemory/commits`.
 
 ## Troubleshooting
 
-See ../_shared/TROUBLESHOOTING.md if `memory_commits` is not available.
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if `memory_commits` is not available.

package/plugin/skills/commit-history/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/plugin/skills/forget/EXAMPLES.md

@@ -1,75 +1,40 @@
 # forget worked examples
 
-## 1. Delete a leaked secret
+## Delete a selected durable memory
 
 User: "Forget that note where I pasted the API key."
 
-Search:
-
-```json
-memory_smart_search { "query": "api key", "limit": 20 }
-```
-
-Response:
-
 ```json
-{
-  "results": [
-    { "id": "abc12345", "sessionId": "7f3a9c21", "title": "Pasted staging API key",
-      "narrative": "STAGING_KEY=sk-live-..." }
-  ]
-}
+memory_smart_search { "query": "api key", "targetLayer": "memory", "project": "app", "limit": 20 }
 ```
 
-Present and gate:
+Show the returned memory ID and title without displaying the secret value:
 
-> Found 1 match:
-> - `abc12345` (session `7f3a9c2`) "Pasted staging API key"
->
-> Delete this memory? (yes/no)
+> Found memory `abc12345` in project `app`: "Staging API configuration".
+> Delete this memory?
 
-After the user says yes:
+After explicit confirmation:
 
 ```json
-memory_governance_delete { "memoryIds": ["abc12345"], "reason": "user privacy request" }
+memory_governance_delete { "memoryIds": "abc12345", "reason": "user privacy request" }
 ```
 
-Response:
-
-```json
-{ "deleted": 1 }
-```
-
-Present:
-
-> Deleted 1 memory (`abc12345`).
+If the response reports `deleted: 1`, report one deletion. If it reports
+`deleted: 0` and `notFound: ["abc12345"]`, report that the memory was not found.
+For mixed results, state the actual count and any failed or missing IDs.
 
-## 2. Drop a whole session's observations
+## A request to erase a whole session
 
 User: "Delete everything from the throwaway spike session."
 
-Search, identify the session, then collect every memory id in it:
-
-```json
-memory_smart_search { "query": "spike prototype throwaway", "limit": 20 }
-```
-
-Response has 4 results all with `sessionId: c98f1100`. Show all four, get a yes,
-then pass every id:
-
-```json
-memory_governance_delete {
-  "memoryIds": ["m1", "m2", "m3", "m4"],
-  "reason": "drop throwaway spike session"
-}
-```
-
-Never send `{ "sessionId": "c98f1100" }`; the MCP deletes by memory id only.
-
-## 3. User declines
+Explain that this tool deletes selected durable memories only. A relevance
+search limited to 20 results cannot enumerate all session data, and observation
+IDs are not accepted as durable-memory IDs. Do not claim complete erasure.
+Offer a review of matching durable memories with the scope clearly stated.
+Lessons have a separate `memory_lesson_delete` operation.
 
-User: "Actually, on second thought, keep them."
+## User declines
 
-Do not call delete. Confirm:
+User: "Actually, keep them."
 
-> Understood, nothing deleted. The 4 memories from session `c98f110` are intact.
+Do not call delete. Report that nothing was deleted.