Hybrid Triple Storage Architecture

SmartMemory implements a hybrid triple storage architecture that combines three complementary storage systems to provide optimal performance, flexibility, and intelligence. This architecture enables sophisticated memory operations while maintaining high performance and scalability.

Architecture Overview

flowchart TD
    A["🧠 Memory Item"] --> B["📊 Storage Router"]
    
    B --> C["💾 Graph Database"]
    B --> D["🗂️ Vector Store"]
    B --> E["📋 Metadata Store"]
    
    subgraph "Graph Database Layer"
        C --> C1["🔗 Entity Relationships"]
        C --> C2["🌐 Knowledge Graph"]
        C --> C3["📈 Graph Analytics"]
        C --> C4["🔍 Path Finding"]
    end
    
    subgraph "Vector Store Layer"
        D --> D1["🎯 Semantic Embeddings"]
        D --> D2["🔍 Similarity Search"]
        D --> D3["📊 Vector Operations"]
        D --> D4["🧮 Clustering"]
    end
    
    subgraph "Metadata Store Layer"
        E --> E1["⏰ Temporal Information"]
        E --> E2["👤 User Context"]
        E --> E3["🏷️ Classification Tags"]
        E --> E4["📊 Quality Metrics"]
    end
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:3px
    style C fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
    style D fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style E fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px

Storage Components

🌐 Graph Database Layer

Primary Functions:

• Entity Storage: People, places, concepts, and objects
• Relationship Mapping: Semantic, temporal, and causal relationships
• Knowledge Graph: Structured representation of domain knowledge
• Path Analysis: Finding connections between distant entities

Shipped Backends:

• FalkorDBBackend (default): Redis-based graph database — also stores vectors (see below)
• SQLiteBackend: File-based graph backend for local/lite development

🎯 Vector Store Layer

Primary Functions:

• Semantic Embeddings: Dense vector representations
• Similarity Search: Finding semantically related memories
• Clustering: Grouping similar memories automatically
• Dimensionality Operations: Efficient storage and retrieval

Shipped Backends:

• falkordb (default, FalkorVectorBackend): vectors are stored inside FalkorDB using its native HNSW vector index — the same database that holds the knowledge graph. Embeddings are 768-dim with cosine similarity by default.
• usearch (UsearchVectorBackend, optional): lightweight local vector index, used when the usearch dependency is installed.

Because the graph and the vectors live in the same FalkorDB instance, "hybrid" does not require a second standalone vector service in the default deployment.

📋 Metadata Store Layer

Primary Functions:

• Temporal Data: Creation time, modification history
• User Context: User-specific information, permissions
• Classification: Memory types, quality scores
• System Metadata: Indexing information, statistics

Metadata is carried on each memory item and persisted alongside the graph. For file-based persistence, the shipped JSONFileBackend stores items and their metadata as JSON.

Query Processing

flowchart LR
    A["🔍 Query"] --> B["📊 Query Analyzer"]
    B --> C["🎯 Storage Selection"]
    
    C --> D["💾 Graph Query"]
    C --> E["🗂️ Vector Search"]
    C --> F["📋 Metadata Filter"]
    
    D --> G["🔄 Result Fusion"]
    E --> G
    F --> G
    
    G --> H["📤 Unified Response"]
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style G fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style H fill:#e8f5e8,stroke:#388e3c,stroke-width:2px

Benefits of Hybrid Architecture

Use Cases

🔍 Semantic Search

# search() fuses the vector and graph channels automatically
results = memory.search("machine learning algorithms", top_k=5)

🌐 Relationship Discovery

# Uses the graph database to find the shortest path between two items
path = memory.find_shortest_path(start_id="john", end_id="techcorp", max_hops=3)

# Or expand a single item's immediate neighborhood
neighbors = memory.get_neighbors("john", direction="both")

⏰ Temporal Queries

# Bi-temporal "transaction-time travel": see memory as it existed on a date
results = memory.search("Python programming", as_of_date="2024-01-31")

🎯 Multi-Hop Retrieval

# Chain retrieval across hops; results from one hop seed the next
results = memory.search(
    "Python programming",
    multi_hop=True,
    max_hops=3,
    budget_ms=1500,
)

Configuration

{
  "graph_db": {
    "backend_class": "FalkorDBBackend",
    "host": "localhost",
    "port": 9010,
    "graph_name": "smartmemory"
  },
  "vector": {
    "backend": "falkordb",
    "dimension": 768,
    "metric": "cosine",
    "host": "localhost",
    "port": 9010
  }
}

The graph backend is selected by the graph_db.backend_class key (default FalkorDBBackend; SQLiteBackend is the lite alternative). The vector backend is selected by the vector.backend key (default falkordb, which co-locates the vector index with the graph in the same FalkorDB instance).

This hybrid architecture enables SmartMemory to provide both the structural intelligence of graph databases and the semantic understanding of vector stores, while maintaining efficient metadata operations for optimal performance.