@moxxy/plugin-memory is moxxy's long-term memory layer. It stores one Markdown file per memory under ~/.moxxy/memory/ plus a MEMORY.md index. Short-term memory is a fold over the current session's event log.

How memories get saved

The plugin contributes five tools (packages/plugin-memory/src/index.ts):

Tool	Purpose
memory_save	Persist a memory (name + type + description + body). Requires approval.
memory_recall	Search by free-text query (TF-IDF or vector).
memory_list	Names + descriptions (no body).
memory_forget	Delete by name.
memory_update	Update in place (preserves createdAt).

The agent calls memory_save when you give it instructions to remember something. Recall happens implicitly on relevant prompts via the discovery skill.

Recall modes

memory_recall takes a mode:

Mode	Behavior
auto	TF-IDF baseline; upgrades to vector if an embedder is configured.
vector	Force vector similarity (requires an EmbeddingProvider).
keyword	Plain substring + token-overlap match.

Embedders ship as separate plugins:

• @moxxy/plugin-embeddings-openai — text-embedding-3-small/large.
• @moxxy/plugin-embeddings-transformers — local CPU via @huggingface/transformers.

Both wrap automatically in @moxxy/sdk's CachedEmbeddingProvider (disk cache at ~/.moxxy/memory/.embeddings/).

Manual curation

moxxy memory list                     # name · type · description
moxxy memory audit                    # full audit: size, dates, tags by type
moxxy memory show <name>              # print the body
moxxy memory revert <name>            # delete one entry
moxxy memory prune-stale --days 90    # delete entries not touched in N days
moxxy memory path

Consolidation

planConsolidation() (exported from @moxxy/plugin-memory) detects overlapping memories and proposes a merge. The optional consolidate plugin runs this periodically. See packages/plugin-memory/src/consolidate.ts.

Short-term memory

recentExchanges(log, n) and summarizeSession(log) (also exported) fold the session's event log into context-window-friendly summaries. The compactor uses similar primitives to drop old turns when the budget hits the threshold.

Types

MemoryType is one of note, preference, fact, decision, lesson. The type drives which folder the file lands in and is used as a filter in memory_list / memory_recall.

Storage layout

~/.moxxy/memory/
  MEMORY.md               human-readable index (one line per memory)
  note/<slug>.md
  preference/<slug>.md
  fact/<slug>.md
  decision/<slug>.md
  lesson/<slug>.md
  .embeddings/            cached vectors (created on first vector recall)

Each entry is plain Markdown with YAML frontmatter — git-friendly, hand-editable, and survives schema changes via parseMdFile.