Quick Start

Get Brain Memory working in under five minutes. This guide walks you through installation, creating your first memory, recalling it, and checking the status dashboard.

Install Brain Memory

Run the installer and follow the interactive prompts to select your agent(s) and install scope:

npx brain-memory@beta

Or use flags for a non-interactive install:

npx brain-memory@beta --claude --global

Initialize your brain

Open a new session with your AI agent and run:

/brain:init

This creates the ~/.brain/ directory structure with default categories (professional/, personal/, social/, family/) and sets up index.json, associations.json, and other supporting files.

Memorize something

After working on a task — making an architecture decision, learning a new pattern, or debugging an issue — store it:

/brain:memorize

The agent analyzes your current session, extracts significant decisions, learnings, insights, or experiences, and creates memory files in the appropriate place in the hierarchy. You can also provide a topic:

/brain:memorize architecture decisions

Recall a memory

In a future session, recall what you stored:

/brain:remember kafka architecture

The agent searches the memory index, scores candidates using spreading activation and context matching, and returns the most relevant memories. Recalled memories get stronger through spaced reinforcement.

Check your brain status

See the overall health of your memory system:

/brain:status

This shows a dashboard with memory count, strength distribution, upcoming reviews, and any maintenance recommendations.

What Happens Automatically

Once installed, Brain Memory works in the background without any commands:

Session start — The agent silently loads the top 5 memories relevant to your current project and checks for memories due for review
During the session — The agent tracks notable events (decisions, learnings, insights) and periodically nudges you to memorize when enough have accumulated
Session end — If significant content occurred, the agent saves session context and suggests running /brain:memorize

You never need to explicitly manage the system — just use /brain:memorize and /brain:remember when you want to, and the agent handles everything else.

Next Steps

Learn about Memory Types to understand how different memories behave
Explore Strength & Decay to see how memories change over time
Run /brain:sleep periodically to trigger the 9-phase maintenance cycle
Set up Portable Sync to share memories across devices

Tip

Run /brain:sleep about once a week. It consolidates weak memories, prunes faded ones, discovers cross-domain connections, and generates expertise profiles — just like real sleep does for your brain.