agentic-composite-memory 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agentic_composite_memory/__init__.py +2 -0
- agentic_composite_memory/py.typed +0 -0
- agentic_composite_memory-0.1.0.dist-info/METADATA +167 -0
- agentic_composite_memory-0.1.0.dist-info/RECORD +31 -0
- agentic_composite_memory-0.1.0.dist-info/WHEEL +4 -0
- agentic_composite_memory-0.1.0.dist-info/entry_points.txt +2 -0
- agentic_composite_memory-0.1.0.dist-info/licenses/LICENSE +17 -0
- agentic_memory_sdk/__init__.py +163 -0
- agentic_memory_sdk/adapters/__init__.py +33 -0
- agentic_memory_sdk/adapters/in_memory.py +439 -0
- agentic_memory_sdk/adapters/neo4j_cypher.py +65 -0
- agentic_memory_sdk/adapters/neptune_cypher.py +309 -0
- agentic_memory_sdk/adapters/opensearch_seed.py +322 -0
- agentic_memory_sdk/adapters/postgres_pgvector.py +484 -0
- agentic_memory_sdk/adapters/postgres_unified.py +511 -0
- agentic_memory_sdk/adapters/redis_playbook.py +157 -0
- agentic_memory_sdk/adapters/redis_unified.py +490 -0
- agentic_memory_sdk/adk_integration.py +250 -0
- agentic_memory_sdk/auth.py +380 -0
- agentic_memory_sdk/cli.py +137 -0
- agentic_memory_sdk/governance.py +713 -0
- agentic_memory_sdk/llm_extractors.py +616 -0
- agentic_memory_sdk/models.py +443 -0
- agentic_memory_sdk/ontology_loader.py +189 -0
- agentic_memory_sdk/ports.py +159 -0
- agentic_memory_sdk/py.typed +0 -0
- agentic_memory_sdk/server/__init__.py +4 -0
- agentic_memory_sdk/server/api.py +328 -0
- agentic_memory_sdk/server/main.py +384 -0
- agentic_memory_sdk/server/mcp_server.py +198 -0
- agentic_memory_sdk/service.py +1214 -0
|
@@ -0,0 +1,384 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import os
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
|
|
6
|
+
from ..adapters import (
|
|
7
|
+
InMemoryUnifiedAdapter,
|
|
8
|
+
Neo4jGraphAdapter,
|
|
9
|
+
PostgresGraphAdapter,
|
|
10
|
+
PostgresPgVectorAdapter,
|
|
11
|
+
PostgresPlaybookAdapter,
|
|
12
|
+
RedisEpisodicAndSeedAdapter,
|
|
13
|
+
RedisGraphAdapter,
|
|
14
|
+
RedisPlaybookAndWorkingAdapter,
|
|
15
|
+
RedisRegistryAdapter,
|
|
16
|
+
)
|
|
17
|
+
from ..governance import PlatformOntologyRegistrar
|
|
18
|
+
from ..llm_extractors import (
|
|
19
|
+
BedrockEmbeddingAdapter,
|
|
20
|
+
BedrockOntologyExtractorAdapter,
|
|
21
|
+
DeterministicHashEmbeddingAdapter,
|
|
22
|
+
GeminiEmbeddingAdapter,
|
|
23
|
+
GeminiOntologyExtractorAdapter,
|
|
24
|
+
LocalSentenceTransformerEmbeddingAdapter,
|
|
25
|
+
OllamaEmbeddingAdapter,
|
|
26
|
+
OllamaOntologyExtractorAdapter,
|
|
27
|
+
OpenAICompatibleEmbeddingAdapter,
|
|
28
|
+
OpenAICompatibleOntologyExtractorAdapter,
|
|
29
|
+
RuleBasedMockExtractorAdapter,
|
|
30
|
+
)
|
|
31
|
+
from ..models import (
|
|
32
|
+
ExtractedEntity,
|
|
33
|
+
ExtractedFact,
|
|
34
|
+
ExtractionPayload,
|
|
35
|
+
)
|
|
36
|
+
from ..ontology_loader import DomainPackLoader
|
|
37
|
+
from ..service import CompositeMemoryService
|
|
38
|
+
from .api import create_memory_platform_app
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def build_default_rule_extractor() -> RuleBasedMockExtractorAdapter:
|
|
42
|
+
"""
|
|
43
|
+
Configures domain-aware extraction rules for deterministic local & Docker testing
|
|
44
|
+
when `GOOGLE_API_KEY` is not set or `MEMORY_FAKE_LLM=1`.
|
|
45
|
+
"""
|
|
46
|
+
extractor = RuleBasedMockExtractorAdapter()
|
|
47
|
+
|
|
48
|
+
# SRE Domain Rules
|
|
49
|
+
extractor.add_keyword_rule(
|
|
50
|
+
"checkout-api is deployed in us-east-1",
|
|
51
|
+
ExtractionPayload(
|
|
52
|
+
entities=[
|
|
53
|
+
ExtractedEntity(
|
|
54
|
+
canonical_name="checkout-api",
|
|
55
|
+
entity_class="Microservice",
|
|
56
|
+
summary="Core checkout payment microservice",
|
|
57
|
+
confidence=0.95,
|
|
58
|
+
),
|
|
59
|
+
ExtractedEntity(
|
|
60
|
+
canonical_name="us-east-1",
|
|
61
|
+
entity_class="CloudRegion",
|
|
62
|
+
summary="AWS US East N. Virginia region",
|
|
63
|
+
confidence=0.95,
|
|
64
|
+
),
|
|
65
|
+
ExtractedEntity(
|
|
66
|
+
canonical_name="aurora-payments-01",
|
|
67
|
+
entity_class="DatabaseCluster",
|
|
68
|
+
summary="Primary Aurora PostgreSQL cluster for checkout",
|
|
69
|
+
confidence=0.95,
|
|
70
|
+
),
|
|
71
|
+
],
|
|
72
|
+
facts=[
|
|
73
|
+
ExtractedFact(
|
|
74
|
+
source_entity="checkout-api",
|
|
75
|
+
source_class="Microservice",
|
|
76
|
+
predicate="DEPLOYED_IN_PRIMARY",
|
|
77
|
+
target_entity="us-east-1",
|
|
78
|
+
target_class="CloudRegion",
|
|
79
|
+
fact_summary="checkout-api primary region is us-east-1",
|
|
80
|
+
confidence=0.95,
|
|
81
|
+
valid_from="2026-01-15T00:00:00Z",
|
|
82
|
+
),
|
|
83
|
+
ExtractedFact(
|
|
84
|
+
source_entity="checkout-api",
|
|
85
|
+
source_class="Microservice",
|
|
86
|
+
predicate="READS_FROM",
|
|
87
|
+
target_entity="aurora-payments-01",
|
|
88
|
+
target_class="DatabaseCluster",
|
|
89
|
+
fact_summary="checkout-api reads from aurora-payments-01",
|
|
90
|
+
confidence=0.95,
|
|
91
|
+
valid_from="2026-01-15T00:00:00Z",
|
|
92
|
+
),
|
|
93
|
+
],
|
|
94
|
+
),
|
|
95
|
+
)
|
|
96
|
+
|
|
97
|
+
extractor.add_keyword_rule(
|
|
98
|
+
"failed checkout-api over to us-west-2",
|
|
99
|
+
ExtractionPayload(
|
|
100
|
+
entities=[
|
|
101
|
+
ExtractedEntity(
|
|
102
|
+
canonical_name="checkout-api",
|
|
103
|
+
entity_class="Microservice",
|
|
104
|
+
summary="Core checkout payment microservice (failed over to us-west-2)",
|
|
105
|
+
confidence=0.96,
|
|
106
|
+
),
|
|
107
|
+
ExtractedEntity(
|
|
108
|
+
canonical_name="us-west-2",
|
|
109
|
+
entity_class="CloudRegion",
|
|
110
|
+
summary="AWS US West Oregon failover region",
|
|
111
|
+
confidence=0.96,
|
|
112
|
+
),
|
|
113
|
+
ExtractedEntity(
|
|
114
|
+
canonical_name="experimental-chaos-mesh",
|
|
115
|
+
entity_class="UnregisteredChaosTool",
|
|
116
|
+
summary="Emergent chaos engineering tool used during failover",
|
|
117
|
+
confidence=0.90,
|
|
118
|
+
),
|
|
119
|
+
],
|
|
120
|
+
facts=[
|
|
121
|
+
ExtractedFact(
|
|
122
|
+
source_entity="checkout-api",
|
|
123
|
+
source_class="Microservice",
|
|
124
|
+
predicate="DEPLOYED_IN_PRIMARY",
|
|
125
|
+
target_entity="us-west-2",
|
|
126
|
+
target_class="CloudRegion",
|
|
127
|
+
fact_summary="checkout-api failed over to primary region us-west-2",
|
|
128
|
+
confidence=0.96,
|
|
129
|
+
valid_from="2026-11-01T00:00:00Z",
|
|
130
|
+
),
|
|
131
|
+
ExtractedFact(
|
|
132
|
+
source_entity="checkout-api",
|
|
133
|
+
source_class="Microservice",
|
|
134
|
+
predicate="TESTED_WITH_UNREGISTERED_TOOL",
|
|
135
|
+
target_entity="experimental-chaos-mesh",
|
|
136
|
+
target_class="UnregisteredChaosTool",
|
|
137
|
+
fact_summary="checkout-api was tested with experimental-chaos-mesh",
|
|
138
|
+
confidence=0.90,
|
|
139
|
+
valid_from="2026-11-01T00:00:00Z",
|
|
140
|
+
),
|
|
141
|
+
],
|
|
142
|
+
),
|
|
143
|
+
)
|
|
144
|
+
|
|
145
|
+
# CRM Domain Rules
|
|
146
|
+
extractor.add_keyword_rule(
|
|
147
|
+
"acme-corp upgraded to enterprise-platinum",
|
|
148
|
+
ExtractionPayload(
|
|
149
|
+
entities=[
|
|
150
|
+
ExtractedEntity(
|
|
151
|
+
canonical_name="Acme-Corp",
|
|
152
|
+
entity_class="CustomerAccount",
|
|
153
|
+
summary="Strategic enterprise customer Acme-Corp",
|
|
154
|
+
confidence=0.95,
|
|
155
|
+
),
|
|
156
|
+
ExtractedEntity(
|
|
157
|
+
canonical_name="Enterprise-Platinum",
|
|
158
|
+
entity_class="SubscriptionPlan",
|
|
159
|
+
summary="Highest-tier Enterprise Platinum subscription",
|
|
160
|
+
confidence=0.95,
|
|
161
|
+
),
|
|
162
|
+
],
|
|
163
|
+
facts=[
|
|
164
|
+
ExtractedFact(
|
|
165
|
+
source_entity="Acme-Corp",
|
|
166
|
+
source_class="CustomerAccount",
|
|
167
|
+
predicate="SUBSCRIBED_TO_TIER",
|
|
168
|
+
target_entity="Enterprise-Platinum",
|
|
169
|
+
target_class="SubscriptionPlan",
|
|
170
|
+
fact_summary="Acme-Corp is subscribed to Enterprise-Platinum tier",
|
|
171
|
+
confidence=0.95,
|
|
172
|
+
valid_from="2026-11-05T00:00:00Z",
|
|
173
|
+
)
|
|
174
|
+
],
|
|
175
|
+
),
|
|
176
|
+
)
|
|
177
|
+
|
|
178
|
+
return extractor
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
def build_platform_service_from_env() -> tuple[CompositeMemoryService, PlatformOntologyRegistrar]:
|
|
182
|
+
"""
|
|
183
|
+
Builds `CompositeMemoryService` from environment variables.
|
|
184
|
+
Supports either a high-level stack preset (`MEMORY_BACKEND`):
|
|
185
|
+
- `MEMORY_BACKEND=docker` -> Postgres Seed + Neo4j Graph + Redis Playbook
|
|
186
|
+
- `MEMORY_BACKEND=postgres_only` -> Pure PostgreSQL (`PostgresUnifiedAdapter`)
|
|
187
|
+
- `MEMORY_BACKEND=redis_only` -> Pure Redis (`RedisUnifiedAdapter`)
|
|
188
|
+
- `MEMORY_BACKEND=memory` -> Zero-dependency `InMemoryUnifiedAdapter`
|
|
189
|
+
OR independent per-port backend selection:
|
|
190
|
+
- `ADK_REGISTRY_BACKEND=postgres|redis|memory`
|
|
191
|
+
- `ADK_SEED_BACKEND=postgres|redis|memory`
|
|
192
|
+
- `ADK_GRAPH_BACKEND=neo4j|postgres|redis|memory`
|
|
193
|
+
- `ADK_PLAYBOOK_BACKEND=redis|postgres|memory`
|
|
194
|
+
"""
|
|
195
|
+
backend = os.environ.get("MEMORY_BACKEND", "docker").lower()
|
|
196
|
+
use_live_gemini = os.environ.get("MEMORY_LIVE_GEMINI", "0") == "1" and bool(
|
|
197
|
+
os.environ.get("GOOGLE_API_KEY")
|
|
198
|
+
)
|
|
199
|
+
emb_provider = os.environ.get(
|
|
200
|
+
"ADK_EMBEDDING_PROVIDER",
|
|
201
|
+
"gemini" if use_live_gemini else "deterministic",
|
|
202
|
+
).lower()
|
|
203
|
+
llm_provider = os.environ.get(
|
|
204
|
+
"ADK_LLM_PROVIDER",
|
|
205
|
+
"gemini" if use_live_gemini else "rules",
|
|
206
|
+
).lower()
|
|
207
|
+
|
|
208
|
+
if emb_provider == "gemini":
|
|
209
|
+
embedder = GeminiEmbeddingAdapter(
|
|
210
|
+
model=os.environ.get("ADK_EMBEDDING_MODEL", "text-embedding-004"),
|
|
211
|
+
output_dimensionality=1536,
|
|
212
|
+
)
|
|
213
|
+
elif emb_provider == "bedrock":
|
|
214
|
+
embedder = BedrockEmbeddingAdapter(
|
|
215
|
+
model_id=os.environ.get(
|
|
216
|
+
"ADK_EMBEDDING_MODEL", "amazon.titan-embed-text-v2:0"
|
|
217
|
+
),
|
|
218
|
+
region=os.environ.get("AWS_REGION", "us-east-1"),
|
|
219
|
+
target_dim=1536,
|
|
220
|
+
)
|
|
221
|
+
elif emb_provider == "openai":
|
|
222
|
+
embedder = OpenAICompatibleEmbeddingAdapter(
|
|
223
|
+
model=os.environ.get("ADK_EMBEDDING_MODEL", "text-embedding-3-small"),
|
|
224
|
+
base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
|
|
225
|
+
dimensions=1536,
|
|
226
|
+
)
|
|
227
|
+
elif emb_provider == "ollama":
|
|
228
|
+
embedder = OllamaEmbeddingAdapter(
|
|
229
|
+
model=os.environ.get("ADK_EMBEDDING_MODEL", "nomic-embed-text"),
|
|
230
|
+
base_url=os.environ.get("OLLAMA_BASE_URL", "http://127.0.0.1:11434"),
|
|
231
|
+
target_dim=1536,
|
|
232
|
+
)
|
|
233
|
+
elif emb_provider == "local_st":
|
|
234
|
+
embedder = LocalSentenceTransformerEmbeddingAdapter(
|
|
235
|
+
model_name=os.environ.get(
|
|
236
|
+
"ADK_EMBEDDING_MODEL", "BAAI/bge-small-en-v1.5"
|
|
237
|
+
),
|
|
238
|
+
target_dim=1536,
|
|
239
|
+
)
|
|
240
|
+
else:
|
|
241
|
+
embedder = DeterministicHashEmbeddingAdapter(dim=1536)
|
|
242
|
+
|
|
243
|
+
if llm_provider == "gemini":
|
|
244
|
+
extractor = GeminiOntologyExtractorAdapter(
|
|
245
|
+
model=os.environ.get("ADK_LLM_MODEL", "gemini-2.5-flash")
|
|
246
|
+
)
|
|
247
|
+
elif llm_provider == "bedrock":
|
|
248
|
+
extractor = BedrockOntologyExtractorAdapter(
|
|
249
|
+
model_id=os.environ.get(
|
|
250
|
+
"ADK_LLM_MODEL", "us.anthropic.claude-3-5-sonnet-20241022-v2:0"
|
|
251
|
+
),
|
|
252
|
+
region=os.environ.get("AWS_REGION", "us-east-1"),
|
|
253
|
+
)
|
|
254
|
+
elif llm_provider == "openai":
|
|
255
|
+
extractor = OpenAICompatibleOntologyExtractorAdapter(
|
|
256
|
+
model=os.environ.get("ADK_LLM_MODEL", "gpt-4o-mini"),
|
|
257
|
+
base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
|
|
258
|
+
)
|
|
259
|
+
elif llm_provider == "ollama":
|
|
260
|
+
extractor = OllamaOntologyExtractorAdapter(
|
|
261
|
+
model=os.environ.get("ADK_LLM_MODEL", "qwen2.5:7b"),
|
|
262
|
+
base_url=os.environ.get("OLLAMA_BASE_URL", "http://127.0.0.1:11434"),
|
|
263
|
+
)
|
|
264
|
+
else:
|
|
265
|
+
extractor = build_default_rule_extractor()
|
|
266
|
+
|
|
267
|
+
pg_dsn = os.environ.get(
|
|
268
|
+
"POSTGRES_DSN",
|
|
269
|
+
"postgresql://platform_admin:platform_secret@127.0.0.1:5433/adk_memory_platform",
|
|
270
|
+
)
|
|
271
|
+
neo4j_uri = os.environ.get("NEO4J_URI", "bolt://127.0.0.1:7687")
|
|
272
|
+
neo4j_user = os.environ.get("NEO4J_USER", "neo4j")
|
|
273
|
+
neo4j_password = os.environ.get("NEO4J_PASSWORD", "platform_secret")
|
|
274
|
+
redis_url = os.environ.get("REDIS_URL", "redis://127.0.0.1:6379/0")
|
|
275
|
+
|
|
276
|
+
has_per_port_override = any(
|
|
277
|
+
k in os.environ
|
|
278
|
+
for k in (
|
|
279
|
+
"ADK_REGISTRY_BACKEND",
|
|
280
|
+
"ADK_SEED_BACKEND",
|
|
281
|
+
"ADK_GRAPH_BACKEND",
|
|
282
|
+
"ADK_PLAYBOOK_BACKEND",
|
|
283
|
+
)
|
|
284
|
+
)
|
|
285
|
+
|
|
286
|
+
if has_per_port_override:
|
|
287
|
+
mem_fallback = InMemoryUnifiedAdapter()
|
|
288
|
+
reg_type = os.environ.get("ADK_REGISTRY_BACKEND", "postgres").lower()
|
|
289
|
+
seed_type = os.environ.get("ADK_SEED_BACKEND", "postgres").lower()
|
|
290
|
+
graph_type = os.environ.get("ADK_GRAPH_BACKEND", "neo4j").lower()
|
|
291
|
+
pb_type = os.environ.get("ADK_PLAYBOOK_BACKEND", "postgres").lower()
|
|
292
|
+
|
|
293
|
+
registry_adapter = (
|
|
294
|
+
PostgresPgVectorAdapter(dsn=os.environ.get("POSTGRES_REGISTRY_DSN", pg_dsn))
|
|
295
|
+
if reg_type == "postgres"
|
|
296
|
+
else RedisRegistryAdapter(redis_url=os.environ.get("REDIS_REGISTRY_URL", redis_url))
|
|
297
|
+
if reg_type == "redis"
|
|
298
|
+
else mem_fallback
|
|
299
|
+
)
|
|
300
|
+
seed_adapter = (
|
|
301
|
+
PostgresPgVectorAdapter(dsn=os.environ.get("POSTGRES_SEED_DSN", pg_dsn))
|
|
302
|
+
if seed_type == "postgres"
|
|
303
|
+
else RedisEpisodicAndSeedAdapter(redis_url=os.environ.get("REDIS_SEED_URL", redis_url))
|
|
304
|
+
if seed_type == "redis"
|
|
305
|
+
else mem_fallback
|
|
306
|
+
)
|
|
307
|
+
graph_adapter = (
|
|
308
|
+
Neo4jGraphAdapter(uri=neo4j_uri, auth=(neo4j_user, neo4j_password))
|
|
309
|
+
if graph_type == "neo4j"
|
|
310
|
+
else PostgresGraphAdapter(dsn=os.environ.get("POSTGRES_GRAPH_DSN", pg_dsn))
|
|
311
|
+
if graph_type == "postgres"
|
|
312
|
+
else RedisGraphAdapter(redis_url=os.environ.get("REDIS_GRAPH_URL", redis_url))
|
|
313
|
+
if graph_type == "redis"
|
|
314
|
+
else mem_fallback
|
|
315
|
+
)
|
|
316
|
+
playbook_adapter = (
|
|
317
|
+
PostgresPlaybookAdapter(dsn=os.environ.get("POSTGRES_PLAYBOOK_DSN", pg_dsn))
|
|
318
|
+
if pb_type == "postgres"
|
|
319
|
+
else RedisPlaybookAndWorkingAdapter(redis_url=os.environ.get("REDIS_PLAYBOOK_URL", redis_url))
|
|
320
|
+
if pb_type == "redis"
|
|
321
|
+
else mem_fallback
|
|
322
|
+
)
|
|
323
|
+
service = CompositeMemoryService(
|
|
324
|
+
registry_adapter=registry_adapter,
|
|
325
|
+
seed_store_adapter=seed_adapter,
|
|
326
|
+
graph_adapter=graph_adapter,
|
|
327
|
+
embedding_adapter=embedder,
|
|
328
|
+
extractor_adapter=extractor,
|
|
329
|
+
playbook_adapter=playbook_adapter,
|
|
330
|
+
sync_outbox_immediately=True,
|
|
331
|
+
)
|
|
332
|
+
registrar = PlatformOntologyRegistrar(registry_adapter)
|
|
333
|
+
elif backend == "postgres_only":
|
|
334
|
+
service = CompositeMemoryService.from_postgres_stack(
|
|
335
|
+
dsn=pg_dsn, embedding_adapter=embedder, extractor_adapter=extractor
|
|
336
|
+
)
|
|
337
|
+
registrar = PlatformOntologyRegistrar(service.registry)
|
|
338
|
+
elif backend == "redis_only":
|
|
339
|
+
service = CompositeMemoryService.from_redis_stack(
|
|
340
|
+
redis_url=redis_url, embedding_adapter=embedder, extractor_adapter=extractor
|
|
341
|
+
)
|
|
342
|
+
registrar = PlatformOntologyRegistrar(service.registry)
|
|
343
|
+
elif backend == "docker":
|
|
344
|
+
pg_adapter = PostgresPgVectorAdapter(dsn=pg_dsn, min_pool_size=2, max_pool_size=15)
|
|
345
|
+
neo4j_adapter = Neo4jGraphAdapter(
|
|
346
|
+
uri=neo4j_uri, auth=(neo4j_user, neo4j_password)
|
|
347
|
+
)
|
|
348
|
+
playbook_adapter = RedisPlaybookAndWorkingAdapter(redis_url=redis_url)
|
|
349
|
+
service = CompositeMemoryService(
|
|
350
|
+
registry_adapter=pg_adapter,
|
|
351
|
+
seed_store_adapter=pg_adapter,
|
|
352
|
+
graph_adapter=neo4j_adapter,
|
|
353
|
+
embedding_adapter=embedder,
|
|
354
|
+
extractor_adapter=extractor,
|
|
355
|
+
playbook_adapter=playbook_adapter,
|
|
356
|
+
sync_outbox_immediately=True,
|
|
357
|
+
)
|
|
358
|
+
registrar = PlatformOntologyRegistrar(pg_adapter)
|
|
359
|
+
else:
|
|
360
|
+
mem = InMemoryUnifiedAdapter()
|
|
361
|
+
service = CompositeMemoryService(
|
|
362
|
+
registry_adapter=mem,
|
|
363
|
+
seed_store_adapter=mem,
|
|
364
|
+
graph_adapter=mem,
|
|
365
|
+
embedding_adapter=embedder,
|
|
366
|
+
extractor_adapter=extractor,
|
|
367
|
+
playbook_adapter=mem,
|
|
368
|
+
sync_outbox_immediately=True,
|
|
369
|
+
)
|
|
370
|
+
registrar = PlatformOntologyRegistrar(mem)
|
|
371
|
+
|
|
372
|
+
# Pre-load standard sample Domain Packs if present
|
|
373
|
+
repo_root = Path(__file__).resolve().parents[3]
|
|
374
|
+
packs_dir = repo_root / "examples" / "domain_packs"
|
|
375
|
+
if packs_dir.exists():
|
|
376
|
+
for json_file in packs_dir.glob("*.json"):
|
|
377
|
+
pack = DomainPackLoader.from_json_file(json_file)
|
|
378
|
+
registrar.register_domain_pack(pack)
|
|
379
|
+
|
|
380
|
+
return service, registrar
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
service, registrar = build_platform_service_from_env()
|
|
384
|
+
app = create_memory_platform_app(service, registrar)
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from typing import Any
|
|
4
|
+
|
|
5
|
+
from ..governance import PlatformOntologyRegistrar
|
|
6
|
+
from ..models import AppMemoryManifest, GovernanceTier, ReasoningTraceStep
|
|
7
|
+
from ..service import CompositeMemoryService, Event, types
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class MemoryMcpServerTools:
|
|
11
|
+
"""
|
|
12
|
+
Exposes governed Context Graph & Memory operations as MCP-compatible tools
|
|
13
|
+
that can be mounted into a FastMCP server or passed directly into Google ADK's `McpToolset` / `FunctionTool`.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
def __init__(
|
|
17
|
+
self,
|
|
18
|
+
service: CompositeMemoryService,
|
|
19
|
+
registrar: PlatformOntologyRegistrar | None = None,
|
|
20
|
+
):
|
|
21
|
+
self.service = service
|
|
22
|
+
self.registrar = registrar or PlatformOntologyRegistrar(service.registry)
|
|
23
|
+
|
|
24
|
+
async def recall_context(
|
|
25
|
+
self,
|
|
26
|
+
app_name: str,
|
|
27
|
+
user_id: str,
|
|
28
|
+
query: str,
|
|
29
|
+
as_of_timestamp: str | None = None,
|
|
30
|
+
max_hops: int = 2,
|
|
31
|
+
) -> dict[str, Any]:
|
|
32
|
+
"""
|
|
33
|
+
Runs hybrid RRF seed search + multi-hop bi-temporal graph expansion and returns a token-budgeted
|
|
34
|
+
subgraph slice + verbatim episodic memories. Supports point-in-time historical queries via `as_of_timestamp`.
|
|
35
|
+
"""
|
|
36
|
+
resp = await self.service.search_memory(
|
|
37
|
+
app_name=app_name,
|
|
38
|
+
user_id=user_id,
|
|
39
|
+
query=query,
|
|
40
|
+
as_of_iso=as_of_timestamp,
|
|
41
|
+
max_hops=max_hops,
|
|
42
|
+
)
|
|
43
|
+
blocks = []
|
|
44
|
+
for m in resp.memories:
|
|
45
|
+
if getattr(m, "content", None) and getattr(m.content, "parts", None):
|
|
46
|
+
text = "\n".join(p.text for p in m.content.parts if getattr(p, "text", None))
|
|
47
|
+
blocks.append({"author": m.author, "timestamp": m.timestamp, "text": text})
|
|
48
|
+
return {
|
|
49
|
+
"query": query,
|
|
50
|
+
"as_of": as_of_timestamp,
|
|
51
|
+
"max_hops": max_hops,
|
|
52
|
+
"memories": blocks,
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
async def commit_episode(
|
|
56
|
+
self,
|
|
57
|
+
app_name: str,
|
|
58
|
+
user_id: str,
|
|
59
|
+
raw_payload: str,
|
|
60
|
+
author: str = "agent",
|
|
61
|
+
session_id: str = "mcp_session",
|
|
62
|
+
) -> dict[str, Any]:
|
|
63
|
+
"""
|
|
64
|
+
Triggers PII scrubbing, episodic vector indexing, TBox-constrained extraction,
|
|
65
|
+
two-bucket validation, and bi-temporal edge updates.
|
|
66
|
+
"""
|
|
67
|
+
ev = Event(
|
|
68
|
+
author=author,
|
|
69
|
+
content=types.Content(role="user", parts=[types.Part.from_text(text=raw_payload)]),
|
|
70
|
+
)
|
|
71
|
+
await self.service.add_events_to_memory(
|
|
72
|
+
app_name=app_name,
|
|
73
|
+
user_id=user_id,
|
|
74
|
+
events=[ev],
|
|
75
|
+
session_id=session_id,
|
|
76
|
+
)
|
|
77
|
+
return {"status": "committed", "app_name": app_name, "session_id": session_id}
|
|
78
|
+
|
|
79
|
+
async def record_decision_trace(
|
|
80
|
+
self,
|
|
81
|
+
app_name: str,
|
|
82
|
+
user_id: str,
|
|
83
|
+
run_id: str,
|
|
84
|
+
session_id: str,
|
|
85
|
+
steps: list[dict[str, Any]],
|
|
86
|
+
) -> dict[str, Any]:
|
|
87
|
+
"""Writes an agent's tool-execution trace to the Tier 3 Procedural Reasoning subgraph."""
|
|
88
|
+
parsed_steps = [ReasoningTraceStep.model_validate(s) for s in steps]
|
|
89
|
+
await self.service.record_decision_trace(
|
|
90
|
+
app_name=app_name,
|
|
91
|
+
user_id=user_id,
|
|
92
|
+
run_id=run_id,
|
|
93
|
+
session_id=session_id,
|
|
94
|
+
steps=parsed_steps,
|
|
95
|
+
)
|
|
96
|
+
return {"status": "recorded", "run_id": run_id, "step_count": len(parsed_steps)}
|
|
97
|
+
|
|
98
|
+
async def register_app_manifest(
|
|
99
|
+
self,
|
|
100
|
+
tenant_id: str,
|
|
101
|
+
app_name: str,
|
|
102
|
+
governance_tier: str = "DOMAIN_SHARED",
|
|
103
|
+
subscribed_domain_packs: list[str] | None = None,
|
|
104
|
+
) -> dict[str, Any]:
|
|
105
|
+
"""Registers an ADK agent app's Governance Tier and Domain Pack subscriptions via MCP."""
|
|
106
|
+
manifest = AppMemoryManifest(
|
|
107
|
+
tenant_id=tenant_id,
|
|
108
|
+
app_name=app_name,
|
|
109
|
+
governance_tier=GovernanceTier(governance_tier),
|
|
110
|
+
subscribed_domain_packs=subscribed_domain_packs or [],
|
|
111
|
+
)
|
|
112
|
+
tbox = await self.registrar.register_adk_app(manifest)
|
|
113
|
+
return {
|
|
114
|
+
"status": "registered",
|
|
115
|
+
"tenant_id": tenant_id,
|
|
116
|
+
"app_name": app_name,
|
|
117
|
+
"governance_tier": governance_tier,
|
|
118
|
+
"compiled_classes": list(tbox.classes.keys()),
|
|
119
|
+
"compiled_predicates": list(tbox.relations.keys()),
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
async def purge_user_lineage(
|
|
123
|
+
self,
|
|
124
|
+
app_name: str,
|
|
125
|
+
user_id: str,
|
|
126
|
+
) -> dict[str, Any]:
|
|
127
|
+
"""Executes a cascading GDPR Right-to-be-Forgotten purge across Episodic and Graph tiers."""
|
|
128
|
+
purged_ids = await self.service.purge_user_lineage(
|
|
129
|
+
app_name=app_name, user_id=user_id
|
|
130
|
+
)
|
|
131
|
+
return {
|
|
132
|
+
"status": "purged",
|
|
133
|
+
"app_name": app_name,
|
|
134
|
+
"user_id": user_id,
|
|
135
|
+
"purged_episode_ids": purged_ids,
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def create_mcp_server(
|
|
140
|
+
service: CompositeMemoryService,
|
|
141
|
+
registrar: PlatformOntologyRegistrar | None = None,
|
|
142
|
+
name: str = "adk-composite-memory",
|
|
143
|
+
) -> Any:
|
|
144
|
+
"""
|
|
145
|
+
Creates a standalone Model Context Protocol (MCP) Server using `MCPServer` (mcp 2.x)
|
|
146
|
+
or `FastMCP` (mcp 1.x), exposing the 5 governed Composite Memory tools over
|
|
147
|
+
stdio, SSE, or Streamable HTTP.
|
|
148
|
+
Can be consumed by Google ADK (`McpToolset`), Claude Desktop, Cursor, or any MCP client.
|
|
149
|
+
"""
|
|
150
|
+
try:
|
|
151
|
+
from mcp.server.mcpserver import MCPServer as _MCPServerClass
|
|
152
|
+
except ImportError:
|
|
153
|
+
from mcp.server.fastmcp import FastMCP as _MCPServerClass
|
|
154
|
+
|
|
155
|
+
mcp = _MCPServerClass(name)
|
|
156
|
+
tools = MemoryMcpServerTools(service=service, registrar=registrar)
|
|
157
|
+
|
|
158
|
+
mcp.tool(
|
|
159
|
+
name="recall_context",
|
|
160
|
+
description=(
|
|
161
|
+
"Hybrid RRF seed search + multi-hop bi-temporal ontology graph traversal + "
|
|
162
|
+
"episodic memory retrieval with point-in-time (`as_of_timestamp`) support."
|
|
163
|
+
),
|
|
164
|
+
)(tools.recall_context)
|
|
165
|
+
|
|
166
|
+
mcp.tool(
|
|
167
|
+
name="commit_episode",
|
|
168
|
+
description=(
|
|
169
|
+
"Ingest an agent/user interaction into Episodic Memory and extract TBox-validated "
|
|
170
|
+
"entities and bi-temporal facts into the Knowledge Graph."
|
|
171
|
+
),
|
|
172
|
+
)(tools.commit_episode)
|
|
173
|
+
|
|
174
|
+
mcp.tool(
|
|
175
|
+
name="record_decision_trace",
|
|
176
|
+
description=(
|
|
177
|
+
"Record Tier 3 Procedural Reasoning Traces (`AgentRun -> ToolCall -> Entity`) "
|
|
178
|
+
"for explainability and auditability."
|
|
179
|
+
),
|
|
180
|
+
)(tools.record_decision_trace)
|
|
181
|
+
|
|
182
|
+
mcp.tool(
|
|
183
|
+
name="register_app_manifest",
|
|
184
|
+
description=(
|
|
185
|
+
"Register an agent app's Governance Tier (`APP_PRIVATE`, `DOMAIN_SHARED`, `GLOBAL_CORE`) "
|
|
186
|
+
"and subscribed Domain Packs."
|
|
187
|
+
),
|
|
188
|
+
)(tools.register_app_manifest)
|
|
189
|
+
|
|
190
|
+
mcp.tool(
|
|
191
|
+
name="purge_user_lineage",
|
|
192
|
+
description=(
|
|
193
|
+
"Execute a cascading GDPR Right-to-be-Forgotten lineage deletion across "
|
|
194
|
+
"Episodic and Bi-Temporal Graph stores."
|
|
195
|
+
),
|
|
196
|
+
)(tools.purge_user_lineage)
|
|
197
|
+
|
|
198
|
+
return mcp
|