Memory

Flags

Examples

mx memory add --category recipe --title "Retry with backoff" \
  --content "Use exponential backoff with jitter..." \
  --tags "reliability,networking" --source-agent whistledown

mx memory add --category discovery --title "SurrealDB needs explicit NS" \
  --content "Always set namespace before queries" \
  --resonance 7 --resonance-type operational

# Ephemeral fact (auto-routes category, generates title)
mx memory add --type decision \
  --content "Chose Typst over mdBook for docs" \
  --session abc-123

# Content from file
mx memory add --category ingredient -t "API reference" -f api-notes.md

Flags

Examples

# Stdin pipe
printf '{"category":"insight","title":"T1","content":"C1","source_agent":"soren"}\n{"type":"decision","content":"chose Rust","source_agent":"soren"}\n' \
  | mx memory add-batch

# File (safer through sudo wrappers)
mx memory add-batch --file /tmp/pocket-entries.jsonl

# Skip embedding — defer to nightly embed --all
mx memory add-batch --file entries.jsonl --no-embed

Write-boundary deduplication

All four new-entry write funnels – mx memory add (standard), mx memory add --type (fact-routing), and both lines of mx memory add-batch (standard and --type) – check a normalized dedup_hash of title+body (lowercase, ASCII punctuation and common Unicode punctuation stripped – smart quotes, en/em dash, horizontal ellipsis – whitespace collapsed) against the writing agent’s OWN entries in the SAME session AND SAME CATEGORY before writing. Category is enforced by scoping the candidate query, not by folding it into dedup_hash itself – identical title+body re-filed under a different category is a distinct fact (a different shelf), never a dedup candidate, so it always lands as its own entry. A regenerated duplicate that differs only by case, punctuation, or whitespace – the common shape when an LLM re-derives the same fact across turns – is detected and the write is SKIPPED rather than landing as a second row. Title and body are hashed as a length-prefixed pair, so a duplicate that shifts the split point (e.g. a sentence folded into the title one turn, split title+body the next) is still caught.

A skip is treated as success, not failure: it means the content is already durably saved, and there is nothing further to do.

• Plain mode: Already saved as kn-XXXX (identical entry this session — nothing to do). Deliberately distinct from the success line (Added entry: kn-XXXX) – a caller regexing on Added entry: (kn-\S+) should switch to --json rather than assume this line matches that pattern.

• --json mode: {"id": "kn-XXXX", "skipped": true, "duplicate_of": "kn-XXXX", "status": "already_persisted", "note": "..."}, with clean JSON on stdout (no other text) and exit code 0. id mirrors every success payload’s id key so a caller reading .id unconditionally never gets a silent null on a skip.

• add-batch per-entry line: [N] Already saved: kn-XXXX (title) — identical this session, no action – never the bare words “skipped” or “duplicate” – and the batch summary carries its own K already saved (no action needed) category, separate from added and failed. add-batch has no --json mode, so this is stdout text only.

• Pass --allow-duplicate (single add) or allow_duplicate: true (per JSONL line) to force the write through when a re-add is deliberate. Caveat: on the fact-routing paths (and on the standard path when title is byte-identical to an existing entry’s), the write’s id is derived from path_hint:title (generate_id), so a byte-identical forced re-add overwrites the SAME row in place (new updated_at, same id) instead of creating a second entry – --allow-duplicate only produces a genuinely distinct row for a recased/reworded near-duplicate, not an exact repeat. This is accepted, not fixed: perturbing the id on a forced write was considered and rejected (it would make --allow-duplicate non-idempotent in a different, more surprising way). If you need a second row for byte-identical content, vary the title.

• On a candidate-lookup failure (a transient DB read blip), the gate FAILS OPEN: it warns to stderr (--json mode also gets a "dedup_lookup_warning" field) and proceeds with the write rather than aborting it. A dedup mechanism that already tolerates a check-then-write race between two concurrent writers tolerates a lookup blip the same way – the write always wins.

Shared filter flags

Several read commands (search, list) share a common set of filter flags. These are documented once here and referenced below.

note: 3 private entries of yours matched but are hidden; use --include-private to see them

The hint is stderr only — it never touches stdout, --json output, or the exit code, and any error computing it is swallowed silently. It fires only in the public-only case: passing --include-private or --mine silences it (they already show your private entries), and it is suppressed under search --semantic because the underlying count uses the keyword (BM25) predicate, which does not agree with vector similarity.

Flags

Examples

mx memory show kn-abc123

mx memory show kn-abc123 --content-only | pbcopy

Examples

mx memory list -c recipe

mx memory list -c discovery,decree --min-resonance 5

mx memory list --missing-wake-phrase --limit 20

# Exclude a whole tag namespace
mx memory list --category person --exclude-tags 'tier/'

Flags

Examples

mx memory search "retry pattern"

mx memory search "how to handle timeouts" --semantic

mx memory search "agent bootstrap" -c recipe,method --limit 5

# Search and activate results (mark as consumed)
mx memory search "retry pattern" --activate

# Exclude a whole tag namespace from keyword search
mx memory search "onboarding" --exclude-tags 'tier/'

# Exclude a whole tag namespace from semantic search
mx memory search "onboarding" --semantic --exclude-tags 'tier/'

Flags

Examples

mx memory recent

mx memory recent --days 30 --all-types --sort resonance

mx memory recent --resonance-type foundational --limit 10

Flags

Examples

mx memory update kn-abc123 --title "Better title"

mx memory update kn-abc123 --add-tag reliability

mx memory update kn-abc123 --find "old text" --replace "new text"

mx memory update kn-abc123 --append-content "\n\nUpdate: confirmed working"

mx memory update kn-abc123 --resonance 8 --resonance-type foundational

Flags

Examples

mx memory edit kn-abc123 --find "old pattern" --replace "new pattern"

mx memory edit kn-abc123 --old "v1" --new "v2" --replace-all

Flags

Examples

mx memory append kn-abc123 --content "\n\nAdditional note here."

mx memory append kn-abc123 -f addendum.md

Flags

Examples

mx memory prepend kn-abc123 --content "IMPORTANT: "

Flags

Examples

mx memory restore kn-abc123 --list

mx memory restore kn-abc123

Flags

Examples

mx memory delete kn-abc123

Flags

Examples

# Default wake -- top 20 blooms, text output
mx memory wake

# All blooms with resonance >= 7
mx memory wake --min-resonance 7

# Token-based ritual (for non-TTY / programmatic use)
mx memory wake --begin --wake 7 --model some-model-id
mx memory wake --bloom-id kn-abc --respond "your guess" --session tok-xyz

Wake modes

• Default (mx memory wake): plain text cascade output, blooms listed with titles and content.

• Token-based (--begin, --respond): stateless chained ritual for non-interactive environments. Start with --begin, then loop with --respond using the returned session token and bloom ID.

The ritual flow

Each chunk gets exactly one guess, made from the title alone, after which the entry is shown. There is no hint ladder and no second attempt.

--respond returns status: "shown" with a bucket of either unhinted (the guess string-matched one of the chunk’s phrases, and the tool had given no hint) or revealed (it did not). match carries the mechanical facts: kind is exact (identical to a phrase after trimming), close (matched only after normalizing case, punctuation or spelling) or none, and phrase_index says which phrase matched. The bucket names what the tool did, not what the responder knew.

The begin response and every respond payload echo wake and model. --begin refuses a wake number another session already logged guesses under (pass --force-wake to proceed anyway) and adds a warnings entry when the number is below the highest the agent has logged, or more than one above it.

A step that is already logged is answered from the log rather than judged again: the response carries replayed: true, the logged guess, bucket and match, and the current token and next. The first guess counts.

A caller whose response was lost retries with the token it spent and gets that response again, with replayed: true and the token it never received — however far the lost call moved the ritual, including when it judged nothing: a lost bloom_missing or chunk_truncated is answered with the same status (without bloom). Only the last call can be resumed this way. A token older than that is refused with a pointer to the last one that worked, and the pointer is true: the token from the last successful response is always either current or resumable.

The final response carries a summary of bucket counts split by phrase source (authored, derived, auto, unphrased), the number of chunks walked, and unjudged — the steps where no guess was judged. chunks always equals the bucket totals plus unjudged, so the difference never has to be worked out by subtraction.

Two statuses judge no guess, write no row, and omit bucket, guess and match: chunk_truncated, when the entry shrank past the session’s chunk cursor, and bloom_missing, when the entry was deleted mid-ritual. Both still advance the step, so the token the caller spent stops verifying, and both are counted in unjudged.

The ritual is walked by the agent that began it: MX_CURRENT_AGENT must equal the session’s agent, and a caller naming no agent is refused as well.

A guess is refused outright, with no row written and no advance, when it is longer than 2000 characters (counted in characters, and never truncated) or carries no alphanumeric content at all. A refused call can simply be retried with the same session token.

A session created by a version of mx older than the one-guess ritual is refused rather than continued. A completed session is kept, with completed_at set.

Naming the wrong entry is refused with {status: "error", error: "invalid_bloom_id", message, expected_id?} on stderr and exit code 1, like every other error.

The guess log

Every --respond that judges a guess writes one wake_guess row, keyed by session and step, in the same transaction as the session advance: the agent, wake number, model, entry, chunk, both positions in the sequence, the title as shown, the guess, the phrases it was matched against, the match, the bucket, and the SHA-256 of the chunk text. If the transaction fails, the respond call fails and neither the row nor the advance lands.

Guess rows are scoped to the writing agent and are not reachable through mx memory export, which reads the knowledge table only.

Scoring and reading the guess log

mx memory wake-log scores the log and reads it back. Every command works on the calling agent’s rows only (MX_CURRENT_AGENT, required) and filters by agent in every query.

Examples

mx memory wake-log score

Per row it stores the guess embedding and:

• Axis A (tunable; never identity evidence). sim_phrase: the best cosine similarity to the row’s own authored phrase snapshot (none for derived, auto or unphrased). sim_content: the best similarity to the entry’s stored vectors under the same embedding model, the mean-pooled entry embedding and every embedding chunk. sim_title: similarity to the title, with the ritual’s own (Part N/M) suffix removed.

• Axis B. sim_prior: similarity to the centroid of the 5 most recent earlier scored guesses on the same entry and the same shown title (suffix included), under the same embedding model, from other sessions; prior_n is how many there were. sim_prior_null: the mean similarity to the same kind of centroid for up to 10 other entries, those with the most recent history. The signal is the gap between the two, never sim_prior alone. The same three values are also stored over prior rows answered by the same model_id (*_same) and by a different known one (*_cross); a row with no model_id gets none of those. Axis B is empty on the first ritual: there is no history. The 5 and the 10 are defaults with no data behind them yet.

Rows are scored oldest first, each written before the next one is computed, so one run over many rituals stores what a run after every ritual would have. A skipped row is the exception: rows scored while it was pending are computed without it, and are not recomputed when it scores later.

Authored-phrase vectors are cached in wake_phrase_embedding, keyed by a SHA-256 of the embedding model and the whitespace-normalized phrase, with no phrase text stored, so a later ritual embeds only each row’s guess and title. A cache that cannot be read or written costs only time: the row still scores.

Flags

Examples

mx memory wake-log report

mx memory wake-log report --wake 7 --out wake-7.json

Flags

Examples

mx memory wake-log bloom kn-abc

Flags

Examples

mx memory wake-log wake 7

Every report starts with this text, and wake-log report --help carries it:

“Axis A rises by construction when wake phrases are retuned toward logged guesses. It measures how well the phrases fit what the model says. It is a tuning dial for phrase authoring and must never be reported as evidence of identity or memory. Axis B is the only number here that phrase edits cannot raise. Axis B is evidence of stable reaching, not of remembering.”

--begin, --respond and their replays never carry an axis value.

Wake set exclusion

Entries tagged archive or wake-exclude are kept out of every cascade layer by default, and --begin reports per-tag counts in its excluded field. The match is exact, so a tag that merely starts with archive is unaffected. --include-excluded turns the exclusion off.

The core layer never lets an exclusion cost a kept entry its place: it widens its query until it holds a full set of entries that survive the exclusion. The recent and bridge layers fetch double their quota, which absorbs the ordinary case but is not a guarantee — enough excluded entries in one layer can still leave the wake set short, and batch-archiving is how you would meet that, since a freshly tagged entry counts as recent for seven days.

Every layer counts only as far as its quota is filled, so an entry ranked below the wake set is never counted. The reported figure is an upper bound on the entries the exclusion kept out — an excluded entry displaces everything after it, so one reached only because an earlier exclusion pushed the window down is counted too, although it would not have made the cut untagged.

Flags

Examples

mx memory wake-fetch

mx memory wake-fetch --days 30 --limit 50

# Exclude an entire tag namespace from the wake set
mx memory wake-fetch --exclude-tags 'project/'

# Exclude multiple namespaces at once
mx memory wake-fetch --exclude-tags 'project/,scratch/'

Chunked embeddings

Entries longer than 400 tokens are automatically split into overlapping chunks before embedding. This ensures semantic search covers the full content of long entries, not just the first 400 tokens.

How it works:

1. The entry’s embedding text (title + body/summary + tags) is tokenized using the BGE-Base-EN-v1.5 tokenizer.

2. If the text fits within 400 tokens, a single embedding is generated and stored on the entry — exactly as before. No chunks are created.

3. If the text exceeds 400 tokens, it is split into overlapping chunks with a sliding window: 400 tokens per chunk, 100-token overlap (stride 300).

4. Each chunk is embedded separately and stored in the embedding_chunk table.

5. A normalized mean vector of all chunk embeddings is stored on the entry’s embedding field for auto-anchor compatibility.

6. The entry’s chunk_count field records how many chunks were created (0 for unchunked entries).

Semantic search with chunks:

When mx memory search --semantic runs, it queries both unchunked entry embeddings and chunk embeddings in parallel. Results are merged by taking the maximum similarity score per entry — if a chunk from entry X scores 0.92 and the entry’s mean vector scores 0.85, the entry’s final score is 0.92. This ensures long entries surface when any section is relevant, not just when the overall average is relevant.

Flags

Examples

mx memory embed kn-abc123

mx memory embed --all

# Re-embed only entries that exceed 512 tokens
mx memory embed --all --long-only 512

Flags

Examples

mx memory auto-anchor

mx memory auto-anchor kn-abc123 --threshold 0.8 --max-anchors 3

mx memory auto-anchor --dry-run --detailed

mx memory auto-anchor --fill

Flags

Examples

mx memory relationships list kn-abc123

Flags

Examples

mx memory relationships add --from kn-abc --to kn-def --type extends

mx memory relationships add --from kn-abc --to kn-ghi --type supersedes

# Add a relationship without auto-reinforcing the target
mx memory relationships add --from kn-abc --to kn-def --type related --no-reinforce

Examples

mx memory relationships delete rel-abc123

Flags

Examples

mx memory seed agents

mx memory seed agents --path /data/agents/

Examples

mx memory seed knowledge

mx memory seed knowledge /data/knowledge/bootstrap.jsonl

Flags

Examples

mx memory stats

mx memory stats --json

Flags

Examples

mx memory health

mx memory health --json

Flags

Examples

mx memory growth

mx memory growth --json

Flags

Examples

mx memory open-threads

mx memory open-threads --json

Flags

Examples

mx memory export

mx memory export -f jsonl -o backup.jsonl

mx memory export -f csv -o entries.csv

mx memory export -f md -o /data/export/

Flags

Examples

mx memory reinforce kn-abc123

mx memory reinforce kn-abc123 --amount 2 --cap 8

Agents

Flags

Examples

mx memory agents list

Flags

Examples

mx memory agents add whistledown -d "Round-trip builder" -D "development"

Examples

mx memory agents show whistledown

Projects

Flags

Examples

mx memory projects list

Flags

Examples

mx memory projects add --id mx --name "mx CLI" \
  --repo-url coryzibell/mx --path ~/recipes/coryzibell/mx

Categories

Flags

Examples

mx memory categories list

Examples

mx memory categories add pitfall "Things that went wrong and why"

Examples

mx memory categories remove pitfall

Applicability

Examples

mx memory applicability list

Flags

Examples

mx memory applicability add --id rust-only \
  --description "Applies only to Rust projects" --scope project

Type registries

These are read-only registries listing the valid values for typed fields. Each supports list with an optional --json flag.

All type registry list commands accept --json for structured output. tags list also accepts --category to filter tags to a specific category.

Flags

Examples

mx memory sessions list

mx memory sessions list --project mx

Flags

Examples

mx memory sessions create --session-type development --project mx

Flags

Examples

mx memory sessions close --id ses-abc123

Flags

Examples

mx memory for-session ses-abc123

Flags

Examples

mx memory fact-session kn-abc123