@agentmemory/agentmemory 0.9.30 → 0.9.32

package/plugin/skills/handoff/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/lesson/SKILL.md

@@ -61,4 +61,4 @@ RIGHT: `content: "Run vitest with --run in CI; watch mode hangs the pipeline."`
 
 ## Troubleshooting
 
-See ../_shared/TROUBLESHOOTING.md if `memory_lesson_save` is not available.
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if `memory_lesson_save` is not available.

package/plugin/skills/lesson/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/memory-discipline/SKILL.md

@@ -62,4 +62,4 @@ RIGHT: search first, save each decision as it settles, let hooks own the summary
 
 ## Troubleshooting
 
-See ../_shared/TROUBLESHOOTING.md if `memory_smart_search` or `memory_save` is not available.
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if `memory_smart_search` or `memory_save` is not available.

package/plugin/skills/memory-discipline/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/recall/SKILL.md

@@ -29,13 +29,24 @@ id, or an importance score. If nothing comes back, say so.
 ## Workflow
 
 1. Call `memory_smart_search` with the user's text as `query` and `limit: 10`.
-   Pass `project` when the user scopes to a specific repo.
-2. Group results by session. Records carry a provenance channel (`user`, `agent`,
-   `tool`, `import`, `shared`); when results conflict, prefer `user` over `agent`
-   inference, and flag `shared` records as another teammate's write.
-3. For each observation show its type, title, and narrative.
+   Pass `project` when the user scopes to a specific repo and `agentId` when
+   they request one agent's history.
+   Use `targetLayer: "memory"` for explicitly saved knowledge, or
+   `targetLayer: "observation"` for captured activity. Omit it for mixed search.
+2. Search results are compact. Before quoting full content or describing
+   provenance, call `memory_smart_search` with the selected IDs as a
+   comma-separated `expandIds` string and the same project, agent, and layer
+   filters. If expansion fails or the record is no longer available, report
+   that limitation; a title alone is not the full fact.
+3. Group expanded observations by session and show the returned type, title,
+   and narrative. Include provenance only when the response supplies it.
 4. Lead with the high-signal observations (importance >= 7).
-5. If zero results, suggest 2-3 alternative search terms and stop. Do not guess.
+5. With `memory_recall`, inspect `matched_count`, `excluded_by_budget`, and
+   `content_truncated` before treating an empty or shortened response as absent
+   knowledge. Recover full content with `memory_smart_search` using `expandIds`
+   and the same project, agent, and layer filters. `minimum_budget` reports the
+   estimated budget needed for a minimal preview when the budget is too small.
+6. If there are no matches, suggest 2-3 alternative search terms and stop. Do not guess.
 
 ## Anti-patterns
 
@@ -60,4 +71,4 @@ or `auth rotation`."
 
 ## Troubleshooting
 
-See ../_shared/TROUBLESHOOTING.md if `memory_smart_search` is not available.
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if `memory_smart_search` is not available.

package/plugin/skills/recall/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/recap/EXAMPLES.md

@@ -7,7 +7,7 @@ User: "Recap this week."
 Window: last 7 days. Invocation:
 
 ```json
-memory_sessions { "limit": 30 }
+memory_sessions { "project": "app", "limit": 30 }
 ```
 
 Response (after filtering to cwd and the 7-day window):
@@ -28,7 +28,7 @@ Response (after filtering to cwd and the 7-day window):
 Per session, pull highlights:
 
 ```json
-memory_recall { "query": "jwt-refresh-rotation auth-flow", "limit": 3 }
+memory_recall { "query": "jwt-refresh-rotation auth-flow", "project": "app", "limit": 3 }
 ```
 
 Present:
@@ -47,7 +47,9 @@ Present:
 
 User: "recap 3"
 
-Treat as `last 3`. Call `memory_sessions { "limit": 3 }`, group by date, same format.
+Treat as `last 3`. Call `memory_sessions { "project": "app", "limit": 3 }`
+using the recorded project identifier, then group by date. If the identifier is
+unknown, page through results and filter by directory before selecting three.
 
 ## 3. Empty window
 

package/plugin/skills/recap/SKILL.md

@@ -10,10 +10,11 @@ The user wants a recap. Time window args: $ARGUMENTS
 ## Quick start
 
 ```json
-memory_sessions { "limit": 30 }
+memory_sessions { "project": "<current-project-id>", "limit": 30 }
 ```
 
-Then per surviving session: `memory_recall { "query": "<top concepts>", "limit": 3 }`.
+Then per surviving session: `memory_recall { "query": "<top concepts>", "project": "<current-project-id>", "limit": 3 }`.
+When an agent is requested, pass the same `agentId` to both calls.
 
 Expected output:
 
@@ -33,11 +34,15 @@ a real answer, not a prompt to invent activity.
 
 1. Parse `$ARGUMENTS`: `today` = current local date; `this week` = last 7 days;
    `last <n>` or bare numeric = most recent N; empty = `last 10`.
-2. Call `memory_sessions`, filter to the current project (match `cwd` against the
-   working directory), apply the window, sort by `startedAt` descending.
+2. Call `memory_sessions` with the exact recorded project identifier when known
+   and the requested `agentId`. Follow `nextCursor` with the same filters until
+   the requested window is covered or pages end. When the project identifier is
+   unknown, match normalized `cwd` by directory boundary across pages before
+   applying the time/count window. Sort by `startedAt` descending.
 3. Group survivors by local calendar date (YYYY-MM-DD).
 4. Per session list id (first 8), title or first prompt, observation count,
-   status. Indent 2-3 highlights (importance >= 7) from `memory_recall`.
+   status. Obtain highlights with `memory_recall`, retaining project/agent scope,
+   and verify each result belongs to that session before including it.
 5. End with "N sessions across M days, K observations."
 
 ## Anti-patterns
@@ -60,4 +65,4 @@ RIGHT: "No sessions in the last 7 days for this project."
 
 ## Troubleshooting
 
-See ../_shared/TROUBLESHOOTING.md if `memory_sessions` or `memory_recall` is not available.
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if `memory_sessions` or `memory_recall` is not available.

package/plugin/skills/recap/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/remember/EXAMPLES.md

@@ -9,7 +9,7 @@ Invocation:
 ```json
 memory_save {
   "content": "We decided to drop Redis and use the iii-engine state store for session caching to remove a moving part.",
-  "concepts": "session-caching, iii-state-store, dropped-redis",
+  "concepts": "session-caching, state-worker-store, dropped-redis",
   "files": ""
 }
 ```
@@ -17,12 +17,12 @@ memory_save {
 Response:
 
 ```json
-{ "id": "7f3a9c21", "concepts": ["session-caching", "iii-state-store", "dropped-redis"], "saved": true }
+{ "id": "7f3a9c21", "concepts": ["session-caching", "state-worker-store", "dropped-redis"], "saved": true }
 ```
 
 Present:
 
-> Saved. Tagged it `session-caching`, `iii-state-store`, `dropped-redis`, so a
+> Saved. Tagged it `session-caching`, `state-worker-store`, `dropped-redis`, so a
 > later recall on caching or Redis will surface this decision.
 
 ## 2. Saving a code-specific gotcha

package/plugin/skills/remember/SKILL.md

@@ -63,4 +63,4 @@ RIGHT: `concepts: "jwt-refresh-rotation, token-revocation"` (specific, retrievab
 
 ## Troubleshooting
 
-See ../_shared/TROUBLESHOOTING.md if `memory_save` is not available.
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if `memory_save` is not available.

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

@@ -7,7 +7,7 @@ User: "Show me the session history."
 Invocation:
 
 ```json
-memory_sessions { "limit": 20 }
+memory_sessions { "project": "app", "limit": 20 }
 ```
 
 Response:
@@ -44,7 +44,7 @@ If a returned session has `observationCount: 0`, list it but say so:
 User: "What did we do last time?"
 
 ```json
-memory_sessions { "limit": 20 }
+memory_sessions { "project": "app", "limit": 20 }
 ```
 
 Response:

package/plugin/skills/session-history/SKILL.md

@@ -9,7 +9,7 @@ The user wants an overview of recent sessions on this project.
 ## Quick start
 
 ```json
-memory_sessions { "limit": 20 }
+memory_sessions { "project": "<current-project-id>", "limit": 20 }
 ```
 
 Expected output:
@@ -28,8 +28,13 @@ real answer, never a cue to invent past work.
 
 ## Workflow
 
-1. Call `memory_sessions` with `limit: 20` for a meaningful window.
-2. Present in reverse chronological order: session id (first 8), project, start
+1. Use the exact project identifier recorded by the host and pass it to
+   `memory_sessions`, with `agentId` when requested. If it is unknown, page
+   through sessions using `nextCursor` and match normalized `cwd` by directory
+   boundary before choosing the most recent 20. Never substitute another project.
+2. Preserve scope filters on every page; stop at the requested count or a null
+   `nextCursor`. State when the displayed history is a partial page. Present in
+   reverse chronological order: session id (first 8), project, start
    time, status.
 3. For sessions with observations, show the key highlights (type plus title).
 4. Note the total observation count per session.
@@ -46,6 +51,7 @@ observation count.
 ## Checklist
 
 - Every session shown came from the tool response.
+- Project/directory scope was checked before selecting the displayed window.
 - Order is reverse-chronological.
 - Per-session observation counts match the response.
 - No session or highlight was invented or merged.
@@ -58,4 +64,4 @@ observation count.
 
 ## Troubleshooting
 
-See ../_shared/TROUBLESHOOTING.md if `memory_sessions` is not available.
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if `memory_sessions` is not available.