Keep the original PDF, spreadsheet or photo so you and your agents can find it again.
Open Knowledge in the app, open the folder it belongs in, and choose Add file, or drop a file on the page.
Say where it came from, pick who can see it, and choose Save file.
Find it later by searching for its filename in Knowledge. Choose Open to read it.
PDFs, spreadsheets, Word files, photos (JPG, PNG, WEBP, GIF), videos (MP4, MOV), audio (M4A, MP3) and text files up to 64 MB work. Photos, videos and audio play in the browser, and you can skip through a video.
More detail
This part describes the source-file release contract. Availability depends on the tools advertised by your connected Mainmind deployment. A tool listing is not proof that a file was saved: retain the returned saved receipt.
The browser and source helper accept PDF, XLSX, CSV, DOCX, PNG, JPG, JPEG, WEBP, GIF, MP4, MOV, M4A and MP3 files, plus UTF-8 Markdown, text, HTML, JSON, YAML and common script files, up to 64 MiB each. Each file's opening bytes must match its extension. Those upload paths refuse SVG because it can carry script. The Git drop folder keeps arbitrary types as attachments.
Context is extracted only from files up to 10 MiB. A larger file is saved and can be opened, but its extraction state is too-large and its contents are not searchable. Original bytes use private object storage. Git holds a source record for browser uploads or a pointer for files added with Git LFS. A checkout without LFS does not contain their bytes. Legacy files already stored in Git remain readable.
From the browser
In Knowledge, choose Add file, or drop a file onto the page. Choose its document type and access scope, describe where it came from, then choose Save file. Saving preserves the original; extraction, search readiness and human review are separate outcomes.
Find what you saved
Open a folder in Knowledge, or search across the space. Select a file to preview it, then choose Open to read the full document and its source. The breadcrumbs take you back through the folders. More options holds type filters and other details.
Folders follow the paths already saved in this space. Adding a file keeps its original and creates a source record; the folder you are browsing does not change where that record is saved. A folder that holds only files appears like any other folder, to people who can see those files. A folder shows its first 200 files and says how many it holds; search finds the rest.
From an agent
In the space shell or a prepared checkout, put files in the knowledge files/ folder, then use Git to add, commit and push them. Git LFS keeps a small text pointer in Git and uploads the bytes to Mainmind's private storage. Your checkout's usual write permissions still apply. Without a terminal, use mainmind.files.put in code mode for files up to 10 MiB, or Add file in Knowledge.
Read what Mainmind extracted from an original with search and the record's path. A query with that path keeps only the parts that contain it, and after continues from the cursor the answer gives. Check coverage and extraction state before relying on an excerpt. When extraction failed, the answer says why. A failure the bytes cause, such as a malformed CSV, is final; one that stopped before the file was read, such as while the space was busy, is tried again within the hour, up to three more times. Read the original resource when unchanged bytes are needed; it carries bytes inline for files up to 10 MiB. Fetch a larger original over HTTP or with the helper's fetch command. Search finds source records; do not assume every file's contents are indexed merely because the original was saved.
A host must expose the actual file bytes or an HTTP transfer mechanism. If it cannot, hand the upload to the browser instead. An attachment in an AI chat is not yet a Mainmind file.
From a checkout
Checkout setup configures Git LFS locally. The space shell includes it; on your own computer, install git-lfs if setup warns that it is missing, then rerun setup. Existing hooks are kept. If setup warns about a hook, add its named git lfs command to that hook before pushing files.
For a checkout whose knowledge is under knowledge/:
If knowledge lives at the repository root, use files/ instead. Every file in that folder uses LFS, including text. PDFs, images, office documents, audio and video also use LFS elsewhere in the checkout. These rules live in the shared Git directory's info/attributes; nothing is added to the space's tracked attributes.
Each file can be up to 64 MiB. Other file types can be kept in files/ as attachments, but may have no text extractor. Extraction reads at most 10 MiB. After Mainmind has read the push, search with the pointer's path returns its extraction state and any extracted text. The path's folder determines who can read it.
To confirm the original is saved independently of extraction, wait until the change lands on main, then make a fresh Mainmind checkout with LFS installed and open knowledge/files/invoice.pdf (or files/invoice.pdf in a root checkout). It should contain the original PDF, rather than the three-line pointer. In Knowledge, search for its filename and choose Open to download it once the push has been read.
Mainmind checkouts with LFS download the bytes through the same Git address. The GitHub copy contains pointers only, so it is not a backup of these bytes; a clone from GitHub alone cannot download them. Keep an explicit export of originals if you need an independent backup. Live checkout, shell and code-mode acceptance has not yet been verified across AI apps.
In code mode
The code tool exposes these methods as mainmind.files. No separate file MCP tool or source-helper sign-in is needed. The connection supplies who is calling; an agent acts with its owner's current access. Identity arguments are refused.
Method
What it does
files.put({ path, bytes, message? })
Saves a Uint8Array of up to 10 MiB and commits the same Git LFS pointer as a checkout. Use base64 instead of bytes for base64 text. Returns path, sha256, size, commit and extraction.
files.get({ path })
Returns path, bytes (Uint8Array), sha256, size and mime, up to 10 MiB. Also reads older records/source-docs/*.md originals.
files.list({ folder?, cursor? })
Lists readable pointer paths, up to 100 per page, with sha256, size, mime and extraction. Pass next_cursor as cursor until it is null. Older register pages are not listed.
Paths are relative to the knowledge root, as search shows them: for example, files/vendors/invoice.pdf. put accepts any regular file under files/, or a supported non-text extension such as PDF, PNG or XLSX elsewhere in the knowledge tree. A checkout's knowledge prefix is also accepted. Existing scope and write rules apply: a scoped writer may land only files its access permits.
const saved = await mainmind.files.put({
path: "files/notes.txt",
bytes: new TextEncoder().encode("Notes from today's work.\n")
});
const original = await mainmind.files.get({ path: saved.path });
return { sha256: original.sha256, size: original.size };
Not yet tested live in an AI app. Each call uses the connection's current access. Missing and unreadable files answer the same way; knowing a hash does not grant a download. Listing checks scope before returning paths.
Retrying the same bytes at the same path returns unchanged: true and makes no second commit. The same bytes at another path share one stored object. Extraction starts after the pointer is published; pending-publication means the commit is saved but the readable copy has yet to catch up. Saving does not mean the file's text is searchable yet.
For files over 10 MiB (up to 64 MiB), use git add, git commit and git push in a Mainmind checkout with Git LFS. To read one, use git pull in that checkout.
Existing helper exports
The helper commands below remain available only to processes that already hold a source-only capability privately as MAINMIND_SOURCE_URL and MAINMIND_SOURCE_TOKEN. Those capabilities expire after one hour, or after membership revocation takes effect. Git's helper does not fetch them.
Download the plain JavaScript helper from the connected Mainmind deployment's HTTPS /api/source-files/cli endpoint to mainmind-source.mjs. Inspect the saved helper before executing it. It uses Node and needs no executable bit.
The helper emits JSON results on standard output and progress on standard error. Downloads verify the fingerprint and refuse to overwrite existing files.
Exports include only selected authorized records and their originals, with a hash inventory and each record's source commit. They are not a complete backup. verify works offline without credentials; it checks local consistency, not a signed proof of authenticity. restore first verifies the export, then saves its originals as new records in the workspace selected by the source capability. It preserves each exported access scope; old exports without scope require explicit --scope. An explicit scope override remains subject to the workspace's access rules. Restore returns the old-to-new record receipts. It does not restore historical paths, roles, or complete space history.
Checkout delivery is where agents receive the proactive reminder to retain relevant originals and useful generated files within the task's authority, record why, and cite the saved reference. Mainmind does not automatically save every chat attachment or scan the user's disk.
Keep binary files out of Git
Use the prepared checkout's Git LFS setup for originals. The commit guard refuses raw binary bytes and keeps your staged files. If Git LFS was missing, install it, run git lfs install --local, stage the file again with git add --renormalize -- PATH, and retry the commit.
For a binary already in an unpushed commit, replace PATH and BRANCH with the file and branch named by the refusal:
This rewrites only commits not on that remote branch. For a new branch with no origin/BRANCH yet, exclude refs/remotes/origin/main instead (use the space's default branch if it has another name). Mainmind refuses raw binaries and pointers whose bytes have not arrived, including earlier commits in a push. If a pointer's bytes are missing, run git lfs push --all origin, then push again. A refused run-branch push may also keep a raw original separately; its answer names anything it kept.
To update an existing checkout with the current downloaded helper:
Terminal
node mainmind-source.mjs install-git-hook .
Files already in Git history are not migrated by this release. Removing one in a later commit does not remove its historical bytes.
Get a folder back into a checkout
A script that reads media from a checkout can pull a folder back first. Run it at the checkout's root:
Every saved file whose folder is that folder, or inside it, is written back at its path in the checkout under --to, after its fingerprint is checked: inside the space's knowledge folder, or at its exact old path for a file moved from a named folder beside it. A file already there with the same bytes is left alone. A different one is kept unless you add --replace yes. pull writes only into real folders: it refuses a folder or file that is a link. It needs the same MAINMIND_SOURCE_URL and MAINMIND_SOURCE_TOKEN as fetch.
Copy a folder
Folder copying was announced in What's new. Use it only when the connected deployment's helper advertises these commands. It retains selected current files, without Git history or ongoing synchronization. It needs no source repository after the copy.
First create a local preview. This step uploads nothing and needs no credential. Choose an existing destination space and review the listed paths, sizes and exclusions before copying. Keep the preview outside the selected folder.
The last three commands use the source capability described above. The copy refuses a different destination or files changed since preview. Repeat it with the same preview after interruption. Status lists remaining originals and any uncertain save; do not start another copy to bypass an uncertain result.
The copy sends every file first, and each is stored and checked against its fingerprint as it arrives. Then each commit saves the records of up to 20 files, the most one commit to the space carries, and one more saves the inventory: a 100-file copy is six commits. Until its commit, status shows each sent file as staged: its original is kept, but it has no record yet. A repeated copy sends only the files not yet stored. While the space is still reading a recent change, the copy waits and tries again by itself.
If the answer to one of those commits is lost, its files show as uncertain, and a repeated copy saves the other files but not those. Mainmind settles them from the space's history once that commit can no longer land, about 15 minutes after it began (a minute, if it never started publishing). Then status shows them saved, or staged again, and the next repeated copy commits them. No record is saved twice.
A copy contains at most 100 files and 100 MiB, with the 64 MiB per-file ceiling. Links, unsafe or colliding paths, credentials, known local caches and unsupported files are excluded or refused. Text is checked for credential patterns; this is not a guarantee that arbitrary documents contain no private information. Review the selection yourself. Excluded files can leave references unresolved.
Keep the returned inventory reference. On another host, recover-copy restores unchanged originals at their relative paths in a new folder and verifies their fingerprints. Existing files are never overwritten. Scripts and instructions remain retained evidence; copying them neither executes them nor changes the space's authority. Extraction and search readiness remain separate from storage.
From an HTTP client
A process already holding a source-only capability sends it as an HTTP authorization header to /api/source-files. Checkout no longer supplies that capability. Otherwise use mainmind.files.put in code mode (up to 10 MiB), Git LFS in a checkout, or Knowledge Add file. POST JSON with action: begin, append or finalize using the same fields as the MCP upload operation. GET that endpoint with upload_id or idempotency_key for status. Keep the original key when retrying an interrupted request.
A request turned away because the space was busy, or Mainmind was still reading its latest change, changed nothing. It answers HTTP 503 with a code and retry_after in seconds, also sent as the Retry-After header; repeat the same request after that. HTTP 409 is a real conflict, such as an operation key that already names another file. An upload whose save outcome was unknown, and that Mainmind can later show never reached the space, returns to uploading; finalize it again with the same upload_id.
GET /api/source-context?workspace=WORKSPACE&record=RECORD_PATH for context and GET /api/source-file?workspace=WORKSPACE&record=RECORD_PATH for original bytes, with the same source capability. These endpoints verify its workspace and live scope. The original endpoint answers one Range: bytes= request with 206 Partial Content, so audio and video can seek. Obtain a new capability through the original authorized connection when it expires; a Git credential or deployment bearer cannot substitute for it.