Skip to main content
You can use Brain to find earlier decisions, save lessons, and give your agent context before it starts work. Below are some ways to use Brain in your project. Install Brain and set up your repository first. Run these commands from the repository, and replace the example questions and rules with your own.

Get to Know a Project

If you are joining a project or returning after a break, you can ask Brain for an overview of its structure, tools, and conventions.

Get Context Before Starting a Task

Describe what you want to build or change. Brain gathers relevant memories, earlier work, code locations, and possible tests into a brief.
You can now use the brief to plan your work or give your coding agent a starting point. Code locations in the brief come from entire-graph.

Find Out Why a Decision Was Made

Search earlier work before reopening a decision or trying an approach your team has already explored.
Use recall for recorded decisions. Check their supporting sources before applying them to current work. Use query for a broader search across history and docs.

Search for a Topic

Search for a topic by the words you expect to appear in saved memories, history, or docs:
query ranks results by keyword relevance using BM25, so results match the words in your query rather than their meaning. If a search returns nothing useful, try the terms your team would have used when the decision was recorded. The --semantic flag is deprecated and has no effect. It is still accepted as an alias so existing scripts keep working, but it returns the same keyword-ranked results. To narrow the search to one kind of source, use --source with fact, history, or doc:
To rank recent results higher, add --recency. You can change how quickly older results lose weight with --recency-half-life, which defaults to 2160h (90 days):

Save a Rule for Future Work

You can also record a decision or lesson as a memory so another session can find it. Only save rules that are true for your project.
The --path flag sets the memory’s category without an agent call. If you omit it, Brain can ask an agent to choose a category and incur token charges.

Save a Rule for Every Repository

Some memories, such as a personal preference or a team convention, apply to every repository you work in. Record them globally:
Brain recalls global memories from every repository and labels them (global) in results. To list them:
To leave global memories out of a search, add --no-global to query or recall. See Storage and Sync for repository and global scope.

Look Up Saved Rules

Before changing behavior, you can check what your project has already recorded about it.
Use recall for saved memories and query for a broader search across memories, history, and docs.

Review Memories as Markdown Files

Write your memories out as one Markdown file per memory, so you can read, search, and diff them with your usual tools:
The files are a copy. Brain rewrites the directory on each run and does not read the files back, so use remember and memories retract to change memories.

Import Memories from Another Tool

If you have memories in mem0, import its export file. Preview the import first:
Imported memories are filed under project.imported by default. Change this with --path-prefix.

Search Documents That Are Not Code

Brain reads PDF, Word, Excel, and PowerPoint files under docs/ along with Markdown, so they come back from query and brief. Extraction runs locally, with no model or network calls. To check what Brain reads from a file:
Scanned PDFs have no text layer, so Brain reports them instead of indexing an empty document.

Check What a Code Change Could Affect

With entire-graph installed, inspect the impact of changing a function or type. Replace ValidateToken with a symbol from your code.
You can also inspect changes since the last index:

Notify Another Service When Memory Changes

Brain can send a JSON event to an HTTP endpoint when a memory is recorded or retracted, or when memory is refreshed. This lets a CI job, chat channel, or index react without polling.
Run entire brain webhook events to list the events Brain sends. See Network Controls before enabling egress.

Check Whether Memory Is Current

You can see which sources are available, missing, or out of date, using:
If something needs attention, doctor prints the command that fixes it:
Check whether saved memories still point to matching sources:
A memory entered by hand can show unverifiable-here because it has no source reference. Verification checks references, not whether a memory is correct.