Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@
<p align="center">
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-recall.svg"><img src="assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tokens.svg"><img src="assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tools.svg"><img src="assets/tags/stat-tools.svg" alt="53 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tools.svg"><img src="assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-hooks.svg"><img src="assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-deps.svg"><img src="assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tests.svg"><img src="assets/tags/stat-tests.svg" alt="1,390+ tests passing" height="38" /></picture>
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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`

Expand Down Expand Up @@ -507,7 +507,7 @@ copilot plugin install rohitg00/agentmemory:plugin
<summary><b>OpenClaw (paste this prompt)</b></summary>

```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": {
Expand All @@ -532,7 +532,7 @@ Full guide: [`integrations/openclaw/`](integrations/openclaw/)
<summary><b>Hermes Agent (paste this prompt)</b></summary>

```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:
Expand Down Expand Up @@ -889,9 +889,9 @@ npm install @xenova/transformers

<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-mcp.svg"><img src="assets/tags/section-mcp.svg" alt="MCP Server" height="32" /></picture></h2>

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

Expand Down Expand Up @@ -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
```

Expand Down
4 changes: 2 additions & 2 deletions assets/tags/light/stat-tools.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions assets/tags/stat-tools.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion plugin/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion plugin/opencode/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
</p>

<p align="center">
<img src="https://img.shields.io/badge/MCP-53_tools-1f6feb?style=flat-square" alt="53 MCP tools" />
<img src="https://img.shields.io/badge/MCP-54_tools-1f6feb?style=flat-square" alt="54 MCP tools" />
<img src="https://img.shields.io/badge/Plugin-22_hooks-1f6feb?style=flat-square" alt="22 hooks" />
<img src="https://img.shields.io/badge/Commands-2_slash-1f6feb?style=flat-square" alt="2 slash commands" />
<img src="https://img.shields.io/badge/R@5-95.2%25-00875f?style=flat-square" alt="95.2% R@5" />
Expand Down
7 changes: 5 additions & 2 deletions plugin/opencode/agentmemory-capture.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
16 changes: 10 additions & 6 deletions plugin/skills/forget/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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: [<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"`
3. Once confirmed, pick the tool that matches what is being deleted:
- **Observations or sessions** (`obs_*` IDs, `ses_*` IDs) → call `memory_forget` with:
- `sessionId: "<ses_*>"` — the session the observations belong to
- `observationIds: "<obs_1>,<obs_2>"` — 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: [<id>, ...]` — an array (or comma-separated string) of memory IDs
- `reason: "<short reason>"` — optional, defaults to `"plugin skill request"`

Comment on lines +20 to 23

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Align governance-delete instructions with the actual runtime contract.

This text currently says memoryIds can be an array and that reason defaults to "plugin skill request". In current runtime behavior, MCP memory_governance_delete expects a comma-separated string in this path, and backend default reason is "manual deletion".

Proposed wording fix
-   - **Saved memories** (`mem_*` IDs) → call `memory_governance_delete` with:
-     - `memoryIds: [<id>, ...]` — an array (or comma-separated string) of memory IDs
-     - `reason: "<short reason>"` — optional, defaults to `"plugin skill request"`
+   - **Saved memories** (`mem_*` IDs) → call `memory_governance_delete` with:
+     - `memoryIds: "<id_1>,<id_2>"` — comma-separated memory IDs
+     - `reason: "<short reason>"` — optional, defaults to `"manual deletion"`
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@plugin/skills/forget/SKILL.md` around lines 20 - 23, The SKILL.md text for
memory_governance_delete is inaccurate: update the description for the
memory_governance_delete call (referenced by name) to state that the runtime
expects a comma-separated string for memoryIds (not an array) and that the
backend default reason is "manual deletion" (not "plugin skill request"); update
any examples or parameter notes in SKILL.md that reference memoryIds or reason
to match this runtime contract.

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.
Expand Down
15 changes: 14 additions & 1 deletion src/functions/governance.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<Memory>(KV.memories, id);
if (mem) {
Expand All @@ -27,6 +28,8 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void {
getSearchIndex().remove(id);
vectorIndexRemove(id);
deleted++;
} else {
notFound.push(id);
}
}

Expand All @@ -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 } : {}),
};
},
);

Expand Down
8 changes: 7 additions & 1 deletion src/functions/remember.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
};
},
);
}
41 changes: 41 additions & 0 deletions src/mcp/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 } : {}),
Comment on lines +624 to +643

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Reject malformed observationIds to avoid accidental full-session deletion.

At Line 626, malformed observationIds (e.g., non-string array entries or empty CSV payload) are normalized to [], and then omitted from the trigger payload. With a sessionId, that can unintentionally invoke whole-session deletion semantics in mem::forget instead of targeted observation deletion.

Proposed fix
           case "memory_forget": {
             const sessionId = asNonEmptyString(args.sessionId);
             const memoryId = asNonEmptyString(args.memoryId);
-            const observationIds = parseCsvList(args.observationIds);
+            const hasObservationIds = args.observationIds !== undefined;
+            if (
+              hasObservationIds &&
+              typeof args.observationIds !== "string" &&
+              !Array.isArray(args.observationIds)
+            ) {
+              return {
+                status_code: 400,
+                body: { error: "observationIds must be a comma-separated string or string[]" },
+              };
+            }
+            if (
+              Array.isArray(args.observationIds) &&
+              args.observationIds.some((v) => typeof v !== "string" || !v.trim())
+            ) {
+              return {
+                status_code: 400,
+                body: { error: "observationIds array must contain non-empty strings" },
+              };
+            }
+            const observationIds = parseCsvList(args.observationIds);
+            if (hasObservationIds && observationIds.length === 0) {
+              return {
+                status_code: 400,
+                body: { error: "observationIds must contain at least one ID" },
+              };
+            }
             if (observationIds.length > 0 && !sessionId) {
               return {
                 status_code: 400,
                 body: { error: "observationIds requires sessionId" },
               };

As per coding guidelines: MCP tool handlers must validate arguments with typeof checks and parse CSV args in a controlled way before triggering functions.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/mcp/server.ts` around lines 624 - 643, The handler currently normalizes
malformed observationIds to [] which gets omitted from the mem::forget payload
and can cause whole-session deletion; update the validation around
asNonEmptyString(args.sessionId), asNonEmptyString(args.memoryId) and
parseCsvList(args.observationIds) so that if args.observationIds is present you
validate its raw type (typeof args.observationIds === "string"), parse it with
parseCsvList, then ensure the result is a non-empty array of non-empty strings
(each entry typeof === "string" && entry.trim().length>0); if this validation
fails return a 400 with an explicit error like "malformed observationIds" and do
not call sdk.trigger({ function_id: "mem::forget", ...}) without observationIds
— only include observationIds in the trigger payload when they passed
validation.

Source: Coding guidelines

} });
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: {
Expand Down
28 changes: 28 additions & 0 deletions src/mcp/tools-registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.",
Expand Down
Loading