@agentmemory/agentmemory 0.9.29 → 0.9.31

package/plugin/skills/agentmemory-hooks/SKILL.md

@@ -4,18 +4,28 @@ description: The agentmemory plugin hooks that capture observations automaticall
 user-invocable: false
 ---
 
-The Claude Code plugin registers lifecycle hooks so memory is captured automatically. You do not have to call `memory_save` for routine work; the hooks observe tool use, prompts, and session boundaries and write observations for you.
+The agentmemory plugin registers lifecycle hooks so memory is captured automatically. You do not have to call `memory_save` for routine work; the hooks observe tool use, prompts, and session boundaries and write observations for you.
 
 ## Quick start
 
-Install the plugin and the hooks register themselves:
+For Claude Code, install its plugin:
 
 ```bash
 /plugin marketplace add rohitg00/agentmemory
 /plugin install agentmemory
 ```
 
-Watch observations land live at `http://localhost:3113`.
+For Devin CLI and Devin Desktop, install the plugin and start a new session:
+
+```bash
+devin plugins install rohitg00/agentmemory#plugin
+```
+
+Run `/hooks` inside Devin to confirm the agentmemory hooks are loaded. Plugin hooks run only in local Devin sessions, not in cloud sessions.
+
+Pi and OMP install native recall and capture with `agentmemory connect pi --with-mcp` or `agentmemory connect omp --with-mcp`. Reload Pi or restart OMP, then inspect `/agentmemory-status`. DSH requires `agentmemory connect dsh --with-hooks` and a restart. Cursor lifecycle hooks come from its enabled plugin, separately from `connect cursor`'s MCP setup.
+
+Hermes and OpenClaw use their native integrations and lifecycle contracts. Follow the matching integration setup instructions and verify a real turn creates an observation. Installing shared skills or connecting MCP alone does not enable automatic capture. Watch recorded observations in the viewer at `http://localhost:3113` when using the default port. A pending capture queue is not proof that the daemon stored the event.
 
 ## What the hooks do
 
@@ -26,8 +36,8 @@ Watch observations land live at `http://localhost:3113`.
 
 ## Important
 
-- Capture is on by default and is zero-LLM. Turning observations into LLM summaries (`AGENTMEMORY_AUTO_COMPRESS`) and injecting them back into context (`AGENTMEMORY_INJECT_CONTEXT`) are separate opt-ins because they spend tokens.
-- If observations are missing, confirm the plugin is enabled and the server is running. See ../_shared/TROUBLESHOOTING.md.
+- The plugin hooks capture by default without an LLM. Per-observation LLM compression (`AGENTMEMORY_AUTO_COMPRESS`) and hook context injection (`AGENTMEMORY_INJECT_CONTEXT`) are separate options. Session summaries can use a configured LLM provider independently of automatic observation compression. Native integrations have their own recall/capture settings; inspect the host configuration instead of assuming these flags control every plugin.
+- If observations are missing, confirm the plugin is enabled and the server is running. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
 
 ## See also
 

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. |
@@ -34,16 +34,16 @@ agentmemory exposes 54 MCP tools. 8 are in the lean core set (`--tools core` or
 | `memory_mesh_sync` |  | `peerId`: string, `direction`: string | Sync memories and actions with peer agentmemory instances for multi-agent collaboration. |
 | `memory_next` |  | `project`: string, `agentId`: string | Get the single most important next action to work on. Combines dependency resolution, priority, and recency into a score. |
 | `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 | Detect recurring patterns across sessions. |
+| `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

@@ -3,9 +3,9 @@
 Generated from `src/triggers/api.ts`. Do not edit the block below by hand; run `npm run skills:gen` after changing the registered endpoints.
 
 <!-- AUTOGEN:rest START - generated by scripts/skills/generate.ts, do not edit by hand -->
-The REST API is the primary surface. All paths are under `http://localhost:3111` (override with `--port`). When `AGENTMEMORY_SECRET` is set, send `Authorization: Bearer $AGENTMEMORY_SECRET`; localhost is otherwise open.
+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`.
 
-130 registered endpoints:
+146 registered endpoints:
 
 | Method | Path |
 | --- | --- |
@@ -19,6 +19,9 @@ The REST API is the primary surface. All paths are under `http://localhost:3111`
 | GET | `/agentmemory/branch/detect` |
 | GET | `/agentmemory/branch/sessions` |
 | GET | `/agentmemory/branch/worktrees` |
+| GET | `/agentmemory/capture` |
+| POST | `/agentmemory/capture/drain` |
+| POST | `/agentmemory/capture/retry` |
 | POST | `/agentmemory/cascade-update` |
 | GET | `/agentmemory/checkpoints` |
 | POST | `/agentmemory/checkpoints` |
@@ -27,10 +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` |
@@ -54,8 +61,13 @@ The REST API is the primary surface. All paths are under `http://localhost:3111`
 | POST | `/agentmemory/governance/bulk-delete` |
 | DELETE | `/agentmemory/governance/memories` |
 | POST | `/agentmemory/graph/build` |
+| POST | `/agentmemory/graph/compact` |
 | POST | `/agentmemory/graph/extract` |
 | POST | `/agentmemory/graph/import-graphify` |
+| GET | `/agentmemory/graph/index` |
+| POST | `/agentmemory/graph/index/migrate` |
+| POST | `/agentmemory/graph/index/resume` |
+| GET | `/agentmemory/graph/node` |
 | POST | `/agentmemory/graph/query` |
 | POST | `/agentmemory/graph/reset` |
 | POST | `/agentmemory/graph/snapshot-rebuild` |
@@ -83,6 +95,7 @@ The REST API is the primary surface. All paths are under `http://localhost:3111`
 | POST | `/agentmemory/migrate` |
 | GET | `/agentmemory/next` |
 | GET | `/agentmemory/observations` |
+| GET | `/agentmemory/observations/locate` |
 | POST | `/agentmemory/observe` |
 | POST | `/agentmemory/obsidian/export` |
 | POST | `/agentmemory/patterns` |
@@ -130,6 +143,7 @@ The REST API is the primary surface. All paths are under `http://localhost:3111`
 | POST | `/agentmemory/snapshot/create` |
 | POST | `/agentmemory/snapshot/restore` |
 | GET | `/agentmemory/snapshots` |
+| GET | `/agentmemory/status` |
 | POST | `/agentmemory/summarize` |
 | GET | `/agentmemory/team/feed` |
 | GET | `/agentmemory/team/profile` |
@@ -137,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 -->