add | MACHINE-MEMORY by JFA

Usage

machine-memory add <content> (--local|--remote)
machine-memory add --from-file <path> (--local|--remote)

add creates an active memory for the current repository. It can store tags, context, memory type, certainty, source agent, references, and an optional expiry window. The command checks for potential conflicts and, for status memories, reports older overlapping status entries that may need deprecation.

Use --upsert-match <query> when an existing strong match should be updated instead of creating a second memory:

machine-memory add "The API uses remote D1" \
  --upsert-match "remote D1 API" --type decision (--local|--remote)

The match is strong only when its similarity is at least 0.62 and its score reaches the threshold (--upsert-threshold <0-100>, default 32, override via the MACHINE_MEMORY_UPSERT_MIN_SCORE environment variable). When a record matches but fails that bar, add refuses to silently create a near-duplicate: non-interactive runs must pass --force to create a new record anyway, and interactive runs ask for confirmation. Preflight with --dry-run to see what would be matched:

machine-memory add "New wording" --upsert-match "topic" \
  --dry-run (--local|--remote)
# {"command":"add","dry_run":true,"action":"update",
#  "would_match":{"id":42,"score":88,"similarity":0.91,"content_head":"..."},
#  "size":{...}}

--dry-run never writes: without --upsert-match it prints the size report for a would-be create, and with it, the candidate plus the prospective merged-document size. It exits 1 when the text is over budget.

Options

--path enables path-driven tag suggestions. --tags and --context store retrieval metadata. --type accepts decision, convention, gotcha, preference, constraint, reference, or status. --certainty accepts verified, inferred, or speculative. --refs accepts JSON or CSV references, and --expires-after-days is useful for transient status.

--from-file and inline content are mutually exclusive. --no-conflicts suppresses conflict details; --brief, --json-min, and --quiet select smaller responses. A forced create over a weak match includes an upsert_match object in the response.

Embedding budget

Every memory is composed into a single embedding text that must stay below 512 BGE tokens and within the embedding service’s conservative byte+2 estimate (UTF-8 bytes plus two). Either limit alone rejects the write before anything is stored, and the error names the exact deficit plus a mechanical trim suggestion:

machine-memory add "long content..." --remote
# error: Memory has 534/512 embedding tokens; the embedding service byte
#        estimate is 1240/512.  content: 520 tokens ...
# Memory is over the 512-byte embedding estimate by 728 bytes.
#   Largest part: content (520 tokens).
#   Suggestion: ... (truncating content to ~403 bytes makes the byte+2
#   estimate fit)

Preflight any text without writing with size or add --dry-run. Pass --token-report to attach the same breakdown to a successful response (including with --json-min or --quiet), so agents can budget upcoming writes:

{"id": 42, "tokens": {"source": "tokenizer", "total_tokens": 26,
 "max_tokens": 512, "bytes_estimate": 108, "within_limit": true,
 "over_by": 0, "remaining": 485, "parts": [{"part": "content", "tokens": 8},
 {"part": "tags", "tokens": 8}, ...], "overhead": 8}}

When the BGE tokenizer cannot be fetched (for example offline), the gate degrades to the embedding service’s conservative byte+2 estimate and marks the breakdown "source": "bytes" without per-part counts.