Agentic Composite Memory (agentic-composite-memory)

An enterprise-grade, domain-agnostic, multi-tenant Composite Memory SDK, FastAPI Service & Model Context Protocol (MCP) Server engineered for Google Agent Development Kit (ADK) and multi-agent A2A ecosystems.

Documentation Hub (docs/)

• Documentation Index
• Architecture, 3-Layer Ontology & 3-Tier Context Graph Guide
• Real-World Usage, Retail/SRE Domain Suites & The 3 Agent Consumption Patterns (SDK, FastAPI, MCP)
• FastAPI REST, MCP Protocol (2026-07-28 / 2025-11-25) & CLI Reference
• Local Setup, Docker Stack & PyPI Testing Guide
• PostgreSQL RLS + pgvector HNSW Partitioned DDL

Installation

# Core SDK, ADK Integration, FastAPI + MCP Server, Postgres/Redis/Neo4j adapters
pip install agentic-composite-memory

# With Cloud IAM Auth & Bedrock / GCP / Azure / Ontology extras
pip install "agentic-composite-memory[aws,gcp,azure,ontology]"

# Everything included
pip install "agentic-composite-memory[all]"

Both import names are supported out of the box:

from agentic_composite_memory import CompositeMemoryService, RemoteCompositeMemoryService
# or
from agentic_memory_sdk import CompositeMemoryService, RemoteCompositeMemoryService

Why agentic-composite-memory?

+-----------------------------------------------------------------------------------+
| LAYER 0: PLATFORM UPPER ONTOLOGY (Mandatory for 100% of Agent Apps, Zero-Config)  |
|   Classes:    p:Actor, p:Object, p:Event, p:Concept, p:CandidateConcept,          |
|               p:UserPreference                                                    |
+-----------------------------------------+-----------------------------------------+
                                          | rdfs:subClassOf / Extends
          +-------------------------------+-------------------------------+
          v                                                               v
+-----------------------------------------+     +-----------------------------------+
| LAYER 1: FEDERATED DOMAIN PACKS         |     | LAYER 2: APP-LOCAL EXTENSIONS     |
| (Plug-and-Play Shared Business TBoxes)  |     | (Self-Service / Emergent Schema)  |
|   - retail_omnichannel@1.0.0 (.json/.ttl)|    |   - Quarantined overflow in       |
|   - sre_infra@v1.2 (JSON / YAML)        |     |     `app:{tenant}:{app}`          |
|   - customer_crm@v2.0 (Pydantic)        |     |   - Auto-evolution to Domain TBox |
+-----------------------------------------+     +-----------------------------------+

1. 3-Layer Domain-Agnostic Ontology:

   • Layer 0 (Platform Upper Ontology): Built-in meta-graph (p:Actor, p:Object, p:Event, p:Concept, p:CandidateConcept, p:UserPreference) requiring zero upfront configuration.
   • Layer 1 (Federated Domain Packs): Register domain ontologies for Retail & Supply Chain, SRE & Cloud Ops, Healthcare, FinOps, or Customer CRM via JSON/YAML, Python Pydantic models, or W3C OWL/SHACL Turtle (.ttl) files using DomainPackLoader.
   • Layer 2 (Two-Bucket Runtime Governance & Auto-Evolution): TBoxRuntimeValidator routes validated facts to domain:{tenant}:{domain} and quarantines novel/low-confidence extractions in app:{tenant}:{app}, with automated promotion via evolve_app_ontology_from_overflow().

2. 3-Tier Context Graph + Procedural Playbooks:

   • Tier 1 (Episodic & Seed Store): Hybrid Reciprocal Rank Fusion (RRF) search (pgvector HNSW + BM25 GIN) with pinned cross-app user preferences (user:{tenant}:{user_id}) and PIIScrubber.
   • Tier 2 (Bi-Temporal Semantic Knowledge Graph): Multi-hop reasoning (max_hops=2), automatic functional edge invalidation (t_valid, t_invalid), point-in-time historical queries (as_of_iso), and EntityResolutionGuard (preventing false merges of numbered/regional siblings like FC-Seattle-01 vs FC-Seattle-02).
   • Tier 3 (Procedural Reasoning Traces & Playbooks): Records agent tool-call trajectories and caches high-reward reusable workflows ([MATCHED_PROCEDURAL_PLAYBOOKS]).

3. Hot-Path vs. Sleep-Time Batch Extraction (ExtractionMode):

   • ExtractionMode.HOT_PATH: Immediate LLM/rule ontology extraction on every turn.
   • ExtractionMode.SLEEP_TIME: Sub-10ms raw episodic write on the hot path, with background batch ontology extraction, session compaction ([AUTO_SESSION_SUMMARY]), and Layer-3 Entity Dossier synthesis ([Dossier: ...]) during run_memory_maintenance().

4. Independent Per-Port or Single-Stack Database Adapters + Cloud Auth:

   • Run 100% on PostgreSQL (CompositeMemoryService.from_postgres_stack), 100% on Redis (CompositeMemoryService.from_redis_stack), or Mix-and-Match per port (PostgreSQL + Neo4j/Neptune + Redis).
   • Built-in Enterprise Cloud DB Auth (AwsIamDatabaseAuthProvider for RDS/Aurora/Neptune/ElastiCache + STS AssumeRole, GcpCloudSqlIamAuthProvider, AzureEntraDatabaseAuthProvider, VaultOrSecretManagerAuthProvider, and EnterpriseTlsConfig mTLS).

5. Multi-Provider LLM & Embedding Adapters:

   • Google Gemini, Amazon Bedrock (Converse API + Titan/Cohere Embeddings), OpenAI / Azure OpenAI / vLLM, Ollama, and local SentenceTransformers.

6. 100% Data-Plane + Control-Plane Parity Across SDK, FastAPI & MCP (2026-07-28 / 2025-11-25):

   • adk-memory serve-api co-hosts both REST (/v1/...) and the latest MCP 2026-07-28 Stateless Request/Response Core & 2025-11-25 Streamable HTTP (/mcp/http/, /mcp/sse, /v1/mcp/tools, /v1/mcp/call) with 11 Annotated Tools, 4 Live Resources, and 2 Workflow Prompts.

The 3 Agent Consumption Patterns

Pattern 1: Direct In-Process Python SDK (CompositeMemoryService)

from agentic_composite_memory import (
    AwsIamDatabaseAuthProvider,
    BedrockEmbeddingAdapter,
    BedrockOntologyExtractorAdapter,
    CompositeMemoryService,
)

auth = AwsIamDatabaseAuthProvider(
    region="us-east-1",
    service="rds-db",
    db_user="memory_iam_user",
    host="mydb.cluster-xyz.us-east-1.rds.amazonaws.com",
)
service = CompositeMemoryService.from_postgres_stack(
    dsn="postgresql://mydb.cluster-xyz.us-east-1.rds.amazonaws.com:5432/memory",
    embedding_adapter=BedrockEmbeddingAdapter(region="us-east-1", target_dim=1536),
    extractor_adapter=BedrockOntologyExtractorAdapter(region="us-east-1"),
    auth_provider=auth,
)

Pattern 2: Co-Hosted FastAPI Service + RemoteCompositeMemoryService

from google.adk.agents import LlmAgent
from google.adk.runners import Runner
from agentic_composite_memory import (
    RemoteCompositeMemoryService,
    get_adk_memory_tools,
    non_blocking_memory_commit_callback,
)

remote_memory = RemoteCompositeMemoryService(base_url="http://memory-platform:8095")

agent = LlmAgent(
    name="order_concierge",
    model="gemini-2.5-flash",
    tools=get_adk_memory_tools(remote_memory, default_app_name="nordstrom_global:order_concierge"),
    after_agent_callback=non_blocking_memory_commit_callback,
)

runner = Runner(app_name="nordstrom_global:order_concierge", agent=agent, memory_service=remote_memory)

Pattern 3: Model Context Protocol (MCP 2026-07-28 & 2025-11-25 Server)

# Start unified FastAPI REST (/v1/*) + MCP (/mcp/http/, /mcp/sse, /v1/mcp/*) server on port 8095
adk-memory serve-api --host 0.0.0.0 --port 8095 --mode in_memory

# Or run standalone stdio MCP server for Claude Desktop / Cursor / Windsurf
adk-memory serve-mcp --mode in_memory

Claude Desktop / Cursor / Windsurf mcpServers Config (Streamable HTTP or stdio):

{
  "mcpServers": {
    "agentic-composite-memory": {
      "command": "uvx",
      "args": ["--from", "agentic-composite-memory", "adk-memory", "serve-mcp", "--mode", "in_memory"]
    }
  }
}

Complete Platform Parity Matrix (SDK vs. FastAPI vs. MCP)

See docs/api_and_mcp_reference.md for full request/response schemas and curl examples.

Local Setup & Testing the Package (Docker Postgres + Neo4j + Redis)

You can test the full multi-backend platform locally using the included docker-compose.yml:

# 1. Start PostgreSQL 16 (pgvector + RLS), Neo4j 5, and Redis 7
docker compose up -d --wait

# 2. Run the standalone unit & platform test suite (13 tests)
uv run --extra dev pytest tests/test_composite_memory_platform.py -v

# 3. Run the live Docker + Multi-Agent Google ADK A2A E2E suite
uv run --extra dev pytest tests/test_a2a_docker_e2e.py -v -s

# 4. Run the 4-Agent Omnichannel Retail Suite & 3 Consumption Patterns (SDK, FastAPI, MCP) Demo
uv run python examples/retail_omnichannel_suite.py
uv run python examples/three_consumption_patterns_demo.py

# 5. Run the 5-Agent Enterprise Stress & Maturity Benchmark against live Docker
uv run python examples/realistic_enterprise_stress_test.py

# 6. Test the published PyPI package in an isolated environment against live Docker
uv run --isolated --no-project --refresh --with "agentic-composite-memory[all]" \
  python examples/realistic_enterprise_stress_test.py

See docs/local_setup_and_testing.md for a complete breakdown of the 5-agent enterprise benchmark and measured latencies.

License

Licensed under the Apache License, Version 2.0 — see LICENSE and NOTICE.