🍺 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.

  ┌──────────────────────────────────────────────────────────┐
  │                   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:

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:

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:

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:

{
  "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.