A storage interface defines the operations a service needs without tying its logic to a particular backend. A Session Service can validate requests and enforce business rules while delegating persistence to a configured implementation. Switching from PostgreSQL to Redis then need not change service logic or client code. section 4.3
In Python, SessionStorage uses an abstract base class to specify session and message operations. Its methods mirror the corresponding gRPC operations, including their parameters and return data. Each backend translates those calls into its own persistence operations. section 4.3.2
Listing 4.8 Abstract storage interface for session persistence
from abc import ABC, abstractmethod
from typing import List, Optional
from datetime import datetime
class SessionStorage(ABC):
@abstractmethod
def get_or_create_session(
self,
user_id: str,
session_id: Optional[str] = None
) -> Session:
"""Retrieve existing session or create new one."""
pass
@abstractmethod
def list_sessions(
self,
user_id: str
) -> List[Session]:
"""Retrieve all sessions for a given user."""
pass
@abstractmethod
def add_messages(
self,
session_id: str,
messages: List[Message]
) -> int:
"""Append messages to session. Returns count added."""
pass
@abstractmethod
def get_messages(
self,
session_id: str,
limit: Optional[int] = None,
offset: Optional[int] = None
) -> tuple[List[Message], int]: #A
"""Retrieve messages with pagination.
➥Returns messages and total count."""
pass
@abstractmethod
def delete_session(self, session_id: str) -> bool:
"""Remove session and all its messages. Returns success."""
passThe abstract interface defines the session operations and their Python signatures. section 4.3.2
The contract separates responsibilities:
- The service calls storage methods and works with returned session and message objects; it does not choose SQL queries or Redis commands. section 4.3 section 4.3.2
- A backend implements the methods using its own data model and APIs. An in-memory implementation can use a Python dictionary to test service logic without a database. section 4.3.2
- A new backend is added by implementing the contract rather than rewriting the service. Backend choice can change as workload needs change. section 4.3.2
PostgreSQL session storage
PostgresSessionStorage implements the abstract methods with psycopg2 and SQL. For get_or_create_session, it looks up a supplied session ID and returns the existing session if found; otherwise it creates one. An ON CONFLICT clause handles concurrent requests using the same session ID by updating the existing row rather than failing on a duplicate key. section 4.4.2
Listing 4.11 PostgreSQL storage implementation
import json
import uuid
from datetime import datetime
from typing import List, Optional, Tuple
import psycopg2 #A
from psycopg2.extras import RealDictCursor #A
class PostgresSessionStorage(SessionStorage):
def __init__(self, connection_string: str): #B
self.connection_string =
➥connection_string #B
self.conn = psycopg2.connect( #B
connection_string, #B
cursor_factory=RealDictCursor #C
)
def get_or_create_session(
self,
user_id: str,
session_id: Optional[str] = None
) -> Session:
cursor = self.conn.cursor() #D
if session_id: #E
cursor.execute(
"SELECT * FROM sessions
➥WHERE session_id = %s", #F
(session_id,)
)
row = cursor.fetchone()
if row: #E
return self._row_to_session(row)
new_session_id = session_id
➥or str(uuid.uuid4()) #G
now = datetime.utcnow()
cursor.execute(
"""INSERT INTO sessions (session_id, user_id, created_at,
updated_at)
VALUES (%s, %s, %s, %s)
ON CONFLICT (session_id)
DO UPDATE SET updated_at = EXCLUDED.updated_at
RETURNING *""", #H
(new_session_id, user_id, now, now)
)
self.conn.commit() #I
return self._row_to_session(cursor.fetchone())The implementation connects through psycopg2 and begins translating the session contract into SQL. section 4.4.2
The contract can grow with the service. Memory methods save or update a value, retrieve one key or a user's memories, delete a key, and clear all memories for a user. An optional session ID supports session-scoped access; clearing user memory supports requests to be forgotten. PostgreSQL and Redis can implement these operations with different data structures while preserving the application-facing calls. section 4.6.3
Listing 4.20 Memory methods for SessionStorage interface
class SessionStorage(ABC):
# ... existing methods from Listing 4.8: get_or_create_session,
# add_messages, get_messages, delete_session ...
@abstractmethod
def save_memory(
self,
user_id: str,
key: str,
value: Any,
session_id: Optional[str] = None #A
) -> bool:
"""Save a fact to memory.
If the key exists for this user (and session, if scoped),
the value is updated. Returns True if successful.
"""
pass
@abstractmethod
def get_memory(
self,
user_id: str,
key: Optional[str] = None,
session_id: Optional[str] = None #B
) -> Dict[str, Any]:
"""Retrieve memories for a user.
If key is provided, returns {key: entry} or empty dict.
If session_id is provided, filters to that session's memories.
"""
pass
@abstractmethod
def delete_memory(
self,
user_id: str,
key: str,
session_id: Optional[str] = None
) -> bool:
"""Remove a fact from memory. Returns True if key existed."""
pass
@abstractmethod
def clear_user_memory(
self,
user_id: str
) -> int:
"""Remove all memories for a user.
➥Returns count deleted.""" #C
pass
The memory extension shows user identifiers, keys, values, and optional session scope in the abstract methods. section 4.6.3
Vector storage contract
A vector store needs both ingestion and search operations. Its write interface inserts chunks with embeddings and deletes by document or index, returning counts for verification. Its search interface accepts a query embedding and optional filters and returns search results. Because deletion is destructive, a production implementation should check the caller's identity against the index owner. section 5.4.1
Listing 5.16 VectorStore abstract base class: write operations
class VectorStore(ABC):
@abstractmethod
def insert(
self,
index_name: str,
document_id: str,
chunks: List[Chunk],
embeddings: List[List[float]],
metadata: Dict[str, str]
) -> int: #A
"""Insert chunks with embeddings. Returns count inserted."""
pass
@abstractmethod
def delete_by_document(
self, index_name: str, document_id: str
) -> int: #B
"""Delete all chunks for a document. Returns count deleted."""
pass
@abstractmethod
def delete_index
➥(self, index_name: str) -> int: #C
"""Delete all data for an index. Returns count deleted."""
passThe write signatures show how index and document identifiers scope insertion and deletion. section 5.4.1
Listing 5.17 VectorStore abstract base class: search operation and result model
@dataclass
class SearchResult:
chunk_id: str
document_id: str
text: str
score: float #A
metadata: Dict[str, str]
class VectorStore(ABC):
# ... write operations from Listing 5.16 ...
@abstractmethod
def search(
self,
index_name: str,
query_embedding: List[float],
top_k: int = 5,
metadata_filters: Optional[Dict[str, str]] = None,
score_threshold: Optional[float] = None
) -> List[SearchResult]: #B
"""Find chunks most similar to the query embedding."""
passThe search signature and result model define the read side of the vector store contract. section 5.4.1
