feat: implement Mem0 memory backend adapter

.github/workflows/dependency-review.yml

@@ -29,11 +29,24 @@ jobs:
           #   pycparser 3.0, sse-starlette 3.3.2 — MIT per classifiers, scancode misdetects
           # LGPL-*: @img/sharp-libvips-* (Astro image optimization, build-time only)
           # BlueOak-1.0.0: lru-cache, sax (Astro transitive deps, permissive)
+          # LicenseRef-scancode-protobuf: protobuf 5.29.6 (BSD-3-Clause AND scancode-protobuf, permissive)
+          # ZPL-2.1: pytz 2026.1 (MIT AND ZPL-2.1, Zope Public License — permissive)
+          # Null: mem0ai, numpy, qdrant-client, posthog — license metadata missing
+          #   from lockfile but all are permissive (Apache-2.0 / BSD-3-Clause / MIT)
           allow-licenses: >-
             MIT, MIT-0, Apache-2.0, BSD-2-Clause, BSD-3-Clause,
             ISC, MPL-2.0, PSF-2.0, Unlicense, 0BSD,
             CC0-1.0, Python-2.0, Python-2.0.1,
-            LicenseRef-scancode-free-unknown,
+            LicenseRef-scancode-free-unknown, LicenseRef-scancode-protobuf,
+            ZPL-2.1,
             LGPL-2.0-only, LGPL-2.1-only, LGPL-3.0-only, LGPL-3.0-or-later,
             BlueOak-1.0.0
+          # Packages with null/missing SPDX license metadata in lockfile.
+          # Verified manually: mem0ai (Apache-2.0), numpy (BSD-3-Clause),
+          # qdrant-client (Apache-2.0), posthog (MIT).
+          allow-dependencies-licenses: >-
+            pkg:pypi/mem0ai@1.0.5,
+            pkg:pypi/numpy@2.4.3,
+            pkg:pypi/qdrant-client@1.17.0,
+            pkg:pypi/posthog@7.9.12
           comment-summary-in-pr: always

CLAUDE.md

@@ -94,7 +94,7 @@ src/ai_company/
   core/           # Shared domain models, base classes, and resilience config (RetryConfig, RateLimiterConfig)
   engine/         # Agent orchestration, execution loops, parallel execution, task decomposition, routing, task assignment, centralized single-writer task state engine (TaskEngine), task lifecycle, recovery, shutdown, workspace isolation, coordination error classification, prompt policy validation, and AgentEngine-TaskEngine incremental status sync
   hr/             # HR engine: hiring, firing, onboarding, offboarding, agent registry, performance tracking (task metrics, collaboration scoring, trend detection), promotion/demotion (criteria evaluation, approval strategies, model mapping)
-  memory/         # Persistent agent memory (Mem0 initial, custom stack future — see Decision Log), retrieval pipeline (ranking, injection, context formatting, non-inferable filtering), shared org memory (org/), consolidation/archival (consolidation/)
+  memory/         # Persistent agent memory (pluggable MemoryBackend protocol), backends/ (Mem0 adapter: backends/mem0/), retrieval pipeline (ranking, injection, context formatting, non-inferable filtering), shared org memory (org/), consolidation/archival (consolidation/)
   persistence/    # Operational data persistence — pluggable PersistenceBackend protocol, SQLite initial (see Memory & Persistence design page)
   observability/  # Structured logging, correlation tracking, log sinks
   providers/      # LLM provider abstraction (LiteLLM adapter)
@@ -205,4 +205,5 @@ src/ai_company/
 
 - **Pinned**: all versions use `==` in `pyproject.toml`
 - **Groups**: `test` (pytest + plugins), `dev` (includes test + ruff, mypy, pre-commit, commitizen)
+- **Optional**: `mem0ai` (Mem0 memory backend — only needed when `backend: "mem0"` is configured)
 - **Install**: `uv sync` installs everything (dev group is default)

README.md

@@ -127,7 +127,7 @@ graph TB
 
 ## Status
 
-Core framework complete — agent engine, multi-agent coordination, API, security, HR, memory, and budget systems are implemented. Remaining: Mem0 adapter backend, approval workflow gates, CLI, web dashboard. See the [roadmap](docs/roadmap/index.md) for details.
+Core framework complete — agent engine, multi-agent coordination, API, security, HR, memory (including Mem0 backend adapter), and budget systems are implemented. Remaining: approval workflow gates, CLI, web dashboard. See the [roadmap](docs/roadmap/index.md) for details.
 
 ## License
 

docs/design/memory.md

@@ -30,7 +30,7 @@ configuration without modifying application code.
 +----------+----------+-----------+---------------+
 |            Storage Backend                      |
 |   SQLite / PostgreSQL / File-based              |
-|   + Mem0 (initial) / Custom Stack (future)      |
+|   + Mem0 (initial, implemented) / Custom (future)|
 |     See Decision Log                             |
 +-------------------------------------------------+
 ```
@@ -283,6 +283,13 @@ memory:
     max_memories_per_agent: 10000
     consolidation_interval: "daily"
     shared_knowledge_base: true
+
+# Embedder config is passed programmatically via the factory:
+#   create_memory_backend(config, embedder=Mem0EmbedderConfig(
+#       provider="<embedding-provider>",
+#       model="<embedding-model-id>",
+#       dims=1536,
+#   ))
 ```
 
 Configuration is modeled by `CompanyMemoryConfig` (top-level), `MemoryStorageConfig`

docs/roadmap/index.md

@@ -8,7 +8,7 @@ The SynthOrg core framework is complete. The following subsystems are built and
 - Budget and cost management (tracking, enforcement, CFO optimization, quotas)
 - Agent engine (execution loops, parallel execution, task decomposition, routing, assignment, recovery, shutdown)
 - Communication layer (message bus, delegation, loop prevention, conflict resolution, meeting protocol)
-- Memory system (pluggable backend protocol, retrieval pipeline, shared org memory, consolidation)
+- Memory system (pluggable backend protocol, Mem0 adapter, retrieval pipeline, shared org memory, consolidation)
 - Security and approval system (rule engine, output scanning, progressive trust, autonomy levels, timeout policies)
 - Tool system (file system, git, code runner, MCP bridge, sandboxing, permissions)
 - HR engine (hiring, firing, onboarding, offboarding, registry, performance tracking, promotions)
@@ -22,7 +22,6 @@ The SynthOrg core framework is complete. The following subsystems are built and
 
 | Area | Description |
 |------|-------------|
-| **Mem0 adapter** | Concrete `MemoryBackend` implementation using the Mem0 library |
 | **Approval workflow gates** | Runtime wiring for human-in-the-loop approval queues |
 | **CLI** | Terminal interface wrapping the REST API (may not be needed) |
 | **Web dashboard** | Vue 3 frontend for monitoring and managing the synthetic organization |

pyproject.toml

@@ -27,6 +27,9 @@ dependencies = [
     "structlog==25.5.0",
 ]
 
+[project.optional-dependencies]
+mem0 = ["mem0ai==1.0.5"]
+
 [build-system]
 requires = ["hatchling==1.29.0"]
 build-backend = "hatchling.build"
@@ -134,6 +137,7 @@ convention = "google"
     "PLR2004", # magic values in tests
     "SLF001",  # private member access in tests
     "PLC0415", # local imports in test functions
+    "TC",      # type-checking imports (fixture type hints)
 ]
 "__init__.py" = ["F401"]
 "scripts/**/*.py" = [
@@ -184,6 +188,10 @@ ignore_missing_imports = true
 module = "mcp.*"
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = "mem0.*"
+ignore_missing_imports = true
+
 [[tool.mypy.overrides]]
 module = "litestar.*"
 ignore_missing_imports = true

src/ai_company/memory/__init__.py

@@ -3,11 +3,19 @@
 Re-exports protocols (``MemoryBackend``, ``MemoryCapabilities``,
 ``SharedKnowledgeStore``, ``MemoryInjectionStrategy``,
 ``OrgMemoryBackend``, ``ConsolidationStrategy``, ``ArchivalStore``),
-domain models, config models, factory, retrieval pipeline,
-consolidation, org memory, and error hierarchy so consumers can
-import from ``ai_company.memory`` directly.
+concrete backends (``Mem0MemoryBackend``), domain models, config
+models, factory, retrieval pipeline, consolidation, org memory, and
+error hierarchy so consumers can import from ``ai_company.memory``
+directly.
 """
 
+import contextlib
+
+with contextlib.suppress(ImportError):  # mem0ai is optional
+    from ai_company.memory.backends.mem0 import (
+        Mem0EmbedderConfig,
+        Mem0MemoryBackend,
+    )
 from ai_company.memory.capabilities import MemoryCapabilities
 from ai_company.memory.config import (
     CompanyMemoryConfig,
@@ -74,6 +82,8 @@
     "DefaultTokenEstimator",
     "InjectionPoint",
     "InjectionStrategy",
+    "Mem0EmbedderConfig",
+    "Mem0MemoryBackend",
     "MemoryBackend",
     "MemoryCapabilities",
     "MemoryCapabilityError",

src/ai_company/memory/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Concrete memory backend implementations."""
+
+from ai_company.memory.backends.mem0 import Mem0MemoryBackend
+
+__all__ = ["Mem0MemoryBackend"]

src/ai_company/memory/backends/mem0/__init__.py

@@ -0,0 +1,6 @@
+"""Mem0-backed agent memory — adapter, config, and mappers."""
+
+from ai_company.memory.backends.mem0.adapter import Mem0MemoryBackend
+from ai_company.memory.backends.mem0.config import Mem0BackendConfig, Mem0EmbedderConfig
+
+__all__ = ["Mem0BackendConfig", "Mem0EmbedderConfig", "Mem0MemoryBackend"]