@agentmemory/agentmemory 0.9.30 → 0.9.31

package/plugin/skills/forget/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: forget
-description: Delete specific observations from agentmemory after showing them and getting explicit confirmation. Use when the user says "forget this", "delete memory", "remove that note", or wants to scrub specific data for privacy.
+description: Delete selected durable memories from agentmemory after showing them and getting explicit confirmation. Use when the user says "forget this", "delete memory", "remove that note", or wants to scrub specific data for privacy.
 argument-hint: "[what to forget - session ID, file path, or search term]"
 user-invocable: true
 ---
@@ -10,13 +10,13 @@ The user wants to remove data from agentmemory: $ARGUMENTS
 ## Quick start
 
 ```json
-memory_smart_search { "query": "old api key in config", "limit": 20 }
+memory_smart_search { "query": "old api key in config", "targetLayer": "memory", "limit": 20 }
 ```
 
 Show the matches, get a yes, then:
 
 ```json
-memory_governance_delete { "memoryIds": ["abc12345", "def67890"], "reason": "user privacy request" }
+memory_governance_delete { "memoryIds": "abc12345,def67890", "reason": "user privacy request" }
 ```
 
 Expected output:
@@ -32,17 +32,21 @@ an explicit yes before calling delete. Delete by memory ID, never a bare session
 
 ## Workflow
 
-1. Search with `memory_smart_search`, the user's text as `query`, `limit: 20`.
-2. Show what matched: session ids, memory ids, titles. Ask for explicit
+1. Search with `memory_smart_search`, the user's text as `query`,
+   `targetLayer: "memory"`, `limit: 20`, and the requested project/agent scope.
+   These are selected relevance matches, not an exhaustive inventory.
+2. Show what matched: memory ids, titles, and scope. Redact secret values. Ask for explicit
    confirmation. Do not proceed on silence or a vague "sure, whatever".
-3. On confirmation, call `memory_governance_delete` with `memoryIds` (array or
-   comma-separated string) and optional `reason` (default `plugin skill request`).
-4. To drop a whole session, collect every memory id in that session from the
-   search results and pass them all. The MCP does not accept a bare `sessionId`.
+3. On confirmation, call `memory_governance_delete` with `memoryIds` as a
+   comma-separated string and optional `reason` (default `plugin skill request`).
+4. Observation or whole-session erasure is not supported by this operation.
+   Explain that limit before proceeding; never label selected memory deletion
+   as a complete session wipe. Do not pass observation IDs or a `sessionId`.
 5. Lessons are separate: delete one with `memory_lesson_delete` and its
    `lessonId`; `memory_governance_delete` does not touch lessons.
-6. Report the deletion count back. A count of 0 means the ids did not exist;
-   say so instead of claiming a delete.
+6. Check `deleted`, `notFound`, and `failed` in the response. Report actual
+   deletions and unresolved IDs separately. Recheck the selected IDs before
+   retrying a failed request; an interrupted response may hide a completed write.
 
 ## Anti-patterns
 
@@ -66,4 +70,4 @@ an explicit yes.
 
 ## Troubleshooting
 
-See ../_shared/TROUBLESHOOTING.md if `memory_smart_search` or `memory_governance_delete` is not available.
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if `memory_smart_search` or `memory_governance_delete` is not available.

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

@@ -7,7 +7,7 @@ User: "Where were we?"
 Project cwd: `/Users/dev/app`. Invocation:
 
 ```json
-memory_sessions { "limit": 20 }
+memory_sessions { "project": "app", "limit": 20 }
 ```
 
 Response:
@@ -26,7 +26,7 @@ Response:
 Pull supporting context:
 
 ```json
-memory_recall { "query": "jwt-refresh-rotation logout", "limit": 10 }
+memory_recall { "query": "jwt-refresh-rotation logout", "project": "app", "limit": 10 }
 ```
 
 Present:
@@ -43,8 +43,9 @@ Project cwd: `/Users/dev/repo-a`. Sessions include one with `cwd:
 
 A raw prefix would match `repo-a-staging`. The boundary check rejects it because
 `/Users/dev/repo-a-staging` does not equal `/Users/dev/repo-a` and does not start
-with `/Users/dev/repo-a/`. Pick the real `repo-a` session instead, or fall back
-to the most recent session overall if none matches.
+with `/Users/dev/repo-a/`. Continue through `nextCursor` when another page is
+available. If no matching session exists, report that this project has no
+recorded session; do not substitute the most recent session from another repo.
 
 ## 3. Empty session
 

package/plugin/skills/handoff/SKILL.md

@@ -10,11 +10,12 @@ The user wants to resume work. Optional cwd override: $ARGUMENTS
 ## Quick start
 
 ```json
-memory_sessions { "limit": 20 }
+memory_sessions { "project": "<current-project-id>", "limit": 20 }
 ```
 
 Pick the most recent session whose `cwd` matches this project, then:
-`memory_recall { "query": "<session top concepts>", "limit": 10 }`.
+`memory_recall { "query": "<session top concepts>", "project": "<current-project-id>", "limit": 10 }`.
+When an agent is requested, pass the same `agentId` to both calls.
 
 Expected output:
 
@@ -33,7 +34,10 @@ gets mistaken for this one. Never invent observations for an empty session.
 
 1. Resolve the project path: if `$ARGUMENTS` is given, normalize it to absolute
    (`path.resolve(process.cwd(), $ARGUMENTS)`); else use the cwd.
-2. Call `memory_sessions`. Pick the most recent session whose normalized `cwd`
+2. Call `memory_sessions` with the exact project identifier when known, and
+   `agentId` when requested. Otherwise follow `nextCursor` until the matching
+   directory is found or pagination ends. Preserve filters between pages.
+   Pick the most recent session whose normalized `cwd`
    matches by directory boundary: equality, OR `cwd.startsWith(projectPath + sep)`,
    OR `projectPath.startsWith(cwd + sep)`. Prefer `completed` over `abandoned`.
    No match: report that this project has no matching session and stop. Do not
@@ -42,7 +46,8 @@ gets mistaken for this one. Never invent observations for an empty session.
    Look in `summary` or recent `conversation` observations whose `narrative`
    ends in `?`.
 4. Summarize: title/summary, key files, key decisions or errors, using
-   `memory_recall` on the top concepts, limit 10. Check each result's session or
+   `memory_recall` on the top concepts, limit 10, preserving the chosen project
+   and agent scope. Check each result's session or
    project provenance before including it; a query alone does not enforce scope.
 5. End with one concrete "next step?" pointer.
 
@@ -67,4 +72,4 @@ a directory-boundary check that cannot cross sibling repos.
 
 ## 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/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.