BrainCell - Centralized Memory for Copilot

A centralized memory system for Copilot that combines PostgreSQL, Weaviate vector database, and JSON storage for semantic search and context management.

Architecture

graph TD
    C(["Clients<br/>Copilot · Claude · Users"])

    C -->|"HTTP REST"| API
    C -->|"HTTP browser"| DASH
    C -->|"MCP Protocol"| MCP

    subgraph app["Application Layer"]
        API["REST API<br/>Port 9504 · FastAPI"]
        MCP["MCP Server<br/>Port 9506 · FastMCP"]
        DASH["Dashboard<br/>Port 9507 · Web UI"]
    end

    subgraph data["Data Layer"]
        PG[("PostgreSQL<br/>Port 9500<br/>Source of truth")]
        WV[("Weaviate<br/>Port 9501 / 9502<br/>Semantic search")]
        RD[("Redis<br/>Port 9503<br/>Cache")]
    end

    PGA["pgAdmin<br/>Port 9505"]

    API --> PG
    API --> WV
    API --> RD
    MCP --> PG
    DASH --> PG
    PGA -.->|"admin only"| PG

    style API fill:#1565C0,color:#fff
    style MCP fill:#2E7D32,color:#fff
    style DASH fill:#E65100,color:#fff
    style PG fill:#37474F,color:#fff
    style WV fill:#6A1B9A,color:#fff
    style RD fill:#B71C1C,color:#fff

Loading

Tech Stack

• Backend: FastAPI + Python 3.11
• Database: PostgreSQL 15 (structured data + JSONB)
• Vector DB: Weaviate (semantic search)
• Cache: Redis (session caching)
• Container: Docker Compose

Quick Start

Prerequisites

• Docker and Docker Compose
• Or Python 3.11+ with PostgreSQL and Weaviate

Run with Docker Compose

# Start all services
docker-compose up -d

# Wait for services to be healthy
docker-compose ps

# Access API
curl http://localhost:9504/health

# View Weaviate console
open http://localhost:9501

Access Points

• API: http://localhost:9504
• API Docs: http://localhost:9504/docs
• Weaviate Console: http://localhost:9501
• PostgreSQL: localhost:9500 (user: braincell, password: braincell_dev_password)
• Redis: localhost:9503
• PgAdmin: http://localhost:9505 (admin@braincell.local / admin)

Environment Variables

Create .env file:

DATABASE_URL=postgresql://braincell:braincell_dev_password@localhost:9500/braincell
WEAVIATE_URL=http://localhost:9501
REDIS_URL=redis://localhost:9503
ENVIRONMENT=development

API Endpoints

Health & Status

• GET /health - Health check

Conversations

• POST /api/conversations - Create conversation
• GET /api/conversations/{id} - Get conversation
• PUT /api/conversations/{id} - Update conversation

Design Decisions

• POST /api/decisions - Create decision
• GET /api/decisions - List decisions
• GET /api/decisions/{id} - Get decision

Architecture Notes

• POST /api/architecture-notes - Create note
• GET /api/architecture-notes - List notes

Files Discussed

• POST /api/files - Record file discussion
• GET /api/files - List files

Code Snippets

• POST /api/snippets - Create snippet
• GET /api/snippets - List snippets

Context Snapshots

• POST /api/snapshots - Create snapshot
• GET /api/snapshots - Get recent snapshots

Memory Sessions

• POST /api/sessions - Create session
• GET /api/sessions/{id} - Get session
• PUT /api/sessions/{id} - Update session

Search

• POST /api/search/conversations - Semantic search conversations
• POST /api/search/decisions - Semantic search decisions
• POST /api/search/code - Semantic search code snippets

Example Usage

Create a Conversation

curl -X POST http://localhost:9504/api/conversations \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "topic": "Building memory system",
    "summary": "Discussed BrainCell architecture with PostgreSQL and Weaviate",
    "metadata": {"tags": ["architecture", "design"]}
  }'

Create a Design Decision

curl -X POST http://localhost:9504/api/decisions \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "Use Weaviate for semantic search",
    "rationale": "Better than Redis for vector similarity",
    "impact": "Enables advanced search capabilities",
    "status": "active"
  }'

Search Conversations

curl -X POST http://localhost:9504/api/search/conversations \
  -H "Content-Type: application/json" \
  -d '{
    "query": "memory system architecture",
    "limit": 10,
    "offset": 0
  }'

Create Code Snippet

curl -X POST http://localhost:9504/api/snippets \
  -H "Content-Type: application/json" \
  -d '{
    "title": "FastAPI Health Check",
    "code_content": "@app.get(\"/health\")\nasync def health_check():\n    return {\"status\": \"ok\"}",
    "language": "python",
    "file_path": "src/main.py",
    "tags": ["fastapi", "health-check"]
  }'

Database Schema

Tables

1. conversations - Conversation records with timestamps
2. design_decisions - Design decisions with rationale and impact
3. architecture_notes - Architecture patterns and constraints
4. files_discussed - Files mentioned in conversations
5. code_snippets - Code examples and snippets
6. context_snapshots - Full context snapshots (JSONB)
7. memory_sessions - Session tracking and metadata

Features

• Full-text search on PostgreSQL
• JSONB support for flexible metadata
• Automatic timestamps with triggers
• Vector indexing in Weaviate for semantic search
• Cascading updates with triggers

Development

Install Dependencies

pip install -r requirements.txt

Run Locally (without Docker)

# Start PostgreSQL, Weaviate, Redis separately
# Then:
uvicorn src.main:app --reload

Run Tests

pytest tests/

Format Code

black src/
ruff check src/

Monitoring

Logs

# View application logs
docker-compose logs braincell-api

# Follow logs
docker-compose logs -f braincell-api

Database Queries

Access PostgreSQL directly:

docker-compose exec postgres psql -U braincell -d braincell

Weaviate Status

curl http://localhost:8080/v1/.well-known/ready

Cleanup

# Stop all services
docker-compose down

# Remove volumes (careful!)
docker-compose down -v

# Rebuild everything
docker-compose down -v && docker-compose build --no-cache

Features

• Structured Data - PostgreSQL for conversations, decisions, notes
• Vector Search - Weaviate for semantic similarity search
• JSON Storage - JSONB in PostgreSQL for flexible data
• Sessions - Track conversation sessions and context
• Caching - Redis for performance
• Full-Text Search - PostgreSQL built-in FTS
• API Docs - Auto-generated Swagger UI
• Docker Ready - Complete docker-compose setup

Integration with Copilot

The BrainCell API can be integrated with Copilot via:

1. Direct API calls from Copilot extensions
2. Memory context injection before conversations
3. Auto-indexing of sessions and decisions
4. Semantic search for context retrieval

Future Enhancements

• Graph database for relationship mapping
• LLM-based summarization
• Advanced filtering and aggregations
• Memory export/import
• Analytics dashboard
• Multi-tenant support
• Audit logging
• Backup and recovery

Documentation

All technical documentation is in the docs/ directory.

Quick Links

• Documentation Index
• Quick Start Guide
• Kubernetes Deployment
• MCP Server Guide
• API Endpoints Reference
• Database Guide

Documentation Categories

Category	Description	Link
API & Architecture	Endpoints, architecture diagrams, service structure	docs/api/
Deployment	Docker, Kubernetes, Helm charts	docs/deployment/
Guides	Quick starts, database setup	docs/guides/
MCP Protocol	Model Context Protocol integration	docs/mcp/
Testing	Test procedures and framework	docs/testing/

MIT

Support

For issues or questions, check the documentation or open an issue.