Build tools from files

A tool can be a folder of Markdown files with an index and instructions for reading and updating them. Start with files when that meets the task; add scripts only when the requested behavior needs them. See the FlashDrive workflow reference for detailed patterns.

Markdown knowledge and memories

Use readable file names, relative links, and an index for a wiki, project knowledge, or a memory collection. Keep instructions in the file your client reads, or ask the agent to read it explicitly. FlashDrive does not execute Markdown instructions or make every client load them automatically.

Folders do not provide privacy. Check workspace membership and drive access before storing individual memories in shared content. A separate drive alone does not hide files from workspace members or administrators with inherited access.

CSV records with stable IDs

For trackers or other structured tools, use a lowercase id column with a stable UUID generated once for each new record. Save that ID before retrying a write, and reuse it for the same operation. Do not renumber rows, derive IDs from positions or editable text, regenerate IDs on reload, or reuse a deleted ID.

The mounted client merges CSV changes from a common synced base when the header stays fixed, IDs are stable, retained rows are unchanged, and new rows are appended. Deleting an existing row while another writer adds a new row preserves the deletion and the addition. Reordering or editing retained rows falls outside that automatic merge rule and can produce a conflict copy. Direct API byte writes still require revision checks.

Keep each file version and merged result within 8 MiB and 10,000 data rows, with at most 128 Ki characters per field. Preserve conflict copies when a change exceeds the merge rules. Test two copies from the same synced base when building your tool: concurrent additions must retain both records, and deletion plus addition must not bring the deleted record back.

For editable records, the tools skill describes an append-only operation history and explicit conflict handling. Do not treat conflicting edits or delete-versus-edit as a successful automatic resolution. Keep pending changes until remote persistence is confirmed.

SQLite

Automatic SQLite merging is planned and is not available yet. Use one writer for a shared SQLite database, including its journal and WAL files. Do not assume a mounted file is a cross-device lock or transaction.