feat: add Mengram memory integration

[alibaizhanov]

Summary

• Add MengramMemory as a drop-in replacement for CrewAI's Memory class, backed by Mengram's cloud API
• Supports all three memory types: semantic (entities + knowledge graph), episodic (events with outcomes), and procedural (learned workflows with success/failure tracking)
• Duck-types the Memory interface (same pattern as Hindsight PR feat: add Hindsight memory integration #4448) — pass directly to Crew(memory=mengram_memory)
• Zero external dependencies beyond stdlib (urllib) — self-contained HTTP client
• Graceful degradation on quota limits — crew continues working without memory (no crash)
• 77 fully mocked unit tests, 0 real API calls

Files Changed

File	Change
lib/crewai/src/crewai/memory/storage/mengram_storage.py	New — _MengramClient, MengramConfig, result converters, MengramMemory class (~780 lines)
lib/crewai/tests/storage/test_mengram_storage.py	New — 76 unit tests covering config, remember, recall, forget, reset, drain, close, scope, info, async, client, quota handling (~850 lines)
lib/crewai/pyproject.toml	Add mengram = ["mengram-ai>=2.15.0"] optional dependency
docs/en/concepts/memory.mdx	Add Mengram Memory section with installation, quick start, config table

Usage

from crewai import Crew, Agent, Task
from crewai.memory.storage.mengram_storage import MengramMemory, MengramConfig

memory = MengramMemory(MengramConfig(
    api_key="om-...",  # or set MENGRAM_API_KEY env var
    user_id="my-crew",
))

crew = Crew(
    agents=[agent],
    tasks=[task],
    memory=memory,  # drop-in replacement
)
crew.kickoff()

How It Works

• remember(content) → POST /v1/add_text — Mengram's extraction pipeline automatically discovers entities, facts, relationships, episodes, and procedures
• recall(query, depth="deep") → POST /v1/search/all — unified search across semantic + episodic + procedural memory with knowledge graph traversal and reranking
• recall(query, depth="shallow") → POST /v1/search — fast semantic-only search
• reset() → DELETE /v1/memories/all
• Background saves via ThreadPoolExecutor, drain_writes() before every recall()

No local LLM or embedder needed — Mengram handles extraction, embedding, and search server-side.

Quota Handling

When the Mengram free plan quota is exceeded (HTTP 402):

• remember() silently skips writes — crew continues working
• recall() returns empty results — agents proceed without memory context
• A single warning with upgrade URL is logged (no log spam)
• The crew never crashes due to quota limits

Test plan

• pytest tests/storage/test_mengram_storage.py -v — 77 passed, 0 failed
• Config validation (api_key required, env var fallback, empty rejection)
• Remember (add_text called, MemoryRecord returned, agent_role enrichment, error handling)
• Recall deep (semantic + episodic + procedural, sorted by score, limit respected)
• Recall shallow (semantic only)
• Forget / Reset (delete entity, delete all, error handling)
• Drain writes / Close (futures resolved, pool shutdown, idempotent)
• Result conversion (all 4 types: semantic, episodic, procedural, chunk)
• Async methods (aremember, arecall, aextract_memories)
• HTTP client (auth header, retry on 429, permanent error, request format)
• Quota graceful degradation (402 detection, no retry, no crash, warning once, malformed body fallback)

---

Note

Medium Risk
Adds a new networked memory backend with custom HTTP/retry and background-write logic; while isolated and optional, failures could affect memory availability and latency for adopters.

Overview
Adds a new optional Mengram memory backend (MengramMemory) that duck-types the unified Memory interface so crews can use Mengram’s cloud API for remember/recall/reset (including async wrappers and background remember_many writes with drain_writes() before recall).

Introduces a small stdlib-only HTTP client with retries and explicit quota handling (HTTP 402) to degrade gracefully (skip writes / return empty recalls with a single warning). Also adds a crewai[mengram] extra, comprehensive mocked unit tests for the backend/client, and documentation covering installation and configuration.

^{Written by Cursor Bugbot for commit f438689. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable autofix in the Cursor dashboard.}

[alibaizhanov]

Hey, friendly ping — this is ready for review. Happy to address any feedback.