# mcp-memories

An MCP server that captures code build sessions and publishes them to a shared team knowledge base, making past work discoverable via semantic search.

**What it does:**
- Auto-captures every agent session via IDE hooks (Cursor, Claude Code)
- When you call `complete_session`, it summarizes with Grove AI and embeds with Voyage `voyage-code-4`
- Team members search with natural language — vector search + Voyage reranking returns the most relevant past builds

## Setup

### 1. Install and build

```bash
npm install
npm run build
```

### 2. Configure environment

```bash
cp .env.example .env
# Fill in MONGODB_URI, MDB_GROVE_API_KEY, GROVE_BASE_URL, VOYAGE_API_KEY, MEMORIES_AUTHOR
```

### 3. Register the MCP server

Add to your IDE's MCP config (e.g. `~/.cursor/mcp.json` or Claude Desktop `config.json`):

```json
{
  "mcpServers": {
    "mcp-memories": {
      "command": "node",
      "args": ["/path/to/mcp-memories/dist/index.js"],
      "env": {
        "MONGODB_URI": "mongodb+srv://...",
        "MEMORIES_DB": "mcp_memories",
        "MDB_GROVE_API_KEY": "...",
        "GROVE_BASE_URL": "...",
        "GROVE_MODEL": "claude-3-7-sonnet",
        "VOYAGE_API_KEY": "...",
        "MEMORIES_AUTHOR": "your.name"
      }
    }
  }
}
```

### 4. Set up auto-capture hooks

**Cursor** — hooks.json is already in `.cursor/hooks.json`. It fires the capture script on every `stop` event automatically.

**Claude Code** — merge the snippet in `hooks/claude/settings-snippet.json` into your `~/.claude/settings.json`, updating the path to point to this repo.

## Tools

| Tool | When to use |
|---|---|
| `capture_activity` | Called automatically by hooks, or manually to record what you're working on |
| `complete_session` | Call when done — triggers summarization + embedding and publishes to the team |
| `search_memories` | Find past builds relevant to what you're about to start |
| `get_overview` | See what the team has built, by language / tag / repo |
| `list_recent` | Browse the most recently published sessions |

## Typical workflow

```
# During a session — automatic (hook fires) or manual:
capture_activity(session_id="abc123", conversation_context="Built JWT auth middleware...")

# When done:
complete_session(session_id="abc123", final_notes="Ended up using RS256 instead of HS256 because...")

# Later, someone else starting similar work:
search_memories(query="JWT authentication middleware Node.js")
```

## MongoDB Atlas setup

The server creates its own indexes on startup, including the Atlas Vector Search index (`memories_vector_index`, 1024 dimensions, cosine similarity, `voyage-code-4`). You need an Atlas cluster with Vector Search enabled.