---
title: "size"
description: "Preflight the embedding budget for a prospective memory."
---

> Documentation Index
> Fetch the complete documentation index at: https://machine-memory.jfa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# size

## Usage

```sh
machine-memory size <content> (--local|--remote)
machine-memory size --from-file <path> (--local|--remote)
```

## Embedding budget

`size` reports whether a prospective memory would pass the embedding budget
**without touching the database**. It composes the embedding text exactly like
an `add` would (content plus tags/context lines plus fixed type/status/certainty
lines) and reports both limits independently:

Every memory's composed embedding text must stay **below 512 BGE tokens**, and
its conservative byte estimate (**UTF-8 bytes + 2**) must be **at most 512**.
Either limit rejects the write before anything is stored.

Use these commands to preflight without writing:

```sh
machine-memory size "<text>" --remote
machine-memory add "<text>" --dry-run --remote
machine-memory update <id> "<text>" --dry-run --remote
```

Pass `--token-report` to a real `add` or `update` to include the per-part token
breakdown. When a memory exceeds the budget, the error states the exact byte or
token deficit and suggests a mechanical trim.

```json
{
  "source": "tokenizer",
  "total_tokens": 16,
  "bytes_estimate": 72,
  "limits": {
"tokens": { "value": 16, "limit": "below 512", "pass": true },
"bytes_estimate": { "value": 72, "limit": 512, "pass": true }
  },
  "within_budget": true,
  "binding_limit": null,
  "over_by_tokens": 0,
  "over_by_bytes": 0,
  "parts": [{ "part": "content", "tokens": 4 }]
}
```

## Exit code

The command exits `1` when either limit fails, so scripts can preflight writes:

```sh
machine-memory size "$(cat long-note.txt)" || echo "would be rejected"
```

When over budget, the report includes `largest_part` and a mechanically derived
`trimmed_suggestion` — an exact UTF-8-safe truncation when the byte+2 estimate
binds, or an approximation labeled as such when tokens bind.

## Options

`--tags`, `--context`, `--type`, and `--certainty` are honored so the composed
text matches the real write. `--from-file` reads content from a file. The
backend flag is accepted for invocation symmetry but no database is accessed.

Source: https://machine-memory.jfa.dev/machine/size/index.mdx