Files, PDFs and web sources

This page assumes you can already write plain notes, which Writing memory well covers. It is about the other kind of thing you can put in memory, which is a document you did not write yourself.

The same keep call handles all of it. What changes is whether you hand it text, a URL, or a local file.

Pass a URL and let aizk do the work

For one web page, PDF, or other supported file, give the original URL and no text at all.

aizk.keep(source_uri="https://example.org/binding-assay-protocol.pdf")

aizk fetches it once, scans the bytes, keeps the exact original unchanged, converts it to readable text, and queues that text for the ordinary pipeline. The call returns quickly with a receipt that says queued, because conversion happens in the background rather than while you wait.

Refreshing later is the same call with the same URL and the same scope, so a page you want to track does not turn into five near-identical notes.

When to preserve the original and when not to

Text is the preferred input. Most of the time what you want in memory is what a document said, and a note in your own words says it better and is cheaper to read.

Preserve the original when the exact bytes might be needed later. A contract, a signed record, a form, a paper you may need to cite by page, or a slide deck somebody will want to open again all qualify. A blog post explaining an idea you already understood does not.

If you have a URL but only want the text of your own reading of it, pass both text and source_uri and leave preservation off. That records the link on your note without keeping a copy of the file.

aizk.keep(
    text="# Assay protocol, the parts that matter\n\nIt fixes incubation at 37 C for nine hours ...",
    source_uri="https://example.org/binding-assay-protocol.pdf",
)

Companion text alongside a file

When both the file and your explanation belong to the same document, pass both and turn preservation on. The text is stored as companion context on the same revision, so find can return your framing together with the converted contents rather than as two unrelated notes.

aizk.keep(
    text="Primary reference for the current retrieval design. Section 4 is the part we implemented.",
    source_uri="https://example.org/paper.pdf",
    preserve_source=True,
)

Local files

There is no upload button in the web app. A local file goes in either through the aizk command line tool, which handles the whole flow itself, or through a client that implements the upload handshake.

aizk keep report.pdf notes.md --text "Primary references for the current design."

An assistant doing it through the tool declares the exact filename, media type, byte size and checksum, and gets back a short-lived, single-use upload address rather than a stored document. It then sends exactly the declared bytes to that address once. Treat that address like a password, because anyone holding it before it expires can perform its one upload.

What happens when conversion fails

Some things cannot be turned into text, and aizk does not silently drop them. The original is still stored and a note is still created from what is known, which is the filename, the size, the media type, the source URL, the conversion state, and any companion text you passed.

That note is findable. So a file that failed to convert is still findable by name and still tells you it exists, and the exact bytes are still there when you go looking. In the web app it shows a failed badge on the processing screen rather than disappearing.

The two size limits

There are two numbers, and they are different, so it is worth knowing both. The storage layer accepts an object up to 96 MiB, but the malware scanner reads only up to 10 MiB.

Plan around 10 MiB

Every file is scanned before anything is stored, and the scan is fail-closed, so anything the scanner will not or cannot clear is rejected rather than let through. ClamAV in the default deployment is set to 10 MiB, so a 40 MiB file sits under the 96 MiB ceiling, is rejected as too large by the scanner, and never lands. The 96 MiB figure is the theoretical ceiling, and you will meet the scanner first.

Do not split a file into pieces to get under the limit. Split parts lose the thing that made the original worth preserving, which is that it is the original, and they turn one document into several sources that find then has to reassemble. Store a note describing what the file is and where it lives instead.

Getting the original bytes back

Find stays text first. When an evidence item is grounded in a stored file, it can name the exact revision of that file as a resource your assistant can read.

  Resource `aizk://artifacts/019b2d0a-.../contents/019b2d0a-...`

Read it only when the task genuinely needs the original bytes, such as quoting a contract clause exactly. It always names the exact revision that produced the evidence, and it is checked against your current visibility before a single byte moves.

Next

• The web app shows conversion progress and failed originals.
• Sources and derived knowledge explains what conversion feeds.
• Notes that stay useful covers when a file beats a note.