Metadata-Version: 2.5
Name: agentic-composite-memory
Version: 0.1.0
Summary: Enterprise Multi-Tenant Ontology-Grounded Composite Memory SDK, MCP Server & Platform Service for Google ADK Agents
License: Apache License
        Version 2.0, January 2004
        http://www.apache.org/licenses/
        
        Copyright 2026 Agentic Memory SDK Contributors
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at
        
            http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
License-File: LICENSE
Keywords: a2a,agent-memory,bitemporal,google-adk,knowledge-graph,mcp,neo4j,neptune,ontology,opensearch,pgvector
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: a2a-sdk>=1.1.2
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: fastapi>=0.111.0
Requires-Dist: google-adk[a2a]>=2.8.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: neo4j>=5.20.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: redis>=5.0.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: all
Requires-Dist: azure-identity>=1.16.0; extra == 'all'
Requires-Dist: boto3>=1.34.0; extra == 'all'
Requires-Dist: google-auth>=2.29.0; extra == 'all'
Requires-Dist: opensearch-py[async]>=2.6.0; extra == 'all'
Requires-Dist: pyshacl>=0.26.0; extra == 'all'
Requires-Dist: rdflib>=7.0.0; extra == 'all'
Provides-Extra: aws
Requires-Dist: boto3>=1.34.0; extra == 'aws'
Provides-Extra: azure
Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: pyshacl>=0.26.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: rdflib>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: gcp
Requires-Dist: google-auth>=2.29.0; extra == 'gcp'
Provides-Extra: local-embed
Requires-Dist: sentence-transformers>=3.0.0; extra == 'local-embed'
Provides-Extra: neptune
Requires-Dist: boto3>=1.34.0; extra == 'neptune'
Provides-Extra: ontology
Requires-Dist: pyshacl>=0.26.0; extra == 'ontology'
Requires-Dist: rdflib>=7.0.0; extra == 'ontology'
Provides-Extra: opensearch
Requires-Dist: opensearch-py[async]>=2.6.0; extra == 'opensearch'
Description-Content-Type: text/markdown

# Agentic Composite Memory (`agentic-composite-memory`)

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

---

## Installation

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

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

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

---

## Key Capabilities

1. **3-Layer Ontology-Grounded Memory**:
   - **Layer 0 (Platform Upper Ontology)**: Built-in meta-graph (`p:Actor`, `p:Object`, `p:Event`, `p:Concept`, `p:CandidateConcept`) with zero configuration required.
   - **Layer 1 (Federated Domain Packs)**: Register domain ontologies via **JSON/YAML**, **Python Pydantic models**, or **W3C OWL/SHACL Turtle (`.ttl`)** files using `DomainPackLoader`.
   - **Layer 2 (App-Local Extensions & Emergent Overflow)**: Two-bucket runtime governance (`TBoxRuntimeValidator`) routes validated facts to `domain:{tenant}:{domain}` and novel concepts to `app:{tenant}:{app}` with automated ontology promotion (`evolve_app_ontology_from_overflow`).

2. **3-Tier Context Graph + Procedural Playbooks**:
   - **Tier 1 (Episodic & Seed Store)**: Hybrid RRF search (`pgvector` HNSW + BM25 GIN) with pinned user preferences and `PIIScrubber`.
   - **Tier 2 (Bi-Temporal Semantic Knowledge Graph)**: Multi-hop reasoning (`max_hops=2`), temporal edge invalidation (`t_valid`, `t_invalid`), and `EntityResolutionGuard`.
   - **Tier 3 (Procedural Reasoning Traces & Playbooks)**: Records agent tool-call trajectories and caches high-reward reusable playbooks.

3. **Hot-Path vs. Sleep-Time Batch Extraction**:
   - `ExtractionMode.HOT_PATH`: Immediate LLM/rule ontology extraction on every turn.
   - `ExtractionMode.SLEEP_TIME_BATCH`: Sub-10ms raw episodic write on the hot path, with background batch ontology extraction during `run_memory_maintenance()`.

4. **Independent Per-Port or Single-Stack Database Adapters**:
   - Run **100% on PostgreSQL** (`CompositeMemoryService.from_postgres_stack`), **100% on Redis** (`CompositeMemoryService.from_redis_stack`), or **Mix-and-Match** per port (e.g., PostgreSQL + Neo4j/Neptune + Redis).
   - Built-in **Enterprise Cloud DB Auth** (`AwsIamDatabaseAuthProvider`, `GcpCloudSqlIamAuthProvider`, `AzureEntraDatabaseAuthProvider`, `VaultOrSecretManagerAuthProvider`, and `EnterpriseTlsConfig` mTLS).

5. **Multi-Provider LLM & Embedding Adapters**:
   - Google **Gemini**, **Amazon Bedrock** (Claude/Nova + Titan/Cohere Embeddings), **OpenAI / Azure OpenAI / vLLM**, **Ollama**, and local **SentenceTransformers**.

6. **Unified FastAPI + MCP Server in One Pod**:
   - `adk-memory serve-api` serves both REST (`/v1/...`) and MCP (`/mcp/http`, `/mcp/sse`, `/v1/mcp/tools`, `/v1/mcp/call`) simultaneously.

---

## Quickstart

### 1. Single-Stack PostgreSQL or Redis Factory

```python
from agentic_memory_sdk import (
    CompositeMemoryService,
    BedrockEmbeddingAdapter,
    BedrockOntologyExtractorAdapter,
    AwsIamDatabaseAuthProvider,
)

# Example: 100% PostgreSQL stack with AWS RDS IAM Auth + Amazon Bedrock
auth = AwsIamDatabaseAuthProvider(region="us-east-1", service="rds-db")
service = CompositeMemoryService.from_postgres_stack(
    dsn="postgresql://iam_user@mydb.cluster.us-east-1.rds.amazonaws.com:5432/memory",
    embedding_adapter=BedrockEmbeddingAdapter(region="us-east-1", target_dim=16),
    extractor_adapter=BedrockOntologyExtractorAdapter(region="us-east-1"),
    auth_provider=auth,
)
```

### 2. Extending `agentic-memory-sdk` with Custom Adapters

Every boundary in `agentic-memory-sdk` is a structural `typing.Protocol` in `agentic_memory_sdk.ports` and `agentic_memory_sdk.auth`. You can extend any port without subclassing internal classes:

```python
from agentic_memory_sdk.ports import EmbeddingAdapter, PlaybookStoreAdapter
from agentic_memory_sdk.models import PlaybookRecord

class MyCustomEmbeddingAdapter:
    """Implements EmbeddingAdapter Protocol via structural subtyping."""
    async def embed(self, text: str) -> list[float]:
        # Call your custom internal embedding gateway
        return [0.1] * 16
```

### 3. Running the Unified FastAPI + MCP Server

```bash
# Start unified REST + MCP server on port 8095
adk-memory serve-api --host 0.0.0.0 --port 8095 --mode in_memory
```
