Forgetful Files

---
name: forgetful-files
description: >-
  File binary content into the knowledge base — screenshots, PDFs, diagrams, fonts, assets.
  Use when a binary artifact is worth keeping alongside knowledge, or when a stored
  procedure needs a bundled asset. The description is the entire search surface: say what
  the file shows and when to reach for it.
license: MIT
tags: [files, binary, assets, multi-modal]
allowed-tools:
  - mcp__forgetful__discover_forgetful_tools
  - mcp__forgetful__how_to_use_forgetful_tool
  - mcp__forgetful__execute_forgetful_tool
  - Bash(forgetful:*)
---

# Filing binary content

Files carry what text cannot: the screenshot that shows the bug, the architecture diagram,
the PDF spec, the font a design system needs. Mechanics are thin; the judgment is in the
description and the attachment.

File operations are feature-flagged — when discovery doesn't list them, the server has
`FILES_ENABLED` off.

## Invoking operations

Operations are named by registry name (`create_file`, `list_files`, ...). Invoke via
whichever surface this agent has:

- **MCP**: `execute_forgetful_tool(tool_name="create_file", arguments={...})`
- **CLI**: `forgetful call create_file --args '{"filename": "..."}' --json`

Get any operation's schema at runtime: `how_to_use_forgetful_tool` (MCP) or
`forgetful tools info <operation>` (CLI) — schemas are deliberately not repeated here.

## Step 1 — Store with a retrieval-grade description

`create_file` takes the content base64-encoded, with `filename`, `mime_type`, tags, and a
description. The description is what future retrieval sees — write what the file shows and
when someone would reach for it ("Auth service architecture diagram — component boundaries
and token flow, current as of the v2 redesign"), never just restating the filename.

Done when: the file is stored and its description answers "what is this and when is it
used" on its own.

## Step 2 — Attach it

A file no path leads to is lost the moment this session ends. Two attachment routes exist:

- `project_id` (at create, or later via `update_file`) puts the file in a project's world.
- `link_skill_to_file` bundles it to a stored procedure as its asset (see
  `forgetful-procedures`).

For knowledge that *discusses* the file, save a memory (`forgetful-remember`) that cites
the file ID in its content, so recall surfaces the pointer.

Done when: at least one route reaches the file — its project, a linked procedure, or a
citing memory.