feat: MongoMemory — drop-in persistent Memory backend for mcp-agent + Atlas Vector Search recall

Author: Pash10g

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "mongodb@claude-plugins-official": true
+  }
+}

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run acceptance suite (offline; Atlas handshake test auto-skips)
+        env:
+          # ATLAS_URI is intentionally unset in CI → the live handshake test skips.
+          # Set it as a repo secret to exercise the Atlas path.
+          ATLAS_URI: ${{ secrets.ATLAS_URI }}
+        run: pytest tests/ -v
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*

.github/workflows/release.yml

@@ -0,0 +1,76 @@
+name: Release
+
+# Publishes to PyPI via Trusted Publishing (OIDC) — no API tokens stored.
+# Trigger: push a version tag (e.g. v0.1.0) OR run manually for a TestPyPI dry-run.
+#
+# One-time setup on PyPI (and TestPyPI) → Project → Publishing → "Add a pending publisher":
+#   Owner:        mongodb-developer
+#   Repository:   mcp-agent-mongodb
+#   Workflow:     release.yml
+#   Environment:  pypi   (and  testpypi  for the test index)
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        type: choice
+        default: testpypi
+        options: [testpypi, pypi]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    # Only on manual dry-runs; tag pushes go straight to PyPI (publish-pypi).
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'testpypi'
+
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write   # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: startsWith(github.ref, 'refs/tags/v') || github.event.inputs.target == 'pypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,33 @@
+# Internal build plan & helper artifacts — not shipped with the package/repo
+PLAN.md
+
+# Internal outreach drafts — not part of the public package/repo
+outreach/
+
+# Secrets / local env
+.env
+demo/.env
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python build / packaging artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+pip-wheel-metadata/
+
+# Caches & bytecode
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS / editor cruft
+.DS_Store

AGENTS.md

@@ -0,0 +1,74 @@
+# AGENTS.md — guide for AI coding agents
+
+A structured guide for AI agents working in `mcp-agent-mongodb`: how to build and test,
+where key files live, and the MongoDB-specific rules to follow.
+
+## Build and test commands
+
+```bash
+# Install (editable) + dev deps
+pip install -e ".[dev]"
+
+# Run the test suite (mongomock — no infra required)
+pytest -q                # 17 tests
+
+# Demos (need Atlas + keys; see demo/.env: ATLAS_URI, VOYAGE_API_KEY, GEMINI_API_KEY)
+pip install -e ".[dev]" "mcp-agent" "google-genai" voyageai
+python demo/memory_demo.py                  # bring-your-own Voyage vectors
+MEMORY_MODE=auto python demo/memory_demo.py # Atlas Automated Embedding
+python demo/agent_demo.py                   # Gemini agent, cross-session memory
+```
+
+## Project structure
+
+- `src/mcp_agent_mongodb/memory.py` — `MongoMemory` (the `Memory` adapter + vector recall).
+- `src/mcp_agent_mongodb/__init__.py` — public exports + `__version__`.
+- `tests/test_acceptance.py` — acceptance tests (mongomock; Atlas handshake test auto-skips).
+- `demo/` — runnable demos over Atlas (`memory_demo.py`, `agent_demo.py`).
+- `EDD.md` — the MongoDB data model (source of truth for schema).
+- `PLAN.md` — the integration plan (phases + acceptance criteria).
+
+## Upstream extension point
+
+mcp-agent's `Memory[MessageParamT]` base class
+(`mcp_agent/workflows/llm/augmented_llm.py`) defines `extend` / `set` / `append` / `get` /
+`clear`. `AugmentedLLM.__init__` assigns `self.history = SimpleMemory()`, so `MongoMemory`
+is a **drop-in**: just set `llm.history = MongoMemory(...)`. Messages are arbitrary
+`MessageParamT` (provider message objects such as `google.genai.types.Content`, or dicts).
+
+## Environment variables and configuration
+
+| Name | Required | Description |
+|---|---|---|
+| `ATLAS_URI` | demos / vector tests | Atlas connection string |
+| `VOYAGE_API_KEY` | bring-your-own embedding demos | Voyage AI key for `voyage-3.5` |
+| `GEMINI_API_KEY` | agent demo | Gemini (Google AI) key |
+| `MEMORY_MODE` | optional | `auto` to use Atlas Automated Embedding in `memory_demo.py` |
+
+## Conventions (do not break)
+
+- The package **owns its `MongoClient`** — built from a connection string. `appName`
+  (`devrel-integ-mcp-agent-python`) and the `mcp-agent-mongodb` driver-info handshake are
+  always set and **non-overridable** (caller `appname`/`appName`/`driver` are stripped).
+- Embeddings use **Voyage AI 3.5** (`voyage-3.5`, 1024-dim) on the bring-your-own path.
+- No silent embedding fallback: `recall_semantic` raises if neither `query_vector` nor
+  `auto_embed` is provided.
+- `get()` preserves insertion order via the per-session `seq` counter.
+
+## MongoDB Skills
+
+Use the official MongoDB agent skills from https://github.com/mongodb/agent-skills
+whenever the task is MongoDB-specific and a matching skill exists.
+
+## When To Use EDD.md
+
+Use [EDD.md](./EDD.md) as the source of truth for the MongoDB data model in this repository.
+
+Consult [EDD.md](./EDD.md) before making changes that touch:
+
+- The `memory` collection, document structure, or field names
+- Code paths that read or write database records (`memory.py`)
+- Index definitions (the `(session_id, seq)` index, optional TTL on `ts`, the Atlas Vector
+  Search index)
+- Validation, payloads, or anything that depends on persisted data
+- Schema documentation, Mermaid diagrams, or entity modeling discussions

EDD.md

@@ -0,0 +1,80 @@
+# EDD.md — Entity Document Diagram
+
+The MongoDB data model for `mcp-agent-mongodb`. A single collection, `memory`, backs
+`MongoMemory`. Keep this in sync with `src/mcp_agent_mongodb/memory.py`.
+
+## Entities
+
+### `memory` (database `mcp_agent`)
+
+One document per message in an agent's conversation history. Documents are scoped by
+`session_id` and ordered by a monotonic `seq` (0-based, contiguous per session).
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `_id` | ObjectId | yes | Primary key (auto) |
+| `session_id` | string | yes | Conversation / agent scope key |
+| `seq` | int | yes | Monotonic order within the session (insertion order) |
+| `role` | string \| null | no | Best-effort role extracted from the message (`user`/`assistant`/…) |
+| `message` | object | yes | The serialized message, returned verbatim by `get()` |
+| `content` | string \| null | no | Best-effort text for embedding / recall |
+| `embedding` | double[1024] | bring-your-own path only | Voyage 3.5 vector |
+| `ts` | date | yes | Insert time (UTC); TTL anchor when enabled |
+
+```json
+{
+  "_id": { "$oid": "…" },
+  "session_id": "user-123",
+  "seq": 7,
+  "role": "user",
+  "message": { "role": "user", "parts": [ { "text": "summarize the Q3 report" } ] },
+  "content": "summarize the Q3 report",
+  "embedding": [0.01, "… 1024 dims …"],
+  "ts": { "$date": "2025-01-01T00:00:00Z" }
+}
+```
+
+## Indexes
+
+- Order index: `{ session_id: 1, seq: 1 }` (`session_seq`) — ordered retrieval + append cursor.
+- Optional TTL: `{ ts: 1 }, expireAfterSeconds=ttl_seconds` (`ttl_ts`).
+- Atlas Vector Search index `idx_agent_memory` over `embedding`
+  (`numDimensions: 1024`, cosine, with a `session_id` filter) — or an `autoEmbed` index
+  over `content` when `auto_embed=True` (Atlas Automated Embedding, recall by query text).
+
+## Surface contract → MongoDB ops
+
+| `Memory` method | MongoDB operation |
+|---|---|
+| `append(message)` | `insert_one` with next `seq` for `session_id` |
+| `extend(messages)` | `insert_many` with contiguous `seq` values |
+| `set(messages)` | `delete_many({session_id})` then `insert_many` |
+| `get()` | `find({session_id}).sort(seq)` → original messages |
+| `clear()` | `delete_many({session_id})` |
+| `recall_semantic(...)` | `$vectorSearch` over `embedding`, `session_id` prefilter |
+
+## Relationships
+
+```mermaid
+erDiagram
+    SESSION ||--o{ MESSAGE : "owns ordered history"
+    MESSAGE {
+        objectId _id
+        string session_id
+        int seq
+        string role
+        object message
+        string content
+        double[] embedding
+        date ts
+    }
+```
+
+## Notes
+
+- `MongoMemory` is a drop-in for mcp-agent's `SimpleMemory` (`llm.history = MongoMemory(...)`).
+- `message` stores arbitrary provider message objects (e.g. `google.genai.types.Content`);
+  pass `message_model=` to rehydrate them into model instances on `get()`.
+- Demo seed data uses the conversation turns created at runtime; the shared
+  `data/embeddings.json` corpus is available for larger semantic-recall experiments.
+- appName: `devrel-integ-mcp-agent-python`; driver-info: `mcp-agent-mongodb`.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MongoDB, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.