# 🍺 BeerMan - Long-Term Project Memory Engine

BeerMan is a professional pair-programming memory system that acts as a continuous intelligence bridge between your IDE agents (Anti-Gravity, Claude Code, Cursor) and your planning sessions. It leverages **Supermemory** as a centralized, canonical vector store for all architectural guidelines, design decisions, code watchers, and context captures.

```text
  ┌──────────────────────────────────────────────────────────┐
  │                   Planning & Session                     │
  │  (ChatGPT / Claude Web Chats / Scrolling Screenshots)   │
  └────────────────────────────┬─────────────────────────────┘
                               │ (Browser Sidebar Extension)
                               ▼
                ┌──────────────────────────────┐
                │    Supermemory Vector Store  │
                └──────────────┬───────────────┘
                               │ (Memory Bridge / MCP API)
                               ▼
  ┌──────────────────────────────────────────────────────────┐
  │                 Development Workspace                    │
  │     (Anti-Gravity / Claude Code / Cursor / VS Code)      │
  └──────────────────────────────────────────────────────────┘
```

---

## ⚡ Quick Start (One-Liner)

Run the following command in your terminal to instantly clone, install dependencies, compile TypeScript packages, and start the development servers:

```bash
git clone https://github.com/nitineeen/beerman.git && cd beerman && npm install && npm run build && npm run dev
```

Once running, your local dashboard will be hosted at **`http://localhost:2414`**.

---

## 🏗️ System Architecture & Monorepo Layout

BeerMan is built as a TypeScript monorepo where components have single, isolated responsibilities:

```text
project-beerman/
├── apps/
│   ├── extension/          # Unpacked Manifest V3 Chrome Sidebar Extension
│   └── dashboard/          # Next.js workspace management dashboard & setup guide
├── packages/
│   ├── core/               # Shared project type definitions, categories, and models
│   ├── memory/             # Supermemory client SDK for ingestion and semantic searches
│   └── mcp-server/         # Model Context Protocol (MCP) server integration
└── .agents/
    └── skills/             # Structured agent guidelines (YAML + Markdown format)
```

### 1. Chrome Extension Sidebar (`apps/extension`)
- Slides out on the right viewport, automatically resizing and rendering target webpages responsively.
- Direct Supermemory integration for live project creation, renaming, and document deletion.
- Features sequential upload queueing with robust error handling and duplicate prevention.
- Seamlessly captures raw text selections, full-page screenshots, files, and chat logs.

### 2. BeerMan Dashboard (`apps/dashboard`)
- Next.js web application that displays your living docs, project indexing details, and setup guides.

### 3. Model Context Protocol Server (`packages/mcp-server`)
- Exposes tools to your AI agent so it can interact with your memory directly:
  - `list_projects`: Lists registered project indices.
  - `open_project(projectId)`: Selects active context.
  - `store_memory(content, category, tags)`: Commits structured milestones, decisions, architecture specs, or roadmaps.
  - `search_memory(query)`: Performs vector/semantic search on project memory.

---

## 🚀 Setup & Installation

### Step 1: Install Dependencies & Build
Compile the TypeScript packages and Next.js applications:
```bash
npm install
npm run build
```

---

### Step 2: Configure the MCP Server in your IDE

Add the BeerMan MCP server configuration to link it with your agent. Ensure you replace `/absolute/path/to/project-beerman` with your actual directory path.

#### For Anti-Gravity or Claude Code:
Add this configuration block to your global configurations at `~/.gemini/config/mcp_config.json` or `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "beerman": {
      "command": "node",
      "args": ["/absolute/path/to/project-beerman/packages/mcp-server/dist/index.js"],
      "env": {
        "SUPERMEMORY_API_KEY": "your_supermemory_api_key_here"
      }
    }
  }
}
```

#### For Cursor:
1. Navigate to **Settings > Features > MCP**.
2. Click **+ Add New MCP Server**.
3. Fill out the fields:
   - **Name**: `beerman`
   - **Type**: `command`
   - **Command**: `node /absolute/path/to/project-beerman/packages/mcp-server/dist/index.js`
4. Under Environment Variables, add `SUPERMEMORY_API_KEY` with your API key.

---

### Step 3: Install the Chrome Sidebar Extension

1. Open Google Chrome and go to `chrome://extensions/`.
2. Toggle **Developer mode** on (top-right corner).
3. Click **Load unpacked** (top-left corner).
4. Select the directory: `project-beerman/apps/extension`.
5. Click the extension icon in your toolbar to open the **right-side panel**.
6. Enter your Supermemory API Key, and manage your projects dynamically.

---

## 🛠️ Deploying & Sharing

### 1. Deploying the Dashboard (Vercel)
The dashboard can be instantly deployed to Vercel:
1. Connect this repository to your Vercel Account.
2. Set the **Root Directory** to `apps/dashboard`.
3. Vercel will automatically compile the Next.js bundle and deploy it.

### 2. Sharing the Extension
- **Unpacked**: Zip the `apps/extension` folder and distribute it to your team to load via Developer Mode.
- **Chrome Web Store**: Package the extension and upload it to the Chrome Developer Dashboard to publish it.

### 3. MCP Server Cloud Deployment
You can host the MCP server on Railway, Fly.io, or Render, exposing it via SSE (Server-Sent Events) or standard stdio transports, allowing team members to connect to the same remote memory.