Brain

You set up and run an MCP Brain Server to give AI agents a centralized learning loop: observe, practice, fail, update, and repeat. This server stores and retrieves knowledge, records outcomes, and automatically expands related knowledge to help AI agents learn more efficiently across your projects.

How to use

You interact with the MCP Brain by configuring a client that can reference and update knowledge. Use the brain to search for task-related knowledge, fetch detailed knowledge, and record execution results (success or failure). When a failure occurs, the brain updates its knowledge to reflect improvements and can auto-generate new knowledge ideas. Related knowledge is connected automatically through semantic similarity, so you don’t need to manually create links.

How to install

Prerequisites: ensure you have the MCP runtime available on your machine. You will also need a suitable environment where you can keep your MCP knowledge storage and run the brain integration.

Install the MCP Brain client/runtime using the built-in installer.

uv tool install . --force

Configuration and usage notes

You store and access knowledge in a dedicated storage directory. The example below shows how to configure the brain to run via an MCP client, including the storage directory path.

{
  "mcpServers": {
    "brain": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/tomoharu-hayashi/mcp-server-brain.git", "mcp-brain"],
      "env": {
        "MCP_BRAIN_DIR": "~/pj/my/mcp-brain-storage"
      }
    }
  }
}

Knowledge reference and learning workflow

Knowledge is organized in a structured storage area. You can reference knowledge with search and get operations, which automatically expand related knowledge using embedding-based similarity. The depth of related knowledge expansion can be controlled with the hops parameter (default is 2). For example, fetching related knowledge two hops away from PR creation yields a cascade of related topics such as commits and pushes.

Git integration and version control

All knowledge creation, updates, and deletions are committed to Git automatically. You can initialize the knowledge directory as a Git repository and link it to a remote location to enable synchronization across environments.

Troubleshooting and notes

If you encounter issues starting or syncing knowledge, verify that MCP_BRAIN_DIR is correctly set and that the storage path is accessible. Ensure network access if you are pulling knowledge from remote sources.

Development and commands

Common development and maintenance commands you may run include building, testing, linting, and dev server access.

make help
make doctor
make deps
make lint
make fmt
make test
make dev ARGS="--help"

Available tools

search

Query knowledge related to a task to locate relevant information within the brain storage.

get

Retrieve knowledge details and automatically expand related knowledge using embedding-based similarity; supports depth control with hops.

create

Add new knowledge to the brain storage.

update

Update existing knowledge to reflect new information or corrections.