Managing Memory

First-Run Setup Check

IMPORTANT: Before using memory tools, ensure the MCP server is built and configured:

# Check if built
ls ~/.claude/plugins/cache/brain-jar/shared-memory/*/dist/index.js 2>/dev/null || echo "NOT_BUILT"

If NOT_BUILT, run the setup:

node ~/.claude/plugins/cache/brain-jar/shared-memory/*/run.js &
sleep 15

Then check for Mem0 config:

cat ~/.config/brain-jar/config.json 2>/dev/null || echo "NOT_CONFIGURED"

If NOT_CONFIGURED, ask user for their Mem0 API key (get one at https://app.mem0.ai), then create config:

mkdir -p ~/.config/brain-jar
cat > ~/.config/brain-jar/config.json << 'EOF'
{
  "mem0_api_key": "USER_API_KEY_HERE",
  "default_scope": "global",
  "auto_summarize": true
}
EOF

Note: Local storage works without Mem0 config - cloud sync is optional.

After setup, user must restart Claude Code for MCP to register.

When to Store Memories

Store memories when you observe:

Decisions - User chooses one approach over another
Preferences - User expresses likes/dislikes about tools, patterns, or approaches
Reactions - Strong positive or negative responses (enthusiasm, frustration)
Context - Important background about projects, goals, or constraints

How to Write Enriched Memories

Bad (too dry):

User chose Neon for database.

Good (captures context and sentiment):

User chose Neon over Supabase for Postgres hosting - appreciated the more generous
free tier limits. Showed strong preference for managed solutions: "I'm not running
my own infra" - values simplicity and time savings over control.

Memory Format

Include:

The fact - What was decided/learned
The why - Reasoning behind it
The sentiment - How they felt about it (quote if memorable)
The implication - What this suggests about future preferences

Scope Selection

global - Personal preferences, general learnings, cross-project patterns
project:<name> - Specific to current project (detect from working directory)

Use global for preferences that apply everywhere. Use project: for architectural decisions, tech choices, and patterns specific to one codebase.

When to Recall Memories

Before:

Starting a new feature (search for relevant past decisions)
Making technology choices (search for preferences)
Suggesting approaches (search for patterns they liked)

Use natural recall language:

"Remember when you were working on X, you decided..."
"You've mentioned before that you prefer..."
"Based on your experience with Y..."

Subagent Pattern for Large Retrievals

When searching or listing memories that could return many results (10+), dispatch a Haiku subagent to process and summarize:

When to use subagent:

Broad searches: "find all memories about preferences"
Timeline queries: "memories from last month"
Pattern analysis: "what decisions have I made about databases?"

How to dispatch:

Use Task tool:

subagent_type: "general-purpose"
model: "haiku"
prompt: "Search user memories and provide a summary.

TASK: [what user is looking for]

STEPS:

Call search_memory with query '[search terms]'
If many results, group by theme or tag
Return a 3-5 sentence summary highlighting:
- Key patterns/preferences found
- Notable decisions or quotes
- Relevant context for the current task

OUTPUT: Concise summary, not raw memory dumps."

Tell the user: The subagent's summary. Don't dump all raw memories into context.

When to use direct tools:

Specific lookups: "what was the exact decision about X?"
Small result sets: known to be 1-3 memories
When user explicitly asks for full details

Example flow:

User: What do I usually prefer for state management?

You: Let me search your memories for state management preferences...
[Dispatch Haiku subagent]

Subagent returns:
"Found 7 memories about state management. Key patterns:
- Strong preference for Zustand over Redux (called Redux 'too much boilerplate')
- Uses React Query for server state ('keeps server/client state separate')
- Avoids global state when possible - prefers component-level state
Notable quote: 'I want the simplest thing that works'"

You: Based on your past preferences, you tend to favor Zustand for client state
and React Query for server state. You've mentioned wanting "the simplest thing
that works" - should I keep that philosophy for this feature?

Tags to Use

preference - Likes/dislikes
decision - Specific choices made
architecture - System design patterns
personality - Working style, communication preferences
project - Project-specific context
session-summary - End-of-session consolidation
profile-context - Background context for profile preferences
profile-learning - Observations that inform the user profile

Related Skills

Learning About You

For structured user profile management (name, role, tech preferences, working style), use the learning-about-you skill instead of storing as freeform memories.

Use memories for:

Rich context and reasoning behind preferences
Specific quotes and reactions
Project-specific decisions
Session summaries

Use profile for:

Structured data (name, timezone, role)
Tech stack preferences (languages, frameworks)
Working style settings (verbosity, pace)
Personal goals and interests

The profile is queryable and shared across all brain-jar plugins. Memories provide the context and "why" behind profile entries.

managing-memory