← Documentation Home

Agent Brain Developer Guide

Overview

Package: @bluefly/agent-brain Version: Latest License: MIT

Agent-Brain is the central vector database hub for the LLM ecosystem, providing semantic memory, knowledge graph integration, and advanced AI capabilities for scientific research acceleration. Built on Qdrant with OSSA v0.1.8 compliance.

Key Features

Installation

npm install @bluefly/agent-brain

Quick Start

Initialize Agent Brain

import { AgentBrain } from '@bluefly/agent-brain';

const brain = new AgentBrain({
  qdrantUrl: 'http://localhost:6333',
  collectionName: 'knowledge-base',
  embeddingModel: 'openai/text-embedding-ada-002',
});

await brain.initialize();

Store Vectors

// Create vector embeddings
const embeddings = await brain.embed({
  texts: [
    'Quantum entanglement in photon pairs',
    'Neural network backpropagation',
    'CRISPR gene editing mechanisms',
  ],
});

// Store in vector database
await brain.store({
  vectors: embeddings,
  metadata: [
    { domain: 'physics', topic: 'quantum mechanics' },
    { domain: 'ai', topic: 'deep learning' },
    { domain: 'biology', topic: 'genetics' },
  ],
});

// Search for similar content
const results = await brain.search({
  query: 'How does quantum computing relate to AI?',
  topK: 5,
  scoreThreshold: 0.7,
});

console.log('Search results:', results);

API Reference

Core Functions

AgentBrain.embed(options)

Generate embeddings for text.

Parameters: - texts (string[]): Array of texts to embed - model (string, optional): Embedding model to use

Returns: Promise

AgentBrain.store(options)

Store vectors in database.

Parameters: - vectors (number[][]): Vector embeddings - metadata (object[]): Metadata for each vector - ids (string[], optional): Custom IDs for vectors

Returns: Promise

AgentBrain.search(options)

Semantic similarity search.

Parameters: - query (string): Search query - topK (number): Number of results to return - scoreThreshold (number): Minimum similarity score - filter (object, optional): Metadata filters

Returns: Promise

AgentBrain.delete(options)

Delete vectors from database.

Parameters: - ids (string[]): Vector IDs to delete - filter (object, optional): Delete by metadata filter

Returns: Promise

Knowledge Graph Integration

// Connect to Neo4j knowledge graph
const graph = brain.connectKnowledgeGraph({
  neo4jUri: 'bolt://localhost:7687',
  username: 'neo4j',
  password: 'password',
});

// Create relationships
await graph.createRelation({
  from: 'quantum-computing',
  to: 'machine-learning',
  type: 'ENABLES',
  properties: { confidence: 0.85 },
});

// Query graph
const related = await graph.query({
  start: 'quantum-computing',
  depth: 2,
  relationTypes: ['ENABLES', 'RELATED_TO'],
});

Configuration

Environment Variables

# Qdrant Vector Database
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your-api-key
QDRANT_COLLECTION=knowledge-base

# Embeddings
OPENAI_API_KEY=your-openai-key
EMBEDDING_MODEL=text-embedding-ada-002
EMBEDDING_DIMENSIONS=1536

# Knowledge Graph (Neo4j)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# MCP Server
MCP_SERVER_ENABLED=true
MCP_SERVER_PORT=3001

# Scientific Research
ENABLE_RESEARCH_AGENTS=true
RESEARCH_DOMAINS=physics,biology,chemistry,math

Configuration File

agent-brain.config.yaml:

vector:
  database: qdrant
  url: http://localhost:6333
  collection: knowledge-base
  dimensions: 1536

embeddings:
  provider: openai
  model: text-embedding-ada-002
  batchSize: 100

knowledgeGraph:
  enabled: true
  provider: neo4j
  uri: bolt://localhost:7687

research:
  enabled: true
  domains:
    - physics
    - biology
    - chemistry
    - mathematics
  expertAgents: true

Examples

Combine vector and keyword search:

const results = await brain.hybridSearch({
  query: 'quantum machine learning applications',
  vectorWeight: 0.7,
  keywordWeight: 0.3,
  topK: 10,
  filters: {
    domain: ['physics', 'ai'],
    publicationYear: { $gte: 2020 },
  },
});

Multi-Modal Embeddings

Process different content types:

// Text embeddings
const textEmbeddings = await brain.embed({
  texts: ['Research paper abstract...'],
  type: 'text',
});

// Image embeddings
const imageEmbeddings = await brain.embed({
  images: ['path/to/image.jpg'],
  type: 'image',
  model: 'clip',
});

// Combine in single search space
await brain.store({
  vectors: [...textEmbeddings, ...imageEmbeddings],
  metadata: [
    { type: 'text', source: 'paper' },
    { type: 'image', source: 'figure' },
  ],
});

Research Agent Collaboration

Use specialized domain agents:

// Initialize research agents
const physics = await brain.spawnResearchAgent({
  domain: 'physics',
  expertise: ['quantum-mechanics', 'particle-physics'],
});

const biology = await brain.spawnResearchAgent({
  domain: 'biology',
  expertise: ['genomics', 'molecular-biology'],
});

// Cross-disciplinary synthesis
const synthesis = await brain.synthesizeResearch({
  query: 'How can quantum computing accelerate protein folding simulations?',
  agents: [physics, biology],
  outputFormat: 'research-paper',
});

console.log(synthesis.findings);

MCP Integration

Agent Brain provides an MCP server for Claude Desktop:

Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "agent-brain": {
      "command": "node",
      "args": ["/path/to/agent-brain/dist/mcp-server.js"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OPENAI_API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools

Testing

# Unit tests
npm test

# Integration tests (requires Qdrant, Neo4j)
npm run test:integration

# Research agent tests
npm run test:research-agents

# Coverage
npm run test:coverage

Performance

Deployment

Docker

# Start Qdrant + Agent Brain
docker-compose up -d

# Services:
# - Qdrant (port 6333)
# - Agent Brain API (port 3004)
# - Neo4j (port 7687, 7474)

Kubernetes

# Deploy
kubectl apply -f infrastructure/kubernetes/

# Check status
kubectl get pods -n agent-brain

Troubleshooting

Qdrant Connection Issues

# Check Qdrant status
curl http://localhost:6333/health

# Test connection
npm run test:qdrant-connection

Embedding Generation Errors

# Verify OpenAI API key
echo $OPENAI_API_KEY

# Test embedding generation
npm run test:embeddings

Documentation

Support