0
# Memory and Vector Stores
1
2
Vector database integrations for semantic memory, embeddings storage, and retrieval-augmented generation. Supports popular vector stores including Chroma, Pinecone, Qdrant, Redis, Azure Cognitive Search, and many others.
3
4
## Capabilities
5
6
### Memory Store Base Interface
7
8
Common interface for all vector store implementations.
9
10
```python { .api }
11
class MemoryStore:
12
"""
13
Base interface for vector memory stores.
14
"""
15
16
async def create_collection(
17
self,
18
collection_name: str,
19
**kwargs
20
) -> None:
21
"""
22
Create a new collection in the memory store.
23
24
Parameters:
25
- collection_name: Name of the collection to create
26
- **kwargs: Store-specific configuration options
27
"""
28
29
async def get_collections(self) -> list[str]:
30
"""
31
Get all collection names in the memory store.
32
33
Returns:
34
List of collection names
35
"""
36
37
async def delete_collection(self, collection_name: str) -> None:
38
"""
39
Delete a collection from the memory store.
40
41
Parameters:
42
- collection_name: Name of the collection to delete
43
"""
44
45
async def does_collection_exist(self, collection_name: str) -> bool:
46
"""
47
Check if a collection exists.
48
49
Parameters:
50
- collection_name: Name of the collection to check
51
52
Returns:
53
True if collection exists, False otherwise
54
"""
55
56
async def upsert(
57
self,
58
collection_name: str,
59
record: MemoryRecord,
60
**kwargs
61
) -> str:
62
"""
63
Insert or update a memory record.
64
65
Parameters:
66
- collection_name: Target collection name
67
- record: Memory record to upsert
68
- **kwargs: Store-specific options
69
70
Returns:
71
ID of the upserted record
72
"""
73
74
async def upsert_batch(
75
self,
76
collection_name: str,
77
records: list[MemoryRecord],
78
**kwargs
79
) -> list[str]:
80
"""
81
Insert or update multiple memory records.
82
83
Parameters:
84
- collection_name: Target collection name
85
- records: List of memory records to upsert
86
- **kwargs: Store-specific options
87
88
Returns:
89
List of IDs for the upserted records
90
"""
91
92
async def get(
93
self,
94
collection_name: str,
95
key: str,
96
with_embedding: bool = False,
97
**kwargs
98
) -> MemoryRecord | None:
99
"""
100
Get a memory record by key.
101
102
Parameters:
103
- collection_name: Collection to search in
104
- key: Record key/ID
105
- with_embedding: Whether to include embedding vector
106
- **kwargs: Store-specific options
107
108
Returns:
109
MemoryRecord if found, None otherwise
110
"""
111
112
async def get_batch(
113
self,
114
collection_name: str,
115
keys: list[str],
116
with_embeddings: bool = False,
117
**kwargs
118
) -> list[MemoryRecord]:
119
"""
120
Get multiple memory records by keys.
121
122
Parameters:
123
- collection_name: Collection to search in
124
- keys: List of record keys/IDs
125
- with_embeddings: Whether to include embedding vectors
126
- **kwargs: Store-specific options
127
128
Returns:
129
List of found MemoryRecord objects
130
"""
131
132
async def remove(self, collection_name: str, key: str, **kwargs) -> None:
133
"""
134
Remove a memory record by key.
135
136
Parameters:
137
- collection_name: Collection containing the record
138
- key: Record key/ID to remove
139
- **kwargs: Store-specific options
140
"""
141
142
async def remove_batch(
143
self,
144
collection_name: str,
145
keys: list[str],
146
**kwargs
147
) -> None:
148
"""
149
Remove multiple memory records by keys.
150
151
Parameters:
152
- collection_name: Collection containing the records
153
- keys: List of record keys/IDs to remove
154
- **kwargs: Store-specific options
155
"""
156
157
async def get_nearest_matches(
158
self,
159
collection_name: str,
160
embedding: list[float],
161
limit: int,
162
min_relevance_score: float = 0.0,
163
with_embeddings: bool = False,
164
**kwargs
165
) -> list[tuple[MemoryRecord, float]]:
166
"""
167
Find the nearest matching records to a query embedding.
168
169
Parameters:
170
- collection_name: Collection to search in
171
- embedding: Query embedding vector
172
- limit: Maximum number of results to return
173
- min_relevance_score: Minimum relevance score threshold
174
- with_embeddings: Whether to include embedding vectors in results
175
- **kwargs: Store-specific options
176
177
Returns:
178
List of tuples containing (MemoryRecord, relevance_score)
179
"""
180
181
async def get_nearest_match(
182
self,
183
collection_name: str,
184
embedding: list[float],
185
min_relevance_score: float = 0.0,
186
with_embedding: bool = False,
187
**kwargs
188
) -> tuple[MemoryRecord, float] | None:
189
"""
190
Find the single nearest matching record to a query embedding.
191
192
Parameters:
193
- collection_name: Collection to search in
194
- embedding: Query embedding vector
195
- min_relevance_score: Minimum relevance score threshold
196
- with_embedding: Whether to include embedding vector in result
197
- **kwargs: Store-specific options
198
199
Returns:
200
Tuple of (MemoryRecord, relevance_score) if found, None otherwise
201
"""
202
203
class MemoryRecord:
204
"""
205
Represents a memory record in a vector store.
206
"""
207
208
def __init__(
209
self,
210
id: str,
211
text: str,
212
is_reference: bool = False,
213
external_source_name: str | None = None,
214
description: str | None = None,
215
additional_metadata: str | None = None,
216
embedding: list[float] | None = None,
217
key: str | None = None,
218
timestamp: datetime | None = None
219
):
220
"""
221
Initialize a memory record.
222
223
Parameters:
224
- id: Unique identifier for the record
225
- text: Text content of the memory
226
- is_reference: Whether this is a reference to external content
227
- external_source_name: Name of external source if reference
228
- description: Description of the memory content
229
- additional_metadata: Additional metadata as string
230
- embedding: Vector embedding for the text
231
- key: Alternative key for the record
232
- timestamp: Timestamp when record was created
233
"""
234
235
@property
236
def id(self) -> str:
237
"""Get the record ID."""
238
239
@property
240
def text(self) -> str:
241
"""Get the text content."""
242
243
@property
244
def embedding(self) -> list[float] | None:
245
"""Get the embedding vector."""
246
247
@property
248
def metadata(self) -> dict[str, Any]:
249
"""Get all metadata as a dictionary."""
250
```
251
252
### Vector Store Connectors
253
254
Specific implementations for popular vector databases.
255
256
```python { .api }
257
# Chroma Vector Store
258
from semantic_kernel.connectors.memory_stores.chroma import ChromaMemoryStore
259
260
class ChromaMemoryStore(MemoryStore):
261
"""Chroma vector database connector."""
262
263
def __init__(self, persist_directory: str | None = None):
264
"""
265
Initialize Chroma memory store.
266
267
Parameters:
268
- persist_directory: Directory to persist Chroma data
269
"""
270
271
# Pinecone Vector Store
272
from semantic_kernel.connectors.memory_stores.pinecone import PineconeMemoryStore
273
274
class PineconeMemoryStore(MemoryStore):
275
"""Pinecone vector database connector."""
276
277
def __init__(self, api_key: str, environment: str):
278
"""
279
Initialize Pinecone memory store.
280
281
Parameters:
282
- api_key: Pinecone API key
283
- environment: Pinecone environment
284
"""
285
286
# Qdrant Vector Store
287
from semantic_kernel.connectors.memory_stores.qdrant import QdrantMemoryStore
288
289
class QdrantMemoryStore(MemoryStore):
290
"""Qdrant vector database connector."""
291
292
def __init__(
293
self,
294
host: str = "localhost",
295
port: int = 6333,
296
api_key: str | None = None
297
):
298
"""
299
Initialize Qdrant memory store.
300
301
Parameters:
302
- host: Qdrant server host
303
- port: Qdrant server port
304
- api_key: API key for authentication
305
"""
306
307
# Redis Vector Store
308
from semantic_kernel.connectors.memory_stores.redis import RedisMemoryStore
309
310
class RedisMemoryStore(MemoryStore):
311
"""Redis vector database connector."""
312
313
def __init__(
314
self,
315
connection_string: str,
316
vector_size: int = 1536
317
):
318
"""
319
Initialize Redis memory store.
320
321
Parameters:
322
- connection_string: Redis connection string
323
- vector_size: Dimension of embedding vectors
324
"""
325
326
# Azure Cognitive Search
327
from semantic_kernel.connectors.memory_stores.azure_cognitive_search import AzureCognitiveSearchMemoryStore
328
329
class AzureCognitiveSearchMemoryStore(MemoryStore):
330
"""Azure Cognitive Search vector store connector."""
331
332
def __init__(
333
self,
334
search_endpoint: str,
335
admin_key: str,
336
vector_size: int = 1536
337
):
338
"""
339
Initialize Azure Cognitive Search memory store.
340
341
Parameters:
342
- search_endpoint: Azure Search service endpoint
343
- admin_key: Admin API key
344
- vector_size: Dimension of embedding vectors
345
"""
346
347
# Weaviate Vector Store
348
from semantic_kernel.connectors.memory_stores.weaviate import WeaviateMemoryStore
349
350
class WeaviateMemoryStore(MemoryStore):
351
"""Weaviate vector database connector."""
352
353
def __init__(
354
self,
355
url: str = "http://localhost:8080",
356
api_key: str | None = None,
357
use_embed: bool = True
358
):
359
"""
360
Initialize Weaviate memory store.
361
362
Parameters:
363
- url: Weaviate instance URL
364
- api_key: API key for authentication
365
- use_embed: Whether to use Weaviate's embedding service
366
"""
367
368
# Additional Vector Stores Available:
369
# - PostgreSQL with pgvector: PostgresMemoryStore
370
# - MongoDB Atlas: MongoDBAtlasMemoryStore
371
# - Milvus: MilvusMemoryStore
372
# - AstraDB: AstraDBMemoryStore
373
# - Azure Cosmos DB: AzureCosmosDBMemoryStore, AzureCosmosDBNoSQLMemoryStore
374
# - USearch: USearchMemoryStore
375
```
376
377
### Memory Integration with Kernel
378
379
Helper classes for integrating memory with kernel operations.
380
381
```python { .api }
382
class SemanticTextMemory:
383
"""
384
High-level interface for semantic text memory operations.
385
"""
386
387
def __init__(
388
self,
389
storage: MemoryStore,
390
embeddings_generator: EmbeddingGeneratorBase
391
):
392
"""
393
Initialize semantic text memory.
394
395
Parameters:
396
- storage: Vector store for memory persistence
397
- embeddings_generator: Service for generating embeddings
398
"""
399
400
async def save_information(
401
self,
402
collection: str,
403
text: str,
404
id: str,
405
description: str | None = None,
406
additional_metadata: str | None = None
407
) -> None:
408
"""
409
Save information to memory with automatic embedding generation.
410
411
Parameters:
412
- collection: Collection to save to
413
- text: Text content to save
414
- id: Unique identifier for the information
415
- description: Optional description
416
- additional_metadata: Optional additional metadata
417
"""
418
419
async def save_reference(
420
self,
421
collection: str,
422
text: str,
423
external_id: str,
424
external_source_name: str,
425
description: str | None = None,
426
additional_metadata: str | None = None
427
) -> None:
428
"""
429
Save a reference to external information.
430
431
Parameters:
432
- collection: Collection to save to
433
- text: Text content of the reference
434
- external_id: ID in the external system
435
- external_source_name: Name of the external source
436
- description: Optional description
437
- additional_metadata: Optional additional metadata
438
"""
439
440
async def get(
441
self,
442
collection: str,
443
key: str
444
) -> MemoryQueryResult | None:
445
"""
446
Get information from memory by key.
447
448
Parameters:
449
- collection: Collection to search in
450
- key: Key/ID of the information
451
452
Returns:
453
MemoryQueryResult if found, None otherwise
454
"""
455
456
async def search(
457
self,
458
collection: str,
459
query: str,
460
limit: int = 1,
461
min_relevance_score: float = 0.0
462
) -> list[MemoryQueryResult]:
463
"""
464
Search for information using natural language query.
465
466
Parameters:
467
- collection: Collection to search in
468
- query: Natural language search query
469
- limit: Maximum number of results
470
- min_relevance_score: Minimum relevance threshold
471
472
Returns:
473
List of MemoryQueryResult objects ordered by relevance
474
"""
475
476
class MemoryQueryResult:
477
"""
478
Result from a memory query operation.
479
"""
480
481
def __init__(
482
self,
483
metadata: MemoryRecordMetadata,
484
relevance: float,
485
embedding: list[float] | None = None
486
):
487
"""
488
Initialize memory query result.
489
490
Parameters:
491
- metadata: Metadata for the memory record
492
- relevance: Relevance score (0.0 to 1.0)
493
- embedding: Vector embedding (optional)
494
"""
495
496
@property
497
def metadata(self) -> MemoryRecordMetadata:
498
"""Get the memory record metadata."""
499
500
@property
501
def relevance(self) -> float:
502
"""Get the relevance score."""
503
504
@property
505
def embedding(self) -> list[float] | None:
506
"""Get the embedding vector."""
507
508
class MemoryRecordMetadata:
509
"""
510
Metadata for a memory record.
511
"""
512
513
def __init__(
514
self,
515
is_reference: bool,
516
id: str,
517
text: str,
518
description: str,
519
external_source_name: str | None = None,
520
additional_metadata: str | None = None
521
):
522
"""
523
Initialize memory record metadata.
524
525
Parameters:
526
- is_reference: Whether this is a reference to external content
527
- id: Unique identifier
528
- text: Text content
529
- description: Description of the content
530
- external_source_name: External source name if reference
531
- additional_metadata: Additional metadata string
532
"""
533
534
@property
535
def id(self) -> str:
536
"""Get the record ID."""
537
538
@property
539
def text(self) -> str:
540
"""Get the text content."""
541
542
@property
543
def description(self) -> str:
544
"""Get the description."""
545
546
@property
547
def is_reference(self) -> bool:
548
"""Check if this is a reference record."""
549
```
550
551
## Usage Examples
552
553
### Basic Memory Operations
554
555
```python
556
from semantic_kernel.connectors.memory_stores.chroma import ChromaMemoryStore
557
from semantic_kernel.connectors.ai.open_ai import OpenAITextEmbedding
558
from semantic_kernel.memory import SemanticTextMemory
559
560
# Setup vector store and embeddings
561
vector_store = ChromaMemoryStore(persist_directory="./chroma_db")
562
embedding_service = OpenAITextEmbedding(
563
ai_model_id="text-embedding-ada-002",
564
api_key="your-api-key"
565
)
566
567
# Create semantic memory
568
memory = SemanticTextMemory(
569
storage=vector_store,
570
embeddings_generator=embedding_service
571
)
572
573
# Save information
574
await memory.save_information(
575
collection="documents",
576
text="Semantic Kernel is an AI orchestration framework",
577
id="sk_intro",
578
description="Introduction to Semantic Kernel"
579
)
580
581
# Search for information
582
results = await memory.search(
583
collection="documents",
584
query="What is Semantic Kernel?",
585
limit=3,
586
min_relevance_score=0.7
587
)
588
589
for result in results:
590
print(f"Relevance: {result.relevance}")
591
print(f"Text: {result.metadata.text}")
592
```
593
594
### Integration with Kernel
595
596
```python
597
from semantic_kernel import Kernel
598
from semantic_kernel.functions import kernel_function
599
600
# Create kernel with memory
601
kernel = Kernel()
602
kernel.add_service(embedding_service)
603
604
# Add memory plugin
605
class MemoryPlugin:
606
def __init__(self, memory: SemanticTextMemory):
607
self._memory = memory
608
609
@kernel_function(description="Search memory for relevant information")
610
async def search_memory(self, query: str, collection: str = "documents") -> str:
611
results = await self._memory.search(collection, query, limit=3)
612
if results:
613
return results[0].metadata.text
614
return "No relevant information found."
615
616
@kernel_function(description="Save information to memory")
617
async def save_to_memory(
618
self,
619
text: str,
620
id: str,
621
collection: str = "documents"
622
) -> str:
623
await self._memory.save_information(collection, text, id)
624
return f"Saved information with ID: {id}"
625
626
# Add memory plugin to kernel
627
memory_plugin = MemoryPlugin(memory)
628
kernel.add_plugin(memory_plugin, plugin_name="memory")
629
630
# Use memory in functions
631
result = await kernel.invoke("memory", "search_memory", query="AI frameworks")
632
print(result.value)
633
```