slm-media

Files (1)

• SKILL.md

SKILL.md (first lines)

# slm-media — Pictures, PDFs and Folders

SuperLocalMemory can keep a picture or a PDF as a memory and find it later by
describing what it shows or what it says. A picture model runs on this
computer (EmbeddingGemma 2). OCR reads the text inside pictures. Each PDF
page is indexed by its picture and by its text. No generative model looks at
the files, so SLM cannot describe a picture to you: it finds it, and you look
at the thumbnail it returns.

This feature is **off by default**. Pictures live in their own database
(`media.db`); turning it on does not change any existing memory or embedding.

---

## When to save a picture or a PDF

Save one when the user asks, or when the file is itself the thing worth
finding again: a screenshot of an error they will meet again, a diagram of a
design decision, a receipt, a scanned page, a PDF spec. Do not save a file
just because it was shown in the conversation.

Add words with `content`. The picture is found by what it shows, by the text
read inside it, and by the words you add, so a short sentence about why it
matters ("Staging dashboard after the Postgres 17 move") helps recall.

Never save a picture or PDF that shows a password, key, token, card number,
government id or private data about a third party. The text read from a file
is scanned like any saved text, but a screenshot of a secret should not be
saved at all. Ask the user first if you are unsure.

---

## Are the tools there?

The five tools below are listed only while pictures and documents are on, and
only in the `full`, `power` and `whole` MCP tool sets. They are not in `core`
or `code`. The tool set is fixed when the MCP server starts, so after the
feature is turned on, restart the MCP session (`slm restart` starts the
picture worker too). Do not guess: run

```bash
slm media status
```

It says whether the feature is off, set up, still setting up, or failed
(`slm doctor` explains a failure). The same status is in the dashboard under
**Documents & Images**.

### Turning it on (ask the user first)

```bash
slm media enable    # shows the download size and a disk check, then asks; --yes skips the question
```

Turning it on downloads about 1.5 GB of models and tools, and needs a
computer with 16 GB of memory (the check passes from 15 GiB). On a smaller
computer `enable` refuses with the reason and exits with code 4; text memory
keeps working. Never turn it on, or pass `--yes`, without the user saying
yes in this conversation. Never set `SLM_MEDIA_ALLOW_LOW_RAM=1` yourself: it
removes the memory check and the owner must decide that.

Supported: macOS on Apple Silicon, Windows x64, Linux x86_64 and Linux ARM64
(aarch64), Python 3.12 to 3.14. Not supported: Intel Macs and Windows on ARM.

Other commands:

```bash
slm media status              # what is on and how set-up is going
slm media disable             # off again; memories are kept (--remove-files also deletes the downloaded models)
slm media gc                  # report picture records without a memory and files without a record; removes nothing
slm media gc --apply          # remove them (owner or admin); never touches SLM's databases
slm media repair --dry-run    # count pictures that cannot be found by what they show yet
slm media repair              # re-embed them (owner or admin); run again if it says pictures are left
```

All take `--json`. Run `slm media repair` when a save says a picture "can't be
found by what it shows yet", or after the picture model changed.

---

## Tool reference

### `remember_media` — save a picture

```
remember_media(
  path: str = "", download_url: str = "", base64: str = "", file = None,   # give exactly one
  content: str = "", tags: str = "", profile_id: str = "",
  idempotency_key: str = "", scope: str = "", shared_with: str = "",
) -> dict
```

Give exactly one of `path` (a file on this computer), `download_url` (an
https link), `base64`, or `file` (a picture attached in a ChatGPT chat;
ChatGPT fills it in, never write it by hand). Two or none is refused
(`invalid_request`). `scope` (personal, project, shared, global) and
`shared_with` (comma-separated profile ids) work as in `remember`: leave them
unset unless the user asked to share. Formats: PNG, JPEG, GIF (first frame)
and WebP.

Returns `success`, `status`, and on success a `media_id` and a `resource`,
`slm://media/<media_id>`. Report what the tool returned; do not say "saved"
unless `success` is true.

### `remember_document` — save a PDF

```
remember_document(
  path: str = "", base64: str = "", download_url: str = "", file = None,   # give exactly one
  file_name: str = "", content: str = "", tags: str = "", profile_id: str = "",
  idempotency_key: str = "", scope: str = "", shared_with: str = "",
) -> dict
```

Same sources and rules as `remember_media`, for a PDF. The work continues in
the background; the answer has a `job_id` (and `document_id`). Follow it with
`media_status`. Each page is indexed by its picture and its text layer.

### `media_status` — follow a document

From qualixar/superlocalmemory, AGPL-3.0.

More from qualixar/superlocalmemory