@agentmemory/agentmemory 0.9.27 → 0.9.28

package/plugin/skills/forget/EXAMPLES.md

@@ -0,0 +1,75 @@
+# forget worked examples
+
+## 1. Delete a leaked secret
+
+User: "Forget that note where I pasted the API key."
+
+Search:
+
+```json
+memory_smart_search { "query": "api key", "limit": 20 }
+```
+
+Response:
+
+```json
+{
+  "results": [
+    { "id": "abc12345", "sessionId": "7f3a9c21", "title": "Pasted staging API key",
+      "narrative": "STAGING_KEY=sk-live-..." }
+  ]
+}
+```
+
+Present and gate:
+
+> Found 1 match:
+> - `abc12345` (session `7f3a9c2`) "Pasted staging API key"
+>
+> Delete this memory? (yes/no)
+
+After the user says yes:
+
+```json
+memory_governance_delete { "memoryIds": ["abc12345"], "reason": "user privacy request" }
+```
+
+Response:
+
+```json
+{ "deleted": 1 }
+```
+
+Present:
+
+> Deleted 1 memory (`abc12345`).
+
+## 2. Drop a whole session's observations
+
+User: "Delete everything from the throwaway spike session."
+
+Search, identify the session, then collect every memory id in it:
+
+```json
+memory_smart_search { "query": "spike prototype throwaway", "limit": 20 }
+```
+
+Response has 4 results all with `sessionId: c98f1100`. Show all four, get a yes,
+then pass every id:
+
+```json
+memory_governance_delete {
+  "memoryIds": ["m1", "m2", "m3", "m4"],
+  "reason": "drop throwaway spike session"
+}
+```
+
+Never send `{ "sessionId": "c98f1100" }`; the MCP deletes by memory id only.
+
+## 3. User declines
+
+User: "Actually, on second thought, keep them."
+
+Do not call delete. Confirm:
+
+> Understood, nothing deleted. The 4 memories from session `c98f110` are intact.

package/plugin/skills/forget/SKILL.md

@@ -1,26 +1,66 @@
 ---
 name: forget
-description: Delete specific observations or sessions from agentmemory. Use when user says "forget this", "delete memory", or wants to remove specific data for privacy.
+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.
 argument-hint: "[what to forget - session ID, file path, or search term]"
 user-invocable: true
 ---
 
 The user wants to remove data from agentmemory: $ARGUMENTS
 
-**IMPORTANT**: This is a destructive operation. Always confirm with the user before deleting.
+## Quick start
 
-Steps:
+```json
+memory_smart_search { "query": "old api key in config", "limit": 20 }
+```
 
-1. First search for matching observations with the `memory_smart_search` MCP tool (provided by the agentmemory server this plugin wires up via `.mcp.json`). Use the user's input as the `query` with `limit: 20`.
-2. Show the user what was found — session IDs, observation IDs, titles — and ask for explicit confirmation before deleting.
-3. Once confirmed, call `memory_governance_delete` with:
-   - `memoryIds: [<id>, ...]` — an array (or comma-separated string) of the memory IDs returned by the search in step 1
-   - `reason: "<short reason>"` — optional, defaults to `"plugin skill request"`
+Show the matches, get a yes, then:
 
-   If the user wants to drop an entire session's observations, collect every memory ID in that session from the search results and pass them all via `memoryIds`. The standalone MCP doesn't accept a bare `sessionId` argument — it deletes by memory ID only.
-4. Confirm the deletion count back to the user.
+```json
+memory_governance_delete { "memoryIds": ["abc12345", "def67890"], "reason": "user privacy request" }
+```
 
-**Never delete without explicit user confirmation.** If the MCP tools aren't available, the stdio MCP shim didn't start — tell the user to:
-1. Run `/plugin list` in Claude Code and confirm `agentmemory` shows as enabled.
-2. Restart Claude Code (the plugin's `.mcp.json` is only read on startup).
-3. Check `/mcp` to see whether the `agentmemory` MCP server is connected.
+Expected output:
+
+```text
+Found 2 matching memories. Confirmed. Deleted 2 memories.
+```
+
+## Why
+
+This is destructive and irreversible. Show exactly what will be deleted and get
+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
+   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`.
+5. Report the deletion count back.
+
+## Anti-patterns
+
+WRONG: search returns matches, you immediately call `memory_governance_delete`
+without showing them or waiting for a yes.
+
+RIGHT: list the matches, ask "Delete these 2? (yes/no)", and only delete after
+an explicit yes.
+
+## Checklist
+
+- Matches were shown to the user before any delete.
+- An explicit yes was received, not assumed.
+- `memoryIds` holds real ids from the search, never a bare `sessionId`.
+- Final message states the actual count deleted.
+
+## See also
+
+- `remember`: the write side; forget is its undo.
+- `recall`: find the exact memory id before deleting.
+
+## Troubleshooting
+
+See ../_shared/TROUBLESHOOTING.md if `memory_smart_search` or `memory_governance_delete` is not available.

package/plugin/skills/handoff/EXAMPLES.md

@@ -0,0 +1,56 @@
+# handoff worked examples
+
+## 1. Resume with an open question
+
+User: "Where were we?"
+
+Project cwd: `/Users/dev/app`. Invocation:
+
+```json
+memory_sessions { "limit": 20 }
+```
+
+Response:
+
+```json
+{
+  "sessions": [
+    { "id": "7f3a9c21", "cwd": "/Users/dev/app", "title": "Auth refresh rework",
+      "status": "completed", "startedAt": "2026-06-07T09:00:00Z",
+      "summary": "Reworked refresh rotation. Open: should logout revoke all device tokens?",
+      "concepts": ["jwt-refresh-rotation", "logout"] }
+  ]
+}
+```
+
+Pull supporting context:
+
+```json
+memory_recall { "query": "jwt-refresh-rotation logout", "limit": 10 }
+```
+
+Present:
+
+> Resuming `7f3a9c2` "Auth refresh rework".
+> **Open question:** should logout revoke all device tokens or just the current one?
+> Touched `auth/refresh.ts`, `auth/logout.ts`. Refresh rotation is done.
+> **Next step:** decide the revoke scope, then finish `auth/logout.ts`.
+
+## 2. Sibling-repo guard
+
+Project cwd: `/Users/dev/repo-a`. Sessions include one with `cwd:
+/Users/dev/repo-a-staging`.
+
+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.
+
+## 3. Empty session
+
+User: "Resume."
+
+If the matched session has zero observations:
+
+> The most recent session `c98f110` for this project has no recorded
+> observations. Nothing to hand off. Want to start fresh from the current state?

package/plugin/skills/handoff/SKILL.md

@@ -1,21 +1,68 @@
 ---
 name: handoff
-description: Resume the most recent agent session for the current working directory. Use when the user says "where were we", "resume", "handoff", "pick up where I left off", or starts a session with no fresh context.
+description: Resume the most recent agent session for the current working directory, leading with any unanswered question. Use when the user says "where were we", "resume", "handoff", "pick up where I left off", or starts a session with no fresh context.
 argument-hint: "[optional cwd override]"
 user-invocable: true
 ---
 
 The user wants to resume work. Optional cwd override: $ARGUMENTS
 
-Determine the current project path: if `$ARGUMENTS` is provided, resolve it to an absolute, normalized path (accept relative inputs, e.g. `path.resolve(process.cwd(), $ARGUMENTS)`); otherwise use the current working directory.
+## Quick start
 
-Call the `memory_sessions` MCP tool. From the result, pick the most recent session whose normalized `cwd` matches the project path with a directory-boundary check — equality OR `session.cwd.startsWith(projectPath + path.sep)` OR `projectPath.startsWith(session.cwd + path.sep)`. Do NOT use a raw string prefix match: it produces false positives across unrelated repos that share a path prefix (e.g. `/repo-a` vs `/repo-a-staging`). Prefer sessions with status `completed` over `abandoned`. If nothing matches, fall back to the single most recent session overall.
+```json
+memory_sessions { "limit": 20 }
+```
 
-Once a session is selected:
-1. If the session ended on an unanswered user-facing question, surface that question FIRST as the lead. Look for it in `summary` or in the last few observations (type `conversation` with `narrative` ending in `?`).
-2. Then summarize the session: title/summary, key files touched, key decisions or errors. Use `memory_recall` with a query derived from the session's top concepts to fetch supporting observations, limit 10.
-3. End with a short "next step?" pointer the user can act on.
+Pick the most recent session whose `cwd` matches this project, then:
+`memory_recall { "query": "<session top concepts>", "limit": 10 }`.
 
-If neither MCP tool is available, fall back to HTTP: `GET $AGENTMEMORY_URL/agentmemory/sessions` and `POST $AGENTMEMORY_URL/agentmemory/recall` with `Authorization: Bearer $AGENTMEMORY_SECRET` when set.
+Expected output:
 
-Do not invent observations. If the most recent session has zero observations, say so and offer to start fresh.
+```text
+Resuming 7f3a9c2 "Auth refresh rework".
+Open question: should logout revoke all device tokens or just the current one?
+Next step: decide revoke scope, then update auth/logout.ts.
+```
+
+## Why
+
+Match the session by directory boundary, not raw prefix, so a sibling repo never
+gets mistaken for this one. Never invent observations for an empty session.
+
+## Workflow
+
+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`
+   matches by directory boundary: equality, OR `cwd.startsWith(projectPath + sep)`,
+   OR `projectPath.startsWith(cwd + sep)`. Prefer `completed` over `abandoned`.
+   No match: fall back to the single most recent session overall.
+3. If the session ended on an unanswered user-facing question, surface it FIRST.
+   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.
+5. End with one concrete "next step?" pointer.
+
+## Anti-patterns
+
+WRONG: `session.cwd.startsWith(projectPath)` matches `/repo-a-staging` when the
+project is `/repo-a`, resuming the wrong repo's session.
+
+RIGHT: `session.cwd === projectPath || session.cwd.startsWith(projectPath + sep)`,
+a directory-boundary check that cannot cross sibling repos.
+
+## Checklist
+
+- cwd override resolved to an absolute, normalized path.
+- Match used a directory-boundary check, not a raw prefix.
+- Unanswered question (if any) leads the response.
+- Empty session is reported plainly, with an offer to start fresh.
+
+## See also
+
+- `recap`, `session-history`, `recall`: same session data, broader views.
+
+## Troubleshooting
+
+See ../_shared/TROUBLESHOOTING.md if `memory_sessions` or `memory_recall` is not available.

package/plugin/skills/recall/EXAMPLES.md

@@ -0,0 +1,74 @@
+# recall worked examples
+
+## 1. Hit on a past decision
+
+User: "Did we ever decide how to cache sessions?"
+
+Invocation:
+
+```json
+memory_smart_search { "query": "session caching decision", "limit": 10 }
+```
+
+Response:
+
+```json
+{
+  "results": [
+    { "sessionId": "7f3a9c21", "type": "decision", "title": "Drop Redis for iii state store",
+      "narrative": "We decided to drop Redis and use the iii-engine state store for session caching.",
+      "importance": 8 }
+  ]
+}
+```
+
+Present:
+
+> Yes. In session `7f3a9c21` you decided to drop Redis and use the iii-engine
+> state store for session caching (importance 8).
+
+## 2. Multiple results across sessions
+
+User: "Recall anything about the rate limiter."
+
+Invocation:
+
+```json
+memory_smart_search { "query": "rate limiter", "limit": 10 }
+```
+
+Response:
+
+```json
+{
+  "results": [
+    { "sessionId": "b21d004e", "type": "code", "title": "limit.ts counts per-IP",
+      "narrative": "Rate limiter counts per-IP, not per-user.", "importance": 6 },
+    { "sessionId": "c98f1100", "type": "conversation", "title": "Discussed sliding window",
+      "narrative": "Considered a sliding-window limiter, deferred.", "importance": 4 }
+  ]
+}
+```
+
+Present them grouped by session, leading with the per-IP code note.
+
+## 3. No results
+
+User: "Recall the GraphQL schema migration."
+
+Invocation:
+
+```json
+memory_smart_search { "query": "graphql schema migration", "limit": 10 }
+```
+
+Response:
+
+```json
+{ "results": [] }
+```
+
+Present:
+
+> No memories matched that. Try `schema change`, `graphql`, or `migration` as
+> narrower terms, or `recap this week` to scan recent sessions.

package/plugin/skills/recall/SKILL.md

@@ -1,21 +1,60 @@
 ---
 name: recall
-description: Search agentmemory for past observations, sessions, and learnings about a topic. Use when the user says "recall", "remember", "what did we do", or needs context from past sessions.
+description: Search agentmemory for past observations, sessions, and learnings about a topic using hybrid BM25 plus vector plus graph search. Use when the user says "recall", "what did we do about", "did we ever", "have we seen", or needs context from past sessions.
 argument-hint: "[search query]"
 user-invocable: true
 ---
 
 The user wants to recall past context about: $ARGUMENTS
 
-Use the `memory_smart_search` MCP tool (provided by the agentmemory server that this plugin wires up automatically via `.mcp.json`) with the user's query as the `query` argument and `limit: 10`. The tool runs hybrid BM25 + vector + graph-expanded search over captured observations and returns ranked results.
+## Quick start
 
-Present the returned results to the user in a readable format:
-- Group by session
-- For each observation show its type, title, and narrative
-- Highlight the most important observations (importance >= 7)
-- If no results come back, suggest 2-3 alternative search terms the user could try
+```json
+memory_smart_search { "query": "jwt refresh token rotation", "limit": 10 }
+```
 
-**Do NOT make up or hallucinate observations.** Only present what the MCP tool actually returned. If `memory_smart_search` isn't available, the stdio MCP shim didn't start — tell the user to:
-1. Run `/plugin list` in Claude Code and confirm `agentmemory` shows as enabled.
-2. Restart Claude Code (the plugin's `.mcp.json` is only read on startup).
-3. Check `/mcp` to see whether the `agentmemory` MCP server is connected.
+Expected output:
+
+```text
+2 results across 2 sessions.
+[importance 8] decision · "Rotate refresh tokens on every use" (session 7f3a9c21)
+[importance 5] code · "limit.ts counts per-IP" (session b21d004e)
+```
+
+## Why
+
+Only surface what the tool returned. Never fabricate an observation, a session
+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.
+3. For each observation show its type, title, and narrative.
+4. Lead with the high-signal observations (importance >= 7).
+5. If zero results, suggest 2-3 alternative search terms and stop. Do not guess.
+
+## Anti-patterns
+
+WRONG: results are empty, so you write "We probably discussed token expiry last
+week" from assumption.
+
+RIGHT: "No memories matched that query. Try `refresh token`, `session expiry`,
+or `auth rotation`."
+
+## Checklist
+
+- Every observation shown came from the tool response.
+- Results grouped by session, high-importance first.
+- Empty results trigger alternative-term suggestions, not invention.
+- No session id or score was paraphrased or rounded.
+
+## See also
+
+- `remember`: the write side; recall retrieves what it stores.
+- `recap`, `handoff`, `session-history`: session-scoped views of the same data.
+
+## Troubleshooting
+
+See ../_shared/TROUBLESHOOTING.md if `memory_smart_search` is not available.

package/plugin/skills/recap/EXAMPLES.md

@@ -0,0 +1,60 @@
+# recap worked examples
+
+## 1. This week
+
+User: "Recap this week."
+
+Window: last 7 days. Invocation:
+
+```json
+memory_sessions { "limit": 30 }
+```
+
+Response (after filtering to cwd and the 7-day window):
+
+```json
+{
+  "sessions": [
+    { "id": "7f3a9c21", "cwd": "/Users/dev/app", "title": "Auth refresh rework",
+      "startedAt": "2026-06-07T09:00:00Z", "observationCount": 14, "status": "completed",
+      "concepts": ["jwt-refresh-rotation", "auth-flow"] },
+    { "id": "b21d004e", "cwd": "/Users/dev/app", "title": "Rate limiter audit",
+      "startedAt": "2026-06-05T14:00:00Z", "observationCount": 9, "status": "completed",
+      "concepts": ["rate-limiter", "per-ip-bug"] }
+  ]
+}
+```
+
+Per session, pull highlights:
+
+```json
+memory_recall { "query": "jwt-refresh-rotation auth-flow", "limit": 3 }
+```
+
+Present:
+
+> **2026-06-07**
+> - `7f3a9c2` Auth refresh rework, 14 obs, completed
+>   - [8] Rotate refresh tokens on every use
+>
+> **2026-06-05**
+> - `b21d004e` Rate limiter audit, 9 obs, completed
+>   - [7] limit.ts counts per-IP, not per-user
+>
+> 2 sessions across 2 days, 23 observations.
+
+## 2. Bare number
+
+User: "recap 3"
+
+Treat as `last 3`. Call `memory_sessions { "limit": 3 }`, group by date, same format.
+
+## 3. Empty window
+
+User: "Recap today."
+
+If `memory_sessions` returns no session whose `startedAt` is today and whose
+`cwd` matches:
+
+> No sessions today for this project. The most recent was yesterday, `7f3a9c2`
+> Auth refresh rework. Want a recap of that instead?

package/plugin/skills/recap/SKILL.md

@@ -1,25 +1,63 @@
 ---
 name: recap
-description: Summarize the last N agent sessions for the current project, grouped by date. Use when the user asks "recap", "what have we been doing", "this week", "today", or wants a rollup of recent work.
+description: Summarize the last N agent sessions for the current project, grouped by date, with highlight observations per session. Use when the user asks "recap", "what have we been doing", "today", "this week", or wants a rollup of recent work.
 argument-hint: "[last N | today | this week]"
 user-invocable: true
 ---
 
 The user wants a recap. Time window args: $ARGUMENTS
 
-Parse `$ARGUMENTS` to determine the window:
-- `today` -> sessions started on the current local date
-- `this week` -> sessions started in the last 7 days
-- `last <n>` -> the most recent N sessions
-- bare numeric -> treat as `last <n>`
-- empty -> default to `last 10`
+## Quick start
 
-Call the `memory_sessions` MCP tool, then filter to the current project (match by `cwd` against the working directory). Apply the time window. Sort by `startedAt` descending.
+```json
+memory_sessions { "limit": 30 }
+```
 
-Group the surviving sessions by their local calendar date (YYYY-MM-DD). For each date:
-- List each session: id (first 8 chars), title or first prompt, observation count, status
-- Indent two or three highlight observations per session (importance >= 7) drawn from `memory_recall` with a per-session query, limit 3
+Then per surviving session: `memory_recall { "query": "<top concepts>", "limit": 3 }`.
 
-End with a one-line total: "N sessions across M days, K observations."
+Expected output:
 
-If MCP tools are unavailable, fall back to HTTP: `GET $AGENTMEMORY_URL/agentmemory/sessions` and `POST $AGENTMEMORY_URL/agentmemory/recall` with `Authorization: Bearer $AGENTMEMORY_SECRET` when set. Do not invent sessions; if the window is empty, say so.
+```text
+2026-06-07
+  7f3a9c2 · "Auth refresh rework" · 14 obs · completed
+    - [8] Rotate refresh tokens on every use
+3 sessions across 2 days, 41 observations.
+```
+
+## Why
+
+Only summarize sessions and observations the tools returned. An empty window is
+a real answer, not a prompt to invent activity.
+
+## Workflow
+
+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.
+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`.
+5. End with "N sessions across M days, K observations."
+
+## Anti-patterns
+
+WRONG: window is empty, so you summarize "a productive week of auth work" from
+memory of the conversation.
+
+RIGHT: "No sessions in the last 7 days for this project."
+
+## Checklist
+
+- Window parsed correctly from the argument.
+- Sessions filtered to the current project's cwd.
+- Highlights come from `memory_recall`, not paraphrase.
+- Totals line reflects the actual counts shown.
+
+## See also
+
+- `handoff`, `session-history`, `recall`: same session data, different lens.
+
+## Troubleshooting
+
+See ../_shared/TROUBLESHOOTING.md if `memory_sessions` or `memory_recall` is not available.

package/plugin/skills/remember/EXAMPLES.md

@@ -0,0 +1,67 @@
+# remember worked examples
+
+## 1. Saving a decision
+
+User: "Remember that we decided to drop Redis and use the iii-engine state store for session caching."
+
+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",
+  "files": ""
+}
+```
+
+Response:
+
+```json
+{ "id": "7f3a9c21", "concepts": ["session-caching", "iii-state-store", "dropped-redis"], "saved": true }
+```
+
+Present:
+
+> Saved. Tagged it `session-caching`, `iii-state-store`, `dropped-redis`, so a
+> later recall on caching or Redis will surface this decision.
+
+## 2. Saving a code-specific gotcha
+
+User: "Save this: the rate limiter in middleware/limit.ts counts per-IP, not per-user, so logged-in users on shared IPs collide."
+
+Invocation:
+
+```json
+memory_save {
+  "content": "The rate limiter in middleware/limit.ts counts per-IP, not per-user, so logged-in users on shared IPs collide.",
+  "concepts": "rate-limiter, per-ip-bug, shared-ip-collision",
+  "files": "src/middleware/limit.ts"
+}
+```
+
+Response:
+
+```json
+{ "id": "b21d004e", "concepts": ["rate-limiter", "per-ip-bug", "shared-ip-collision"], "saved": true }
+```
+
+Present:
+
+> Saved memory `b21d004e` referencing `src/middleware/limit.ts`. Concepts:
+> `rate-limiter`, `per-ip-bug`, `shared-ip-collision`.
+
+## 3. Vague request, no files
+
+User: "Remember this for later."
+
+Ask once for the substance, then save:
+
+```json
+memory_save {
+  "content": "Staging deploys must run the migration job before the app rollout, never after.",
+  "concepts": "staging-deploy, migration-ordering, rollout-sequence",
+  "files": ""
+}
+```
+
+Present the confirmation with the concepts echoed back.