<img src="docs/logo.svg" width="72" alt="">

# meet-memory

**Your Google Calendar is a CRM you've been filling out for years without knowing it.**

meet-memory is a source-available [MCP](https://modelcontextprotocol.io) server that turns your Google Calendar *history* into a searchable people CRM — and lets you talk to it through Claude (or any MCP client):

> *"How many meetings did I have with Mariana in 2024 vs 2025?"*
> *"Who are the 10 people I meet with the most?"*
> *"Which relationships are going cold?"*
> *"Everyone from acmecorp.example I've ever met — and when we last talked."*
> *"How many hours of meetings per month over the last year?"*

Existing calendar integrations manage your *upcoming* events. meet-memory is about the other direction: years of history, organized around **people**, not events.

- 🔒 **Local-first** — OAuth credentials and the calendar database stay on your machine. meet-memory has no telemetry or hosted backend; it calls Google's API read-only and returns only the requested tool results to your MCP client.
- 🧠 **People-centric** — attendees become contacts, email domains become organizations, meetings become relationship history.
- ⚡ **Incremental** — first sync backfills up to 10 years; after that, syncs are fast deltas.

![meet-memory running in demo mode](docs/screenshot.png)

*Demo mode. Every name above is fabricated: `--demo` seeds a fake address book so the tool can be shown without exposing anyone.*

## Try it without a Google account

Demo mode seeds fake data so you can feel the product before touching OAuth. Build it once:

```bash
git clone https://github.com/arthurglv/meet-memory
cd meet-memory
npm install && npm run build
```

Then register it in Claude Code:

```bash
claude mcp add meet-memory -- node "$PWD/dist/index.js" --demo
```

Or in Claude Desktop (`claude_desktop_config.json`), using the absolute path to the folder you cloned:

```json
{
  "mcpServers": {
    "meet-memory": {
      "command": "node",
      "args": ["/absolute/path/to/meet-memory/dist/index.js", "--demo"]
    }
  }
}
```

Now ask: *"Who do I meet with the most?"*

> Not on npm yet, so there is no `npx` one-liner. Building takes about a minute.

## Real setup (your calendar)

1. **Create Google OAuth credentials** (one time, ~5 minutes): follow [docs/oauth-setup.md](docs/oauth-setup.md). You'll end up with a `client_secret_*.json` file. meet-memory only requests the **read-only** calendar scope.

2. **Configure your MCP client.** In Claude Code, from the folder you cloned:

```bash
claude mcp add meet-memory --scope user --env GOOGLE_OAUTH_CREDENTIALS=$HOME/.meet-memory/client_secret.json -- node "$PWD/dist/index.js"
```

Or in Claude Desktop:

```json
{
  "mcpServers": {
    "meet-memory": {
      "command": "node",
      "args": ["/absolute/path/to/meet-memory/dist/index.js"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/absolute/path/to/client_secret.json"
      }
    }
  }
}
```

3. **First run:** ask Claude to run `sync_calendar`. A browser tab opens for Google login; after that, the backfill runs (a couple of minutes for years of history). Subsequent syncs are incremental and take seconds.

4. **More than one account?** Ask for `sync_calendar` with `add_account` and pick the other Google account. Then use `list_calendars` and `set_calendar_role` to say which calendars hold meetings and which are to-do lists.

## Tools

| Tool | What it answers |
|---|---|
| `sync_calendar` | Pulls your history into the local database (backfill, then incremental) |
| `list_people` | "Who do I meet with the most?" — the CRM view, filterable by period/org |
| `get_person` | Full profile: meetings, hours, first/last contact, per-year history |
| `search_meetings` | Find meetings by person, org, text, or date range |
| `get_org` | Company view: everyone you know at a domain |
| `meeting_stats` | Meeting load per week/month/year (optionally including solo focus blocks) |
| `stale_relationships` | People you used to see often but haven't lately |
| `suggest_merges` | Addresses that look like the same person (suggestions only) |
| `merge_people` | Confirm that two addresses are one person |
| `unmerge_people` | Undo a merge |
| `export_report` | Write a Markdown report of everyone to a local file |
| `list_calendars` | Connected accounts and their calendars |
| `set_calendar_role` | Mark a calendar as meetings or tasks |
| `set_person_category` | Mark someone as personal, keeping them out of the work ranking |
| `status` | Database totals and auth state |

## How it works

```
Google Calendar API ──read-only──▶ sync engine ──▶ ~/.meet-memory/meet-memory.db (SQLite)
                                                        ▲
Claude / MCP client ◀───────── stdio ── 15 query tools ─┘
```

- **Read-only, permanently.** The only Google endpoints called are `events.list` and `calendarList.list`; the test suite fails the build if a write call or a second OAuth scope ever appears. meet-memory cannot create, move or delete anything on your calendar.
- **Several Google accounts.** Each login gets its own token: `sync_calendar` with `add_account` connects another one. Every calendar can be marked as `meetings` or `tasks`; task calendars remain searchable and can be included in time stats, but do not feed the people ranking.
- **Work and personal contacts can share a calendar.** Marking someone personal preserves their history and keeps them searchable while excluding them from the professional ranking. Categories are always chosen by the user, never inferred.
- Attendees are resolved into **people** by email; free-mail domains (gmail, outlook…) are not treated as organizations.
- One person often has several addresses (work, personal, their own company). `suggest_merges` proposes; nothing is ever merged without you confirming through `merge_people`.
- Only past events count. A backfill makes Google expand recurring series years ahead — those are appointments, not history.
- Solo events (no other attendees) are excluded from meeting counts — they're time blocks, not meetings — but can be included in time stats with `include_solo`.
- Cancelled events are dropped; recurring events are expanded into instances.
- Env vars: `MEET_MEMORY_DB` (db path), `MEET_MEMORY_BACKFILL_YEARS` (default 10), `MEET_MEMORY_TOKENS` (token path).

## Privacy

meet-memory operates no hosted service, account system or telemetry pipeline. Your Google OAuth credentials, refresh tokens and SQLite database remain in `~/.meet-memory/` with owner-only permissions.

Tool results are delivered to the MCP client you configure. If that client uses a cloud-hosted model, the specific names, addresses, meeting titles or aggregates returned by a tool call may be processed by that model provider under its own privacy policy. Use a local model or avoid sensitive queries when that trust boundary is not acceptable.

The OAuth scope is read-only (`calendar.readonly`) and the sign-in flow uses PKCE — see [SECURITY.md](SECURITY.md) for the full threat model, guarantees and known limitations. Using the Calendar API is free: personal use stays far below Google's free quota.

## Development

```bash
git clone https://github.com/arthurglv/meet-memory
cd meet-memory
npm install
npm run build
npm test        # boots the server in demo mode and exercises every tool
npm run dev     # run from source (tsx)
```

`npm test` needs a prior `npm run build`: it spawns the compiled server, not the TypeScript.

## Roadmap

- Publish to npm, so setup is `npx meet-memory` instead of clone and build
- Outlook / iCloud providers
- Meeting notes & transcript enrichment (Meet, Fathom, Circleback)
- CSV export and HTML dashboards

Contributions welcome — open an issue first for anything non-trivial.

## License

[FSL-1.1-MIT](LICENSE) — the [Functional Source License](https://fsl.software/), MIT Future License.

Use it, copy it, modify it, redistribute it, run it inside your company, build client work on
top of it. The one thing you may not do is repackage it as a commercial product or service
that competes with meet-memory. Two years after each release, that release converts
automatically to the plain MIT license.

This is *source-available*, not OSI open source: the OSI definition does not allow
restrictions on commercial use.