Brain Memorybrain memory

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.

undefined

Install Brain Memory

Install the package globally, then run the setup wizard:

npm install -g brain-memory@beta
brain

Or use flags for a non-interactive install:

brain --claude --global
undefined

Confirm your brain is ready

The installer already created your ~/.brain/ directory — the structure with default categories (professional/, personal/, social/, family/) plus index.json, associations.json, and other supporting files. Open a new session with your AI agent and confirm it's active:

/brain:status

(If ~/.brain/ is ever missing, it's recreated automatically on your first /brain:memorize or /brain:sync.)

undefined

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
undefined

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.

undefined

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

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.