Architecture Deep Dive

A guided tour through SmartMemory's architecture: how content flows through the ingestion pipeline, how the five memory types relate, how the Zettelkasten layer organises atomic knowledge, how clustering deduplicates entities, how MCP integration works, and how it all sits on the storage substrate. Aimed at readers evaluating whether SmartMemory fits their architecture, and at integrators who want a complete mental model before reaching for the API reference.

For the short version, see Introduction. For task-oriented usage see the Guides. For the API surface see SmartMemory.

📚 Repository: smartmemory-ai/smart-memory
🐛 Issues: Report bugs or request features
📖 Documentation: View online docs

🚀 What is SmartMemory?

SmartMemory is a next-generation memory system that goes far beyond simple storage and retrieval. It's designed specifically for AI agents and intelligent applications that need sophisticated memory capabilities with human-like cognitive processing and complete user isolation.

🌟 Key Features

• 🧠 Cognitive Memory Types: Pending, semantic, episodic, and procedural memory systems
• 🔄 Automatic Evolution: Memories improve and consolidate over time
• 🎯 Entity Extraction: LLM, SpaCy, and GLiNER extractors with automatic fallback
• 🔗 Entity Clustering: deduplication (SemHash + KMeans + LLM)
• 🌐 Knowledge Grounding: Automatic Wikipedia linking for entity provenance
• 🔍 Assertion Challenging: Detect contradictions between new and existing facts
• 🔍 Semantic Search: Vector embeddings + graph traversal + text fallbacks
• ⏱️ Temporal Versioning: Bi-temporal tracking with time-travel queries
• 🌐 Framework Integration: Works with LangChain, CrewAI, AutoGen, and more

🔄 Ingestion Pipeline

When you call memory.ingest(), content flows through an 11-stage pipeline:

flowchart LR
    A["📥 Input"] --> B["🏷️ Classification"]
    B --> C["🔍 Extraction"]
    C --> D["💾 Storage"]
    D --> E["🔗 Linking"]
    E --> F["📊 Vector"]
    F --> G["✨ Enrichment"]
    G --> H["🌐 Grounding"]
    H --> I["🔄 Evolution"]
    I --> J["🧬 Clustering"]
    J --> K["📜 Versioning"]
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style C fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
    style J fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style K fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px

🧠 Memory Type Distribution

SmartMemory organizes information into five distinct cognitive memory types, each optimized for different kinds of knowledge and usage patterns, mimicking human cognitive architecture.

flowchart TD
    A["🧠 Classified Memory"] --> B{"Memory Type?"}
    
    B -->|Facts & Knowledge| C["🔍 Semantic Memory"]
    B -->|Personal Events| D["📚 Episodic Memory"]
    B -->|Skills & Procedures| E["⚙️ Procedural Memory"]
    B -->|Active Context| F["💭 Pending Memory"]
    B -->|Atomic Knowledge| G["🗂️ Zettelkasten Memory"]
    
    C --> H["🔗 Relationship Mapping"]
    D --> H
    E --> H
    G --> H
    F --> H
    
    H --> I["💾 Storage Layer"]
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    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

🧬 Memory Evolution & Intelligence

Memory improves itself in the background while you continue chatting. Memories consolidate, prune, and enhance relationships as well as create new memories to self-improve. The system also goes out to the web to find new information and ground existing memories in facts.

flowchart TB
    subgraph "Memory Lifecycle"
        A["📥 New Memory"] --> B["🔍 Initial Processing"]
        B --> C["💾 Storage"]
        C --> D["🔄 Background Evolution"]
        D --> E{"Evolution Type?"}
        
        E -->|Consolidate| F["🧬 Memory Consolidation"]
        E -->|Prune| G["✂️ Strategic Pruning"]
        E -->|Link| H["🔗 Relationship Enhancement"]
        E -->|Organize| I["📋 Hierarchical Organization"]
        
        F --> J["📊 Quality Assessment"]
        G --> J
        H --> J
        I --> J
        
        J --> K{"Quality Score?"}
        K -->|High| L["⭐ Promote Memory"]
        K -->|Medium| M["🔄 Continue Evolution"]
        K -->|Low| N["🗄️ Archive/Remove"]
        
        L --> O["🎯 Enhanced Retrieval"]
        M --> D
        N --> P["📋 Archive Storage"]
    end
    
    subgraph "Intelligence Features"
        Q["🤖 Agent Query"] --> R["🔍 Smart Search"]
        R --> S["🎯 Context Building"]
        S --> T["📊 Relevance Scoring"]
        T --> U["📤 Intelligent Response"]
        
        O --> R
        C --> R
    end
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style J fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style O fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
    style U fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px

🗂️ Zettelkasten Memory System

SmartMemory includes a sophisticated Zettelkasten system for atomic knowledge management, automatically creating interconnected knowledge networks that evolve and strengthen over time.

Zettelkasten Creation

flowchart LR
    A["📝 Knowledge Input"] --> B["🔍 Atomic Concept Extraction"]
    B --> C["📋 Zettel Creation"]
    C --> D["🏷️ Auto-Tagging"]
    D --> E["🔗 Link Discovery"]
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style E fill:#e8f5e8,stroke:#388e3c,stroke-width:2px

Knowledge Graph Evolution

flowchart LR
    F["🕸️ Concept Network"] --> G["📊 Hierarchical Clusters"]
    G --> H["🎯 Topic Modeling"]
    H --> I["🔍 Semantic Relationships"]
    I --> J["🧬 Link Strengthening"]
    J --> K["📈 Concept Merging"]
    K --> L["✂️ Redundancy Pruning"]
    L --> M["🌱 New Connection Discovery"]
    
    style F fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
    style M fill:#fff3e0,stroke:#f57c00,stroke-width:2px

Intelligent Retrieval

flowchart LR
    N["🔍 Query Processing"] --> O["🎯 Relevance Scoring"]
    O --> P["📊 Context Assembly"]
    P --> Q["📤 Knowledge Response"]
    
    style N fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Q fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px

🧬 Entity Clustering & Deduplication

SmartMemory provides multi-level entity resolution:

flowchart LR
    A["🔤 Entities"] --> B["#️⃣ SemHash"]
    B --> C["📊 KMeans"]
    C --> D["🤖 LLM Clustering"]
    D --> E["🔗 Merge Nodes"]
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style B 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

Runs automatically after each ingest() call, or manually via memory.run_clustering().

🔍 Advanced Search & Retrieval

Multi-dimensional search capabilities that go beyond simple keyword matching, using semantic understanding, graph traversal, and temporal patterns to find the most relevant memories.

flowchart TD
    subgraph "Search Input"
        A["🔤 User Query"] --> B["🔍 Query Analysis"]
        B --> C["🎯 Intent Detection"]
        C --> D["📊 Context Extraction"]
    end
    
    subgraph "Search Strategies"
        D --> E["🔍 Semantic Search"]
        D --> F["🕸️ Graph Traversal"]
        D --> G["⏰ Temporal Search"]
        D --> H["🔗 Hybrid Search"]
        D --> I["📊 Similarity Search"]
    end
    
    subgraph "Memory Sources"
        E --> J["🔍 Semantic Memory"]
        F --> K["📚 Episodic Memory"]
        G --> L["⚙️ Procedural Memory"]
        H --> M["💭 Pending Memory"]
        I --> N["🗂️ Zettelkasten Memory"]
    end
    
    subgraph "Result Processing"
        J --> O["📊 Relevance Scoring"]
        K --> O
        L --> O
        M --> O
        N --> O
        
        O --> P["🔗 Relationship Mapping"]
        P --> Q["📈 Ranking Algorithm"]
        Q --> R["📤 Contextual Results"]
    end
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style E fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
    style O fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style R fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px

🔌 MCP Server Integration

Seamless integration with AI agents through the Model Context Protocol, providing standardized tools and interfaces for memory operations within agentic workflows.

flowchart TD
    subgraph "AI Agent Layer"
        A["🤖 AI Agent"] --> B["📡 MCP Client"]
        B --> C["🔌 Protocol Handler"]
    end
    
    subgraph "SmartMemory MCP Server"
        C --> D["📥 Request Router"]
        D --> E["🛠️ Tool Interface"]
        
        E --> F["💾 Memory Operations"]
        E --> G["🔍 Search Operations"]
        E --> H["🔗 Relationship Operations"]
        E --> I["📊 Analytics Operations"]
    end
    
    subgraph "Core Memory Engine"
        F --> J["🧠 Memory Manager"]
        G --> K["🔍 Search Engine"]
        H --> L["🕸️ Graph Engine"]
        I --> M["📈 Analytics Engine"]
    end
    
    subgraph "Storage Layer"
        J --> N["📊 Graph Database"]
        K --> O["🗂️ Vector Store"]
        L --> P["📋 Metadata Store"]
        M --> Q["📊 Analytics Store"]
    end
    
    subgraph "Background Processing"
        N --> R["🔄 Evolution Engine"]
        O --> R
        P --> R
        Q --> R
        
        R --> S["🧬 Memory Consolidation"]
        R --> T["✂️ Strategic Pruning"]
        R --> U["🔗 Link Enhancement"]
    end
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style E fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
    style J fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style R fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px

💾 Storage Architecture

SmartMemory uses a unified FalkorDB backend for both graph and vector storage:

flowchart TD
    subgraph "SmartMemory API"
        A["🤖 SmartMemory"] --> B["📊 SmartGraph"]
        A --> C["🗂️ VectorStore"]
    end
    
    subgraph "FalkorDB (Unified Backend)"
        B --> D["🕸️ Graph Storage"]
        C --> E["📊 HNSW Vector Index"]
        
        D --> F["Memory Nodes"]
        D --> G["Entity Nodes"]
        D --> H["Wikipedia Nodes"]
        D --> I["Version Nodes"]
        D --> J["Edges (CONTAINS, GROUNDED_IN, HAS_VERSION)"]
        
        E --> K["vecf32 embeddings"]
        E --> L["Cosine similarity"]
    end
    
    subgraph "Redis Cache"
        M["⚡ Embeddings"]
        N["⚡ Search Results"]
        O["⚡ Entity Extraction"]
    end
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style D fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
    style E fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style M fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px

Key Features:

• Dual-node pattern: Memory nodes + separate entity nodes for reuse
• Global Wikipedia nodes: Shared across users (is_global=True)
• HNSW vector index: Native FalkorDB vector search with configurable M, efConstruction
• Multi-tenant isolation: ScopeProvider filters all queries by tenant/user/workspace

🎯 Agentic Framework Integration

Seamless integration with major AI agent frameworks through specialized adapters, enabling SmartMemory to work natively within your existing agentic workflows and toolchains.

flowchart LR
    subgraph "AI Agent Frameworks"
        A["🦜 LangChain"]
        B["🦙 LlamaIndex"]
        C["🌾 Haystack"]
        D["🤖 AutoGen"]
        E["🚢 CrewAI"]
        F["🔧 Custom Agents"]
    end
    
    subgraph "SmartMemory Integration Layer"
        A --> G["🔌 LangChain Adapter"]
        B --> H["🔌 LlamaIndex Adapter"]
        C --> I["🔌 Haystack Adapter"]
        D --> J["🔌 AutoGen Adapter"]
        E --> K["🔌 CrewAI Adapter"]
        F --> L["🔌 Generic MCP Adapter"]
    end
    
    subgraph "Core SmartMemory"
        G --> M["🧠 Memory Engine"]
        H --> M
        I --> M
        J --> M
        K --> M
        L --> M
        
        M --> N["💾 Storage Layer"]
        M --> O["🔍 Search Engine"]
        M --> P["🧬 Evolution Engine"]
        M --> Q["📊 Analytics Engine"]
    end
    
    subgraph "Agent Capabilities"
        N --> R["💭 Memory Persistence"]
        O --> S["🔍 Intelligent Retrieval"]
        P --> T["🧬 Continuous Learning"]
        Q --> U["📈 Performance Insights"]
    end
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style G fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
    style M fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style R fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px

🎯 Key Differentiators

🌟 Key Features & Architecture Blocks

🧠 Cognitive Memory Types

Core Processing Capabilities:

• 🤖 Automatic Entity Extraction: Identify people, places, concepts, and relationships
• 🕸️ Intelligent Linking: Discover connections between memories automatically
• 📈 Semantic Enrichment: Enhance memories with contextual information
• 🎯 Similarity Analysis: Multi-dimensional similarity scoring and clustering
• 🔄 Evolution Algorithms: Continuous memory consolidation and optimization

⚡ High-Performance Architecture

🤖 Agent-First Design

Quick Start

from smartmemory import SmartMemory

# Initialize SmartMemory
memory = SmartMemory()

# Ingest memories (full 11-stage pipeline)
# classify → coreference → simplify → entity_ruler → llm_extract →
# ontology_constrain → store → link → enrich → ground → evolve
memory.ingest("I learned Python programming in 2020")
memory.ingest("Paris is the capital of France")
memory.ingest("John works at Google as an engineer")

# Search memories (vector + graph + text fallbacks)
results = memory.search("programming languages")
print(results)

# Get related memories via graph traversal
related = memory.get_neighbors(results[0].item_id)
print(related)

# Run clustering to deduplicate entities
stats = memory.run_clustering()
print(f"Merged {stats['merged_count']} duplicate entities")

Key Differentiators

🧠 SmartMemory: Most comprehensive system with 5 memory types, advanced evolution algorithms, hybrid storage, and enterprise-grade features

🔧 Zep: Lightweight vector-based system focused on simplicity and basic retrieval

☁️ Mem0: Cloud-native solution with good LLM integration but limited memory sophistication

Best Use Cases

• SmartMemory: Complex AI agents, enterprise applications, research systems, sophisticated conversational AI
• Zep: Simple chatbots, basic RAG applications, proof-of-concepts
• Mem0: Cloud-first applications, basic personalization, simple memory needs

Use Cases

• Conversational AI: Persistent memory for chatbots and assistants
• Learning Systems: Educational applications with knowledge tracking
• Knowledge Management: Enterprise knowledge bases with intelligent organization
• Research Tools: Academic and scientific knowledge organization
• Personal AI: Individual memory systems for personal assistants

Next Steps

1. Installation - Set up SmartMemory in your environment
2. Quick Start - Build your first memory-enabled application
3. Core Concepts - Understand the fundamental concepts
4. API Reference - Detailed API documentation

SmartMemory is designed for developers building intelligent applications that need sophisticated memory capabilities. Whether you're creating conversational AI, learning systems, or knowledge management tools, SmartMemory provides the foundation for intelligent memory processing.