Forgetful Files

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.