| 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.
