using-mem

name: using-mem description: Use when starting a coding session, making design decisions, fixing bugs, or when the user asks to remember or recall something — manages persistent memory via the mem CLI across project and global scopes

Using mem

Overview

Use the mem CLI to persist knowledge across sessions. Recall before working, store at milestones. mem is a Git-powered key-value store with branching, history, and semantic search.

Recall Phase (Session Start)

Before touching code, ensure stores exist and load relevant context:

# Ensure both stores exist
mem status || mem init                  # project-local .mem/
test -d ~/.mem || mem init --global     # global ~/.mem

# Load project context
mem list arch/                          # architecture decisions
mem list bugs/                          # known bug patterns
mem list onboard/                       # onboarding context
mem list ctx/                           # project context
mem search -s "<your current task>" -n 5  # semantic search (if embedder available)

# Load global context
mem list prefs/ --scope global          # user preferences
mem list patterns/ --scope global       # cross-project patterns

Read anything relevant with mem get <key>. Synthesize into working knowledge before proceeding.

If semantic search fails with "embedder not available": The embedding model could not be loaded. Fall back to keyword search (mem search "<query>" without -s). To fix: ensure the GGUF embedding model is downloaded to ~/Library/Caches/mem/models/ and the .mem/config.yaml points to it. The default model (nomic-embed-text-v1.5) is public and requires no token.

Store Phase (At Milestones)

After a design decision, bug fix, pattern discovery, or on user request:

1. Pick the right prefix and scope from the table below
2. mem set <prefix>/<kebab-case-topic> "<concise content>" (auto-commits)
3. For batch changes, use mem commit -m "remember: <brief description>" after multiple edits
4. If semantic search is configured: mem index rebuild

Key Convention

For global scope, add --scope global to set/get/list commands.

Content Format

Store concise, actionable statements — not narratives.

Architecture: Decision, rationale, alternatives rejected, date. Bugs: Symptom, root cause, fix, what to watch for. Context: Concise factual description. Onboarding: What a new contributor needs to know, key file paths. Preferences: Concise preference statement.

Seeding Memories

When starting a new project or onboarding, bulk-load context into mem:

mem init                                            # if not yet initialized
mem set ctx/architecture "Go CLI with cobra..."
mem set ctx/deps "Vendored deps, do not run go mod vendor"
mem set arch/auth "JWT-based, refresh tokens in httpOnly cookies"
mem set prefs/style "table-driven tests" --scope global

This gives future sessions immediate context without manual recall.

Git Hook Integration

mem install adds a post-commit hook that automatically captures structural changes from every commit into memory. This builds a project changelog without manual effort.

Prerequisite: The project must have a .git/ directory (git init if needed).

# Install the hook (default: extract strategy, no LLM needed)
git init                                            # if no .git/ exists yet
mem install

# Install with all strategies (extract + LLM summarize + custom script)
mem install --strategy all --script ./hooks/my-hook.sh

# Overwrite an existing hook (backs up original)
mem install --force

# Remove the hook
mem uninstall

Strategies:

Hook results are stored under hooks/commits/<short-hash> and the vector index is rebuilt asynchronously. Review hook-generated memories with:

mem list hooks/commits/
mem get hooks/commits/<hash>

Quick Reference

Deletion guardrail: Only run mem del when the user explicitly asks you to remove a memory. Never auto-delete entries you didn't create, and never "clean up" memories you judge outdated on your own — supersede them by overwriting with mem set instead. Git history preserves prior values, so there is no need to delete to correct a memory.

Red Flags — STOP and Check mem

These thoughts mean you're skipping the recall phase:

Common Mistakes

• Skipping recall entirely — Always run the recall phase commands at session start
• Storing narratives — Store "what + why" not "here's what happened in session X"
• Wrong scope — Project-specific knowledge stays project scope; only cross-project patterns and user preferences go global
• Forgetting index rebuild — After storing memories, run mem index rebuild if semantic search is configured
• Ignoring "embedder not available" — If semantic search fails, fall back to keyword search and note the issue. Don't silently skip recall.