#348·picoclaw

[Feature] General Attachment Support: Handling Files, Documents, and Media across Channels

Author: ZepanCreated Feb 17, 2026Updated Jun 19, 2026
Labelstype: enhancementpriority: hightype: roadmap

** The Goal / Use Case**

Enable PicoClaw to process various types of message attachments sent through IM channels (Telegram, Discord, etc.). This includes:

  • Textual Attachments: Reading logs, configuration files, or code snippets (e.g., .txt, .log, .yaml, .py).
  • Multimedia: Processing images, audio, or video files for multimodal tasks.
  • Data Files: Extracting information from PDFs or CSVs.

** Proposed Solution**

Implement a unified File Handling Interface that abstracts the attachment retrieval process. The goal is to allow the AI Agent to interact with files without knowing the specific underlying channel's API.

  • File Metadata Extraction: Automatically parse filename, MIME type, and size.
  • Lazy Loading: Do not download or load the file into memory until the Agent explicitly requests to "read" it.

** Potential Implementation (Optional)**

  • Stream-based Processing: Since we must maintain a <20MB memory footprint on 64MB RAM devices, large text files or logs must be read in chunks or streamed to disk.
  • Workspace Integration: Save attachments to a dedicated temporary directory (e.g., /tmp/picoclaw/attachments/) and provide the path to the Agent's context.
  • Path Sanitization: Ensure filenames are sanitized to prevent Directory Traversal or Shell Injection (VDP-002) when the Agent uses the ExecTool on these files.

** Impact & Roadmap Alignment**

  • This is a Core Feature: Expands the Agent's context beyond simple text strings.
  • This is a Nice-to-Have / Enhancement
  • This aligns with the current Roadmap: Crucial for the next phase of "Skill Expansion."

** Alternatives Considered**

  • Direct LLM Upload: Some LLM APIs support direct file uploads.

  • Downside: Most local/edge LLMs or specific channel gateways require local file pre-processing (like chunking a 10MB log file).

  • Base64 Encoding: Converting files to Base64 strings within the message.

  • Downside: This will instantly crash the process on a 64MB RAM board due to memory bloat.

** Additional Context**