ziiagentmemory 0.1.0

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

@@ -0,0 +1,62 @@
+---
+name: commit-history
+description: List recent git commits linked to agent sessions, optionally filtered by branch or repo. Use when the user asks "show agent commits", "what has the agent shipped", "list linked commits", or wants commits with their session context.
+argument-hint: "[branch=... repo=... limit=...]"
+user-invocable: true
+---
+
+The user wants a list of agent-linked commits. Filter args: $ARGUMENTS
+
+## Quick start
+
+```json
+memory_commits { "branch": "main", "limit": 20 }
+```
+
+Expected output:
+
+```text
+9a1b2c3 main 2026-06-07 "rotate refresh tokens" · session 7f3a9c2 (14 obs)
+b21d004 main 2026-06-05 "rate limiter audit"    · session b21d004 (9 obs)
+```
+
+## Why
+
+Render only the commits the tool returned, newest first. An empty result means
+the filter matched nothing, not that work is missing.
+
+## Workflow
+
+1. Parse `$ARGUMENTS` for `branch=<name>`, `repo=<url-or-fragment>`,
+   `limit=<n>`. A bare numeric token is the limit. Defaults: no branch, no repo,
+   limit 100, max 500.
+2. Call `memory_commits` with the parsed filters.
+3. Render reverse-chronologically: short sha, branch, authored timestamp, first
+   line of the message, linked session id(s) (first 8) with observation counts,
+   and file count when `files` is present.
+4. Empty result: tell the user the filter matched nothing and suggest dropping
+   the branch or repo filter.
+
+## Anti-patterns
+
+WRONG (REST fallback): concatenate `?branch=` + raw branch name, so a name with
+`?`, `&`, or `#` corrupts the query string.
+
+RIGHT: URL-encode every value with `URLSearchParams`/`encodeURIComponent` before
+appending to `GET /agentmemory/commits`.
+
+## Checklist
+
+- Filters parsed; bare number treated as limit; limit capped at 500.
+- Output is reverse-chronological.
+- Session ids and observation counts come straight from the response.
+- REST fallback URL-encodes branch, repo, and limit.
+
+## See also
+
+- `commit-context`: drill into one commit's session.
+- `recall`: search the observations behind a linked session.
+
+## Troubleshooting
+
+See ../_shared/TROUBLESHOOTING.md if `memory_commits` is not available.

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

@@ -0,0 +1,66 @@
+---
+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.
+argument-hint: "[what to forget - session ID, file path, or search term]"
+user-invocable: true
+---
+
+The user wants to remove data from agentmemory: $ARGUMENTS
+
+## Quick start
+
+```json
+memory_smart_search { "query": "old api key in config", "limit": 20 }
+```
+
+Show the matches, get a yes, then:
+
+```json
+memory_governance_delete { "memoryIds": ["abc12345", "def67890"], "reason": "user privacy request" }
+```
+
+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

@@ -0,0 +1,68 @@
+---
+name: handoff
+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
+
+## Quick start
+
+```json
+memory_sessions { "limit": 20 }
+```
+
+Pick the most recent session whose `cwd` matches this project, then:
+`memory_recall { "query": "<session top concepts>", "limit": 10 }`.
+
+Expected output:
+
+```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

@@ -0,0 +1,60 @@
+---
+name: recall
+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
+
+## Quick start
+
+```json
+memory_smart_search { "query": "jwt refresh token rotation", "limit": 10 }
+```
+
+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

@@ -0,0 +1,63 @@
+---
+name: recap
+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
+
+## Quick start
+
+```json
+memory_sessions { "limit": 30 }
+```
+
+Then per surviving session: `memory_recall { "query": "<top concepts>", "limit": 3 }`.
+
+Expected output:
+
+```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.