unpin_memory

Instructions

    The chunk stays in the hot tier until the next maintenance run, after
    which it will be promoted or demoted based on its access history.

    Args:
        chunk_id: Stable chunk identifier ``<path>:<chunk_index>``.

    Returns:
        Confirmation dict with ``chunk_id`` and ``pinned`` fields.
    

Implementation Reference

• src/memorymesh/server/tools/pin_memory.py:62-94 (handler)

  MCP tool handler function for 'unpin_memory'. Accepts a chunk_id, checks access permission ('index'), validates that tiered memory is enabled, calls ctx.tiered_memory.unpin(chunk_id), logs the query via audit logger, and returns a confirmation dict with pinned=False.

  @mcp.tool()
  def unpin_memory(
      chunk_id: Annotated[
          str,
          "The chunk identifier to unpin, in '<absolute_path>:<chunk_index>' format.",
      ],
  ) -> dict:
      """Remove the manual pin from a chunk, allowing normal tiering.
  
      The chunk stays in the hot tier until the next maintenance run, after
      which it will be promoted or demoted based on its access history.
  
      Args:
          chunk_id: Stable chunk identifier ``<path>:<chunk_index>``.
  
      Returns:
          Confirmation dict with ``chunk_id`` and ``pinned`` fields.
      """
      from memorymesh.server.auth_guard import check_access
  
      if (err := check_access(ctx, "index")) is not None:
          return err
  
      if ctx.tiered_memory is None:
          return {"error": "Memory tiers are not enabled in the current configuration."}
      ctx.tiered_memory.unpin(chunk_id)
      ctx.audit_logger.log_query(
          tool="unpin_memory",
          query=chunk_id,
          n_results=0,
          latency_ms=0.0,
      )
      return {"chunk_id": chunk_id, "pinned": False}

• src/memorymesh/server/app.py:131-131 (registration)

  Registration of the pin_memory module (which contains both pin_memory and unpin_memory tools) onto the FastMCP server instance.

  pin_memory.register(mcp, ctx)

• src/memorymesh/server/tools/pin_memory.py:64-67 (schema)

  Input schema for the unpin_memory tool: requires a single 'chunk_id' string parameter in '<absolute_path>:<chunk_index>' format.

  chunk_id: Annotated[
      str,
      "The chunk identifier to unpin, in '<absolute_path>:<chunk_index>' format.",
  ],

• src/memorymesh/storage/tiered.py:158-177 (helper)

  The TieredMemoryManager.unpin() method called by the handler. Retrieves the existing chunk tier record, sets pinned=False while preserving all other fields, persists to metadata store, and logs the action.

  def unpin(self, chunk_id: str) -> None:
      """Remove the manual pin from *chunk_id*, allowing normal demotion.
  
      The chunk remains in hot tier until the next maintenance run.
  
      Args:
          chunk_id: ``<path>:<chunk_index>`` stable identifier.
      """
      existing = self._store.get_chunk_tier(chunk_id)
      if existing is None:
          return
      record = ChunkTierRecord(
          chunk_id=chunk_id,
          tier=existing.tier,
          last_accessed=existing.last_accessed,
          access_count=existing.access_count,
          pinned=False,
      )
      self._store.set_chunk_tier(record)
      logger.info(f"TieredMemory: unpinned chunk {chunk_id!r}")