Brain 🧠⚡

Neuron-connected, local-first associative memory framework for AI agent developers.

Brain is a vendor-agnostic developer framework that gives AI agents a brain-inspired memory architecture. Unlike traditional vector databases or flat memory stores, Brain automatically builds weighted synaptic connections between memories based on semantic meaning, entity overlap, and temporal context, enabling multi-hop associative recall.

🌟 Key Features

• Vendor-Agnostic & LLM-Independent: Works with ANY LLM provider (OpenAI, Groq, Ollama, Claude, Gemini, or custom local models). The core engine runs 100% locally with zero cloud API dependencies.
• Label-Free Emergent Synapses: No manual schemas or tags required. Synaptic connections form dynamically based on vector space proximity and extracted entity overlap.
• Associative Multi-Hop Recall: Recalls direct matches and traverses graph synapses (e.g., querying "tell me about user preferences" recalls connected facts across sessions).
• Dual-Track Real-Time Pipeline: Includes a high-level RealtimeBrainPipeline helper for real-time agents combining short-term dialogue buffering, pronoun resolution, customizable entity extraction, and background 3rd-person atomic fact extraction.
• Hebbian Learning & Decay: Connections strengthen when memories are co-recalled ("neurons that fire together wire together") and naturally decay over time.
• HNSW Acceleration: Built-in Hierarchical Navigable Small World index for sub-10ms $O(\log n)$ recall at 100K+ memory scale.
• Developer-Centric CLI: brain CLI for project creation and daemon management.

🚀 Quickstart

1. Installation

# Install global CLI and daemon
npm install -g brain-mem

2. CLI Workflow

# Create a new brain for your project
brain create my-agent

# Start the server (runs on http://localhost:7700)
brain start my-agent

# List all registered brains
brain list

# Check brain health & statistics
brain status my-agent

# Show author information
brain --about

💻 SDK Integration

Python SDK

pip install brain-neuromem

Option A: Direct Brain Client (Low-Level API)

from neuromem import Brain

# 1. Connect via brain_name or brain_url (or auto-resolves BRAIN_NAME / BRAIN_URL env vars)
brain = Brain(brain_name="my-agent")

# Store memories
brain.remember("User prefers dark mode UI")
brain.remember("User is building a web application using Python")
brain.remember("User lives in Seattle")

# Associative Recall
memories = brain.recall("what are user preferences?", depth=2, limit=5)

for m in memories:
    print(f"[{m['score']}] {m['content']}")

Option B: Vendor-Agnostic Real-Time Pipeline (High-Level API)

Works with ANY LLM provider (OpenAI, Groq, Ollama, Claude, Gemini, etc.):

from neuromem import RealtimeBrainPipeline

# Define your custom completion callback using any LLM provider
def my_llm_callback(messages):
    # Call OpenAI, Groq, Ollama, Claude, or any local model here
    return llm_client.chat(messages)

# Initialize Realtime Pipeline (Pass brain_name, custom prompt, or extract_fn if needed)
pipeline = RealtimeBrainPipeline(
    brain_name="my-agent",
    llm_fn=my_llm_callback,
    # Optional: Pass custom extraction prompt for specific character personas
    # custom_extract_prompt="Your custom extraction prompt for {text}"
)

# Chat naturally (handles pronoun resolution + background fact extraction automatically)
result = pipeline.chat("i prefer dark mode for my editor")
print(result["response"])

TypeScript SDK

import { Brain } from 'brain-mem';

// Connect via name, URL, or auto-resolves process.env.BRAIN_NAME / process.env.BRAIN_URL
const brain = new Brain('my-agent');

// Store memory
await brain.remember("User prefers dark mode UI");

// Associative Recall
const memories = await brain.recall("what are user UI preferences?", { depth: 2 });
console.log(memories);

🔗 How Brain Connects to ANY LLM

Brain operates as an independent memory layer. It does not lock you into any specific LLM model or provider:

┌─────────────────────────────────────────────────────────────┐
│                 YOUR AI AGENT APPLICATION                   │
│   (Uses OpenAI, Groq, Ollama, Claude, Gemini, or vLLM)      │
└──────────────────────────────┬──────────────────────────────┘
                               │
            1. recall()        │  2. Inject memories as context
            Query Facts        │  into system prompt
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                   BRAIN DAEMON (:7700)                      │
│                                                             │
│  - HNSW Index (O(log n) ANN search)                         │
│  - Local ONNX Embeddings (all-MiniLM-L6-v2, 22MB)           │
│  - Synaptic Graph & Hebbian Consolidation                   │
│  - Local Binary .nmem File Storage                          │
└─────────────────────────────────────────────────────────────┘

📊 Performance & Benchmarks

• Recall Latency: ~8ms average across multi-hop queries
• Embedding Model: Local ONNX quantized all-MiniLM-L6-v2 (22MB, no external API needed)
• Index: HNSW $O(\log n)$ search engine

👨‍💻 Author

Engineered by Elangovan Manickam ([email protected]).

📄 License

MIT License