forget_memory
Remove or fade memory chunks from search results. Choose instant suppression for permanent hiding or cold demotion for gradual relevance decay.
Instructions
Forget a chunk from memory using either instant suppression or gradual decay.
Two modes are available:
- **suppress** (default): chunk is added to the suppression list and
immediately hidden from all search results. Use when you never want
to see this chunk again.
- **cold**: chunk is demoted to the cold memory tier so its relevance
score decays over time. The chunk stays visible but becomes less
prominent on each query. Use when you prefer gradual fading.
Use ``pin_memory`` to reverse a cold demotion and restore full relevance.
A suppressed chunk can only be unsuppressed by direct database access
(intentionally — suppression is permanent).
Args:
chunk_id: Stable chunk identifier ``<path>:<chunk_index>``.
mode: ``"suppress"`` or ``"cold"``. Defaults to ``"suppress"``.
Returns:
Confirmation dict with ``chunk_id``, ``mode``, and result fields.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chunk_id | Yes | ||
| mode | No | suppress |
Implementation Reference
- The forget_memory MCP tool handler function, registered via @mcp.tool() decorator. Supports two modes: 'suppress' (instantly hides chunk via forgotten_chunks suppression table) and 'cold' (demotes to cold tier for gradual score decay). Checks auth via check_access(ctx, 'delete'), then delegates to ctx.metadata_store.forget_chunk() or ctx.tiered_memory.forget() accordingly.
@mcp.tool() def forget_memory( chunk_id: Annotated[ str, "The chunk identifier to forget, in '<absolute_path>:<chunk_index>' format. " "Chunk IDs are returned by search_memory results.", ], mode: Annotated[ Literal["suppress", "cold"], "'suppress' (default) — hide chunk from search immediately via the " "forgotten_chunks suppression table. " "'cold' — demote to cold tier so the chunk's score decays gradually " "(requires memory tiers to be enabled).", ] = "suppress", ) -> dict: """Forget a chunk from memory using either instant suppression or gradual decay. Two modes are available: - **suppress** (default): chunk is added to the suppression list and immediately hidden from all search results. Use when you never want to see this chunk again. - **cold**: chunk is demoted to the cold memory tier so its relevance score decays over time. The chunk stays visible but becomes less prominent on each query. Use when you prefer gradual fading. Use ``pin_memory`` to reverse a cold demotion and restore full relevance. A suppressed chunk can only be unsuppressed by direct database access (intentionally — suppression is permanent). Args: chunk_id: Stable chunk identifier ``<path>:<chunk_index>``. mode: ``"suppress"`` or ``"cold"``. Defaults to ``"suppress"``. Returns: Confirmation dict with ``chunk_id``, ``mode``, and result fields. """ from memorymesh.server.auth_guard import check_access if (err := check_access(ctx, "delete")) is not None: return err if mode == "suppress": try: ctx.metadata_store.forget_chunk(chunk_id) except AttributeError: return {"error": "forget_chunk not implemented by this metadata store."} except Exception as exc: return {"error": str(exc)} return {"chunk_id": chunk_id, "mode": "suppress", "suppressed": True} # mode == "cold" if ctx.tiered_memory is None: return {"error": "Memory tiers are not enabled in the current configuration."} ctx.tiered_memory.forget(chunk_id) ctx.audit_logger.log_query( tool="forget_memory", query=chunk_id, n_results=0, latency_ms=0.0, ) return {"chunk_id": chunk_id, "mode": "cold", "tier": "cold", "pinned": False} - src/memorymesh/server/app.py:110-132 (registration)Import and registration of the forget_memory tool. The module is imported from memorymesh.server.tools.forget_memory and registered via forget_memory.register(mcp, ctx) on line 132.
forget_memory, forget_source, get_document, get_entity, graph_memory, index_now, list_sources, pin_memory, query_timeline, related_documents, search_by_date, search_memory, summarize_source, sync_source, ) search_memory.register(mcp, ctx) list_sources.register(mcp, ctx) get_document.register(mcp, ctx) index_now.register(mcp, ctx) ask_memory.register(mcp, ctx) pin_memory.register(mcp, ctx) forget_memory.register(mcp, ctx) - Input schema for forget_memory tool: chunk_id (str in '<path>:<chunk_index>' format) and mode (Literal['suppress', 'cold'] defaults to 'suppress'). The return type is dict.
def forget_memory( chunk_id: Annotated[ str, "The chunk identifier to forget, in '<absolute_path>:<chunk_index>' format. " "Chunk IDs are returned by search_memory results.", ], mode: Annotated[ Literal["suppress", "cold"], "'suppress' (default) — hide chunk from search immediately via the " "forgotten_chunks suppression table. " "'cold' — demote to cold tier so the chunk's score decays gradually " "(requires memory tiers to be enabled).", ] = "suppress", ) -> dict: - Helper logic: imports check_access from auth_guard, enforces 'delete' permission, and delegates to metadata_store.forget_chunk() for suppress mode or tiered_memory.forget() for cold mode. Also logs cold-mode queries via audit_logger.
from memorymesh.server.auth_guard import check_access if (err := check_access(ctx, "delete")) is not None: return err if mode == "suppress": try: ctx.metadata_store.forget_chunk(chunk_id) except AttributeError: return {"error": "forget_chunk not implemented by this metadata store."} except Exception as exc: return {"error": str(exc)} return {"chunk_id": chunk_id, "mode": "suppress", "suppressed": True} # mode == "cold" if ctx.tiered_memory is None: return {"error": "Memory tiers are not enabled in the current configuration."} ctx.tiered_memory.forget(chunk_id) ctx.audit_logger.log_query( tool="forget_memory", query=chunk_id, n_results=0, latency_ms=0.0, ) return {"chunk_id": chunk_id, "mode": "cold", "tier": "cold", "pinned": False}