🧠 Local Agent Brain

A local, lightweight, and offline Second Brain for AI agents (like Cursor, Windsurf, Claude Desktop, and Copilot) powered by Graph RAG (Knowledge Graph + Semantic Search).

local-agent-brain helps AI agents retain long-term memory about your project setups, build commands, architecture decisions, database schemas, and workflows. It runs 100% locally and offline.

✨ Features

• Local Vector Embeddings: Uses the lightweight Xenova/all-MiniLM-L6-v2 model locally via Hugging Face Transformers.js. No API keys needed.
• Hybrid Search: Combines semantic similarity (Cosine Similarity) with keyword matching for highly accurate retrieval.
• Knowledge Graph: Create directed connections between notes/memories (nodes) and relations (edges) so the agent understands context and dependencies.
• MCP Server Integration: Exposes native tools to AI agents using Anthropic's Model Context Protocol (MCP), letting agents search, query, and save memories during chat.
• Project-Specific or Global: Can be initialized locally in a repository (.agent-brain/) or globally (~/.agent-brain/).

🚀 Quick Start

1. Installation

You can run it directly using npx, install it globally, or install it locally in your project:

# Global installation
npm install -g local-agent-brain

2. Initialization

Go to your project directory and run:

# Initialize a local brain for the current project
local-agent-brain init

# Or initialize a global brain
local-agent-brain init --global

This creates a .agent-brain/ directory with a brain.json database.

3. Store Memories (CLI)

Add facts, setups, or tips to your brain:

local-agent-brain store "Production Build" "To build the project for production, run 'npm run build'" --tags "build,prod"

You can also create links between memories:

# Store another memory
local-agent-brain store "Deploy Command" "To deploy the built application, run 'npm run deploy'" --tags "deploy,prod"

# Link them together
local-agent-brain link "Production Build" "Deploy Command" --relation "pre-requisito"

4. Query Memories (CLI)

Test the RAG search using the CLI:

local-agent-brain remember "how to deploy the application?"

Output:

Querying brain for: "how to deploy the application?"...

1. [Score: 61.1%] "Deploy Command" (ID: 3b72daca-69ab-44b2-a233-7dbb493a1f4e)
   Tags: deploy, prod
   Content: To deploy the built application, run 'npm run deploy'
   Linked to:
     - "Production Build" (pre-requisito)

🤖 Integrating with AI Agents (MCP Server Setup)

The absolute best way to use local-agent-brain is by exposing it as a Model Context Protocol (MCP) server in your IDE. This allows agents to query your memory graph automatically when you ask questions.

⚡ Automatic Configuration (Recommended)

You can automatically configure local-agent-brain in your IDEs (Cursor, Windsurf, and Claude Desktop) with a single command:

# Register MCP server automatically in Cursor, Windsurf, and Claude Desktop
local-agent-brain setup

This will inspect your system, locate the configuration directories for these applications, and register the MCP server automatically. Afterward, please restart your IDE or reload the chat window to apply the changes.

🛠️ Manual Configuration (Alternative)

1. Cursor IDE

1. Go to Cursor Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Fill in the details:
   • Name: local-agent-brain
   • Type: command
   • Command: npx -y local-agent-brain mcp

2. Windsurf IDE

Add the following to your global MCP configuration file (typically located at ~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "local-agent-brain": {
      "command": "npx",
      "args": ["-y", "local-agent-brain", "mcp"]
    }
  }
}

3. Claude Desktop App

Add the following to your configuration file (typically located at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "local-agent-brain": {
      "command": "npx",
      "args": ["-y", "local-agent-brain", "mcp"]
    }
  }
}

🛠️ CLI Reference

Usage: local-agent-brain [options] [command]

Options:
  -V, --version                      output the version number
  -h, --help                         display help for command

Commands:
  init [options]                     Initialize the agent brain database
  store [options] <title> <content>  Store a new fact, instruction, or note in the brain
  remember [options] <query>         Query the brain for memories using semantic hybrid search
  link [options] <source> <target>   Create a relationship connection between two memories
  delete <id>                        Delete a memory from the brain
  status                             Check the database location and memory graph stats
  mcp                                Start the Model Context Protocol (MCP) server on stdio
  setup                              Automatically register local-agent-brain MCP server in Cursor, Windsurf, and Claude Desktop config

📦 MCP Tools Exposed to AI

When active, the agent gains access to these tools:

• query_memory(query: string, limit?: number): Queries the local knowledge graph.
• store_memory(title: string, content: string, tags?: string[], linksTo?: string[]): Saves new context.
• link_memories(source: string, target: string, relationType?: string): Links existing nodes.
• get_memory_graph(): Inspects the overall graph structure.
• delete_memory(id: string): Removes outdated facts.

📄 License

MIT License. Feel free to use and contribute!