From 9af6e8a2ec24eac5987f671b69f3126264bc5167 Mon Sep 17 00:00:00 2001 From: serhiizghama Date: Sat, 6 Jun 2026 09:10:11 +0700 Subject: [PATCH 1/3] feat(mcp): expose memory_forget tool for observation and session deletion --- AGENTS.md | 2 +- README.md | 16 +-- assets/tags/light/stat-tools.svg | 4 +- assets/tags/stat-tools.svg | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/.codex-plugin/plugin.json | 2 +- plugin/opencode/README.md | 2 +- plugin/plugin.json | 2 +- src/functions/remember.ts | 8 +- src/mcp/server.ts | 41 +++++++ src/mcp/tools-registry.ts | 28 +++++ test/mcp-forget-tool.test.ts | 179 ++++++++++++++++++++++++++++++ test/mcp-standalone.test.ts | 4 +- 13 files changed, 274 insertions(+), 20 deletions(-) create mode 100644 test/mcp-forget-tool.test.ts diff --git a/AGENTS.md b/AGENTS.md index a5e3633a6c..90878cd63f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -116,7 +116,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). ## Current Stats (v0.9.16) -- 53 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all) +- 54 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all) - 128 REST endpoints - 6 MCP resources, 3 MCP prompts - 12 hooks, 4 skills diff --git a/README.md b/README.md index af01900271..4d9c342222 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@

95.2% retrieval R@5 92% fewer tokens - 53 MCP tools + 54 MCP tools 12 auto hooks 0 external DBs 1,390+ tests passing @@ -444,7 +444,7 @@ Implementation details live in `src/cli.ts` (see `runUpgrade` around the `src/cl ### Claude Code (one block, paste it) ```text -Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 8 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. +Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 8 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. ``` #### Claude Code without the plugin install (MCP-standalone path) @@ -473,7 +473,7 @@ codex plugin add agentmemory@agentmemory The Codex plugin ships from the same `plugin/` directory as the Claude Code plugin. It registers: -- `@agentmemory/mcp` as an MCP server (proxies all 53 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable) +- `@agentmemory/mcp` as an MCP server (proxies all 54 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable) - 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop` - 8 skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/commit-context`, `/commit-history` @@ -507,7 +507,7 @@ copilot plugin install rohitg00/agentmemory:plugin

OpenClaw (paste this prompt) ```text -Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 53 memory tools: +Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools: { "mcpServers": { @@ -532,7 +532,7 @@ Full guide: [`integrations/openclaw/`](integrations/openclaw/) Hermes Agent (paste this prompt) ```text -Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 53 memory tools: +Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools: mcp_servers: agentmemory: @@ -889,9 +889,9 @@ npm install @xenova/transformers

MCP Server

-53 tools, 6 resources, 3 prompts, and 8 skills — the most comprehensive MCP memory toolkit for any agent. +54 tools, 6 resources, 3 prompts, and 8 skills — the most comprehensive MCP memory toolkit for any agent. -> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the full 53-tool surface **only when it can reach a running agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). The `AGENTMEMORY_TOOLS=core|all` env var is a *server-side* flag — setting it in the shim's `env` block has no effect. If you see only 7 tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`. +> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the full 54-tool surface **only when it can reach a running agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). The `AGENTMEMORY_TOOLS=core|all` env var is a *server-side* flag — setting it in the shim's `env` block has no effect. If you see only 7 tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`. ### 53 Tools @@ -1423,7 +1423,7 @@ Create `~/.agentmemory/.env`: # USER_ID= # TEAM_MODE=private -# Tool visibility: "core" (8 tools, lean fallback) or "all" (53 tools) +# Tool visibility: "core" (8 tools, lean fallback) or "all" (54 tools) # AGENTMEMORY_TOOLS=core ``` diff --git a/assets/tags/light/stat-tools.svg b/assets/tags/light/stat-tools.svg index e6d598532f..9ed07e9faf 100644 --- a/assets/tags/light/stat-tools.svg +++ b/assets/tags/light/stat-tools.svg @@ -1,5 +1,5 @@ - + - 53 + 54 MCP TOOLS diff --git a/assets/tags/stat-tools.svg b/assets/tags/stat-tools.svg index 2f38d7a109..57c3dc4eef 100644 --- a/assets/tags/stat-tools.svg +++ b/assets/tags/stat-tools.svg @@ -1,5 +1,5 @@ - + - 53 + 54 MCP TOOLS diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index cb4e6df7b8..f351b2c8bc 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "version": "0.9.27", - "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 53 MCP tools, 8 skills, real-time viewer.", + "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 54 MCP tools, 8 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json index 7c42f13094..f135276f48 100644 --- a/plugin/.codex-plugin/plugin.json +++ b/plugin/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "version": "0.9.27", - "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 6 hooks, 53 MCP tools, 8 skills, real-time viewer.", + "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 6 hooks, 54 MCP tools, 8 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/plugin/opencode/README.md b/plugin/opencode/README.md index 60f5e5bb94..6bcc4b321e 100644 --- a/plugin/opencode/README.md +++ b/plugin/opencode/README.md @@ -9,7 +9,7 @@

- 53 MCP tools + 54 MCP tools 22 hooks 2 slash commands 95.2% R@5 diff --git a/plugin/plugin.json b/plugin/plugin.json index 5cb13fe844..0265b43a52 100644 --- a/plugin/plugin.json +++ b/plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agentmemory", "version": "0.9.27", - "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 53 MCP tools, 8 skills, real-time viewer.", + "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 54 MCP tools, 8 skills, real-time viewer.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" diff --git a/src/functions/remember.ts b/src/functions/remember.ts index 5735b4f238..fca470dc4d 100644 --- a/src/functions/remember.ts +++ b/src/functions/remember.ts @@ -258,7 +258,13 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void { } logger.info("Memory forgotten", { deleted }); - return { success: true, deleted }; + return { + success: true, + deleted, + memoriesDeleted: deletedMemoryIds.length, + observationsDeleted: deletedObservationIds.length, + sessionDeleted: deletedSession, + }; }, ); } diff --git a/src/mcp/server.ts b/src/mcp/server.ts index e21445670c..647c20a8e3 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -620,6 +620,47 @@ export function registerMcpEndpoints( } } + case "memory_forget": { + const sessionId = asNonEmptyString(args.sessionId); + const memoryId = asNonEmptyString(args.memoryId); + const observationIds = parseCsvList(args.observationIds); + if (observationIds.length > 0 && !sessionId) { + return { + status_code: 400, + body: { error: "observationIds requires sessionId" }, + }; + } + if (!sessionId && !memoryId) { + return { + status_code: 400, + body: { error: "sessionId or memoryId is required" }, + }; + } + try { + const result = await sdk.trigger({ function_id: "mem::forget", payload: { + ...(sessionId ? { sessionId } : {}), + ...(observationIds.length > 0 ? { observationIds } : {}), + ...(memoryId ? { memoryId } : {}), + } }); + return { + status_code: 200, + body: { + content: [ + { type: "text", text: JSON.stringify(result, null, 2) }, + ], + }, + }; + } catch { + return { + status_code: 200, + body: { + content: [{ type: "text", text: "Forget failed" }], + isError: true, + }, + }; + } + } + case "memory_snapshot_create": { try { const result = await sdk.trigger({ function_id: "mem::snapshot-create", payload: { diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts index c86d899bbc..ebf8cd73b2 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -345,6 +345,34 @@ export const V040_TOOLS: McpToolDef[] = [ required: ["memoryIds"], }, }, + { + name: "memory_forget", + description: + "Delete observations, a whole session, or a single memory with audit trail. " + + "Use this for observation (obs_*) and session cleanup — " + + "memory_governance_delete only handles saved memories (mem_*).", + inputSchema: { + type: "object", + properties: { + sessionId: { + type: "string", + description: + "Session to delete from. Without observationIds, removes ALL of the " + + "session's observations plus the session record and its summary.", + }, + observationIds: { + type: "string", + description: + "Comma-separated observation IDs to delete within sessionId. " + + "Requires sessionId.", + }, + memoryId: { + type: "string", + description: "Single saved memory ID to delete", + }, + }, + }, + }, { name: "memory_snapshot_create", description: "Create a git-versioned snapshot of current memory state.", diff --git a/test/mcp-forget-tool.test.ts b/test/mcp-forget-tool.test.ts new file mode 100644 index 0000000000..e5e8e02a3c --- /dev/null +++ b/test/mcp-forget-tool.test.ts @@ -0,0 +1,179 @@ +import { describe, it, expect, beforeEach, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); + +import { registerMcpEndpoints } from "../src/mcp/server.js"; + +function mockKV() { + const store = new Map>(); + return { + get: async (scope: string, key: string): Promise => { + return (store.get(scope)?.get(key) as T) ?? null; + }, + set: async (scope: string, key: string, data: T): Promise => { + if (!store.has(scope)) store.set(scope, new Map()); + store.get(scope)!.set(key, data); + return data; + }, + delete: async (scope: string, key: string): Promise => { + store.get(scope)?.delete(key); + }, + list: async (scope: string): Promise => { + const entries = store.get(scope); + return entries ? (Array.from(entries.values()) as T[]) : []; + }, + }; +} + +function mockSdk() { + const functions = new Map(); + const triggerOverrides = new Map(); + return { + registerFunction: (idOrOpts: string | { id: string }, handler: Function) => { + const id = typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id; + functions.set(id, handler); + }, + registerTrigger: () => {}, + trigger: async ( + idOrInput: string | { function_id: string; payload: unknown }, + data?: unknown, + ) => { + const id = typeof idOrInput === "string" ? idOrInput : idOrInput.function_id; + const payload = typeof idOrInput === "string" ? data : idOrInput.payload; + if (triggerOverrides.has(id)) { + return triggerOverrides.get(id)!(payload); + } + const fn = functions.get(id); + if (!fn) throw new Error(`No function: ${id}`); + return fn(payload); + }, + overrideTrigger: (id: string, handler: Function) => { + triggerOverrides.set(id, handler); + }, + getFunction: (id: string) => functions.get(id), + }; +} + +function makeReq(body?: unknown, headers?: Record) { + return { + body, + headers: headers || {}, + query_params: {}, + }; +} + +type McpResponse = { + status_code: number; + body: { + error?: string; + content?: Array<{ type: string; text: string }>; + isError?: boolean; + tools?: Array<{ name: string }>; + }; +}; + +describe("memory_forget MCP tool (issue #833)", () => { + let sdk: ReturnType; + let kv: ReturnType; + let forgetPayloads: unknown[]; + + beforeEach(() => { + sdk = mockSdk(); + kv = mockKV(); + registerMcpEndpoints(sdk as never, kv as never); + forgetPayloads = []; + sdk.overrideTrigger("mem::forget", (payload: unknown) => { + forgetPayloads.push(payload); + return { + success: true, + deleted: 3, + memoriesDeleted: 0, + observationsDeleted: 1, + sessionDeleted: true, + }; + }); + }); + + async function callTool( + args: Record, + ): Promise { + const handler = sdk.getFunction("mcp::tools::call")!; + return handler( + makeReq({ name: "memory_forget", arguments: args }), + ) as Promise; + } + + it("is listed in the MCP tool registry", async () => { + const handler = sdk.getFunction("mcp::tools::list")!; + const res = (await handler(makeReq())) as McpResponse; + expect(res.status_code).toBe(200); + const names = (res.body.tools ?? []).map((t) => t.name); + expect(names).toContain("memory_forget"); + }); + + it("rejects calls without sessionId or memoryId", async () => { + const res = await callTool({}); + expect(res.status_code).toBe(400); + expect(res.body.error).toBe("sessionId or memoryId is required"); + expect(forgetPayloads.length).toBe(0); + }); + + it("rejects observationIds without sessionId", async () => { + const res = await callTool({ observationIds: "obs_1,obs_2" }); + expect(res.status_code).toBe(400); + expect(res.body.error).toBe("observationIds requires sessionId"); + expect(forgetPayloads.length).toBe(0); + }); + + it("forwards sessionId-only deletes to mem::forget", async () => { + const res = await callTool({ sessionId: "ses_1" }); + expect(res.status_code).toBe(200); + expect(forgetPayloads).toEqual([{ sessionId: "ses_1" }]); + const text = res.body.content?.[0]?.text ?? ""; + expect(JSON.parse(text)).toMatchObject({ + success: true, + deleted: 3, + sessionDeleted: true, + }); + }); + + it("parses comma-separated observationIds", async () => { + const res = await callTool({ + sessionId: "ses_1", + observationIds: "obs_1, obs_2 ,obs_3", + }); + expect(res.status_code).toBe(200); + expect(forgetPayloads).toEqual([ + { sessionId: "ses_1", observationIds: ["obs_1", "obs_2", "obs_3"] }, + ]); + }); + + it("accepts observationIds as an array", async () => { + const res = await callTool({ + sessionId: "ses_1", + observationIds: ["obs_1", "obs_2"], + }); + expect(res.status_code).toBe(200); + expect(forgetPayloads).toEqual([ + { sessionId: "ses_1", observationIds: ["obs_1", "obs_2"] }, + ]); + }); + + it("forwards memoryId deletes to mem::forget", async () => { + const res = await callTool({ memoryId: "mem_1" }); + expect(res.status_code).toBe(200); + expect(forgetPayloads).toEqual([{ memoryId: "mem_1" }]); + }); + + it("returns an isError content block when mem::forget throws", async () => { + sdk.overrideTrigger("mem::forget", () => { + throw new Error("boom"); + }); + const res = await callTool({ sessionId: "ses_1" }); + expect(res.status_code).toBe(200); + expect(res.body.isError).toBe(true); + expect(res.body.content?.[0]?.text).toBe("Forget failed"); + }); +}); diff --git a/test/mcp-standalone.test.ts b/test/mcp-standalone.test.ts index b48eade966..8ff771c30c 100644 --- a/test/mcp-standalone.test.ts +++ b/test/mcp-standalone.test.ts @@ -72,8 +72,8 @@ describe("Tools Registry", () => { expect(CORE_TOOLS.length).toBe(14); }); - it("V040_TOOLS has 8 items", () => { - expect(V040_TOOLS.length).toBe(8); + it("V040_TOOLS has 9 items", () => { + expect(V040_TOOLS.length).toBe(9); }); it("all tools have required name, description, inputSchema fields", () => { From 252d92f043df24be50d3dc2c7b989c067b4c6603 Mon Sep 17 00:00:00 2001 From: serhiizghama Date: Sat, 6 Jun 2026 09:10:16 +0700 Subject: [PATCH 2/3] fix(governance): report notFound ids instead of claiming success on no-op deletes --- src/functions/governance.ts | 15 +++++++++++- test/governance.test.ts | 47 +++++++++++++++++++++++++++++++++---- 2 files changed, 57 insertions(+), 5 deletions(-) diff --git a/src/functions/governance.ts b/src/functions/governance.ts index 16d0d1c427..ff05579d45 100644 --- a/src/functions/governance.ts +++ b/src/functions/governance.ts @@ -19,6 +19,7 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { } let deleted = 0; + const notFound: string[] = []; for (const id of data.memoryIds) { const mem = await kv.get(KV.memories, id); if (mem) { @@ -27,6 +28,8 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { getSearchIndex().remove(id); vectorIndexRemove(id); deleted++; + } else { + notFound.push(id); } } @@ -40,14 +43,24 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { { reason: data.reason || "manual deletion", deleted, + ...(notFound.length > 0 ? { notFound } : {}), }, ); logger.info("Governance delete", { requested: data.memoryIds.length, deleted, + notFound: notFound.length, }); - return { success: true, deleted, total: data.memoryIds.length }; + // success only when every requested ID was actually removed — + // a no-op delete reporting success hid real data-retention bugs + // (observation IDs passed here never match the memories store). + return { + success: notFound.length === 0, + deleted, + total: data.memoryIds.length, + ...(notFound.length > 0 ? { notFound } : {}), + }; }, ); diff --git a/test/governance.test.ts b/test/governance.test.ts index 6390bbeea6..b31c7acef6 100644 --- a/test/governance.test.ts +++ b/test/governance.test.ts @@ -96,19 +96,58 @@ describe("Governance Functions", () => { expect(remaining.length).toBe(2); }); - it("governance-delete handles non-existent IDs gracefully", async () => { + it("governance-delete reports non-existent IDs instead of claiming success (#833)", async () => { const result = (await sdk.trigger("mem::governance-delete", { memoryIds: ["nonexistent_1", "nonexistent_2"], - })) as { success: boolean; deleted: number; total: number }; - - expect(result.success).toBe(true); + })) as { + success: boolean; + deleted: number; + total: number; + notFound?: string[]; + }; + + expect(result.success).toBe(false); expect(result.deleted).toBe(0); expect(result.total).toBe(2); + expect(result.notFound).toEqual(["nonexistent_1", "nonexistent_2"]); const remaining = await kv.list("mem:memories"); expect(remaining.length).toBe(3); }); + it("governance-delete flags partial deletes with the missing IDs (#833)", async () => { + const result = (await sdk.trigger("mem::governance-delete", { + memoryIds: ["mem_1", "obs_unknown"], + })) as { + success: boolean; + deleted: number; + total: number; + notFound?: string[]; + }; + + expect(result.success).toBe(false); + expect(result.deleted).toBe(1); + expect(result.total).toBe(2); + expect(result.notFound).toEqual(["obs_unknown"]); + + const remaining = await kv.list("mem:memories"); + expect(remaining.length).toBe(2); + }); + + it("governance-delete omits notFound when every ID was deleted", async () => { + const result = (await sdk.trigger("mem::governance-delete", { + memoryIds: ["mem_1", "mem_2"], + })) as { + success: boolean; + deleted: number; + notFound?: string[]; + }; + + expect(result.success).toBe(true); + expect(result.deleted).toBe(2); + expect(result.notFound).toBeUndefined(); + }); + it("governance-bulk deletes by type filter", async () => { const result = (await sdk.trigger("mem::governance-bulk", { type: ["pattern"], From 5c8a362ec70d4e698368427fe4df8933260c2241 Mon Sep 17 00:00:00 2001 From: serhiizghama Date: Sat, 6 Jun 2026 09:10:16 +0700 Subject: [PATCH 3/3] docs(plugin): route forget skill through memory_forget for observations --- plugin/opencode/agentmemory-capture.ts | 7 +++++-- plugin/skills/forget/SKILL.md | 16 ++++++++++------ 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/plugin/opencode/agentmemory-capture.ts b/plugin/opencode/agentmemory-capture.ts index 056d53d38d..cf9a7b320d 100644 --- a/plugin/opencode/agentmemory-capture.ts +++ b/plugin/opencode/agentmemory-capture.ts @@ -129,8 +129,11 @@ memory_lesson_save — Save a lesson learned (what worked, what to avoid). memory_lesson_recall — Search lessons by query. Returns lessons sorted by confidence. Use when: before making a decision, check if past lessons apply. -memory_governance_delete — Delete specific memories. Requires explicit user confirmation. - Use when: user says "forget this", "delete that memory". +memory_governance_delete — Delete specific saved memories (mem_* IDs). Requires explicit user confirmation. + Use when: user says "forget this", "delete that memory" about saved memories. + +memory_forget — Delete observations (obs_* IDs), an entire session, or a single memory. Requires explicit user confirmation. + Use when: user wants to remove session observations or a whole session; governance_delete cannot delete those. memory_patterns — Detect recurring patterns across sessions. Use when: you want to understand project-level trends over time. diff --git a/plugin/skills/forget/SKILL.md b/plugin/skills/forget/SKILL.md index 067d564cb8..76e7cc4be6 100644 --- a/plugin/skills/forget/SKILL.md +++ b/plugin/skills/forget/SKILL.md @@ -11,14 +11,18 @@ The user wants to remove data from agentmemory: $ARGUMENTS Steps: -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`. +1. First search for matching data 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: [, ...]` — an array (or comma-separated string) of the memory IDs returned by the search in step 1 - - `reason: ""` — optional, defaults to `"plugin skill request"` +3. Once confirmed, pick the tool that matches what is being deleted: + - **Observations or sessions** (`obs_*` IDs, `ses_*` IDs) → call `memory_forget` with: + - `sessionId: ""` — the session the observations belong to + - `observationIds: ","` — optional; omit it to delete ALL of the session's observations plus the session record and its summary + - **Saved memories** (`mem_*` IDs) → call `memory_governance_delete` with: + - `memoryIds: [, ...]` — an array (or comma-separated string) of memory IDs + - `reason: ""` — optional, defaults to `"plugin skill request"` - 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. + Do NOT pass observation IDs to `memory_governance_delete` — it only targets the saved-memories store and will report them back in `notFound` without deleting anything. +4. Confirm the deletion count back to the user from the tool result (`deleted`, `observationsDeleted`, `sessionDeleted`, or `notFound`). If `notFound` is non-empty or `success` is `false`, tell the user which IDs were not deleted instead of reporting success. **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.