# Destructive MCP Tools in ai-memory: Administrative Operations Reference

> Discover destructive MCP tools in ai-memory like purge project, delete workspace, and reset. These admin endpoints modify or delete wiki data. Learn more!

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: api-reference
- Published: 2026-08-22

---

**The ai-memory repository exposes eleven destructive MCP tools—admin endpoints such as `purge-project`, `delete-workspace`, and `reset`—that modify or delete wiki data and require Admin capability with explicit confirmation flags.**

The ai-memory project implements a **Memory-Client-Protocol (MCP)** interface for managing persistent knowledge stores via HTTP. The **destructive MCP tools** category includes all administrative endpoints that perform state-changing operations on projects, workspaces, and pages within the SQLite-backed wiki system.

## Overview of Destructive MCP Tools

Destructive MCP tools are HTTP POST endpoints mounted under the `/admin/*` namespace. According to the source code in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs), these operations permanently alter or remove data, distinguishing them from read-only query interfaces.

### What Makes a Tool Destructive

A tool is classified as destructive when it performs any of the following actions:

- Permanently deleting projects, workspaces, or individual pages
- Renaming entities that require direct database row updates
- Moving data between scopes or merging workspace hierarchies
- Restoring or resetting system state from backups

## Available Destructive MCP Tools

The ai-memory MCP interface provides eleven administrative tools that modify the wiki store. Each requires the `Admin` capability and explicit confirmation to execute.

### Project and Workspace Lifecycle Tools

- **admin/purge-project**: Completely removes a project and all associated pages, sessions, and observations. Implemented in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs) at line 86.
- **admin/delete-workspace**: Deletes an entire workspace including every project it contains. Found at line 90 of [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs).
- **admin/merge-workspace**: Merges one workspace into another, then deletes the now-empty source workspace. Located at line 92 in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs).

### Renaming and Relocation Tools

- **admin/rename-project**: Updates the database row to rename a project without moving underlying files. See line 87 in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs).
- **admin/rename-workspace**: Renames a workspace and refreshes scope manifests accordingly. Implemented at line 91 in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs).
- **admin/move-project**: Copies pages to a destination workspace then purges the source project. Found at line 88 in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs).
- **admin/move-session**: Updates a session's scope to move it between projects or workspaces. Located at line 89 in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs).

### Page-Level and System Operations

- **admin/delete-page**: Permanently deletes a single wiki page by its path. Implemented at line 93 in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs).
- **admin/restore-page**: Restores a single page from a previously created git checkpoint. Found at line 85 in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs).
- **admin/reset**: Resets the entire server state, dropping all data and re-initializing the system. This legacy privileged endpoint requires Admin rights.
- **admin/restore**: Restores the entire wiki and SQLite database from a backup tarball, overwriting current state. Implemented alongside the backup handlers in the admin router.

## Authentication and Safety Requirements

Every destructive MCP tool enforces strict authorization checks to prevent accidental data loss.

### Required Capabilities

All administrative endpoints require the **Admin capability** (`Capability::Admin`) as enforced by the auth middleware in [`crates/ai-memory-mcp/src/auth.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/auth.rs). The server validates the caller's `AuthLevel` before executing any state-changing operation.

### Confirmation Flags

As documented in [`AGENTS.md`](https://github.com/akitaonrails/ai-memory/blob/main/AGENTS.md) and implemented in [`admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/admin.rs) at line 4086, destructive operations demand explicit confirmation:

- **`confirm=true`**: Required parameter for all destructive tools to confirm intent
- **`force`**: Used where applicable to bypass additional warnings

## Usage Examples

The following examples demonstrate how to invoke destructive MCP tools via HTTP POST requests to the admin router at `http://localhost:49374`.

### Purge an Entire Project

```bash
curl -X POST http://localhost:49374/admin/purge-project \
     -H "Authorization: Bearer <admin-token>" \
     -d '{"workspace":"my_ws","project":"old_project","confirm":true}'

```

### Rename a Project

```bash
curl -X POST http://localhost:49374/admin/rename-project \
     -H "Authorization: Bearer <admin-token>" \
     -d '{"workspace":"my_ws","project":"old_name","new_name":"new_name","confirm":true}'

```

### Move a Project Between Workspaces

```bash
curl -X POST http://localhost:49374/admin/move-project \
     -H "Authorization: Bearer <admin-token>" \
     -d '{"src_workspace":"ws1","src_project":"proj","dst_workspace":"ws2","confirm":true}'

```

### Delete a Specific Page

```bash
curl -X POST http://localhost:49374/admin/delete-page \
     -H "Authorization: Bearer <admin-token>" \
     -d '{"workspace":"my_ws","project":"my_proj","path":"notes/todo.md","confirm":true}'

```

## Implementation in the Source Code

The destructive MCP tools are implemented across several key files in the ai-memory codebase.

### Admin Router and Handlers

All destructive routes are defined in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs). This file contains the request handlers for every administrative operation, with specific implementations ranging from line 85 (`admin/restore-page`) through line 93 (`admin/delete-page`). The comment at line 4086 documents the confirmation policy for destructive operations.

### Authorization Layer

The [`crates/ai-memory-mcp/src/auth.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/auth.rs) module defines the `Capability::Admin` enum variant and enforces capability-based access control. The server rejects any destructive request lacking proper authorization headers.

### Server Integration

The admin router is registered with the main HTTP server in [`crates/ai-memory-mcp/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/lib.rs), which wires the MCP tools into the API surface. These tools are **MCP-only** and are not exposed via the standard client-side CLI commands.

## Summary

- **Destructive MCP tools** in ai-memory include eleven administrative endpoints for deleting, renaming, moving, and restoring projects, workspaces, and pages.
- All tools require **HTTP POST** requests to the `/admin/*` namespace with **Admin capability** authorization.
- Every destructive operation mandates **`confirm=true`** to prevent accidental data loss, as enforced in [`admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/admin.rs) at line 4086 and documented in [`AGENTS.md`](https://github.com/akitaonrails/ai-memory/blob/main/AGENTS.md).
- Key implementations reside in [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs) with specific handlers at lines 85-93.
- These tools are exclusively available through the MCP interface, not the standard CLI.

## Frequently Asked Questions

### What is the difference between admin/purge-project and admin/delete-workspace?

**admin/purge-project** removes a single project and its contents while leaving the workspace intact, whereas **admin/delete-workspace** recursively deletes the workspace and every project contained within it. Both operations are irreversible without backup restoration, as noted in the destructive operations policy.

### How do I authorize a request to use destructive MCP tools in ai-memory?

You must include an `Authorization` header with a Bearer token that possesses the **Admin capability** (`Capability::Admin`). The server validates this against the auth layer defined in [`crates/ai-memory-mcp/src/auth.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/auth.rs) before processing any destructive request.

### Can destructive MCP tools be accessed through the ai-memory CLI?

No. According to the source analysis, these tools are **MCP-only** endpoints exposed via the HTTP admin router. They are not available through normal client-side CLI commands and must be accessed through direct HTTP POST requests to the MCP interface.

### What happens when I call admin/restore-page?

The **admin/restore-page** tool retrieves a single wiki page from a previously created git checkpoint and restores it to the active wiki state, overwriting any current version of that page. This operation is destructive to existing unsaved changes on that specific page path.