Core Concepts

📚 Repository: smartmemory-ai/smart-memory
🐛 Issues: Report bugs or request features

Understanding SmartMemory's core concepts is essential for building effective memory-enabled applications. This guide covers the fundamental principles and components that make SmartMemory powerful.

Memory Architecture

SmartMemory implements a unified memory architecture that combines multiple memory types with intelligent processing capabilities. Unlike traditional storage systems, SmartMemory doesn't just store data—it understands, connects, and evolves your information.

SmartMemory's memory types fall into two cohorts: a knowledge layer (semantic, episodic, procedural, zettel) that stores what's true, and an expertise layer (decision, constraint, learned, opinion, reasoning, observation) that stores what to do — and what not to do. The expertise layer captures the choices an agent makes, the alternatives it rejects, the constraints it discovers, the lessons it learns the hard way. See Expertise vs Knowledge for the full distinction.

graph TD
    A["📝 Raw Input"] --> B["🔍 Content Analysis"]
    B --> C["🏷️ Type Classification"]
    
    C --> D{"Memory Type?"}
    D -->|Facts| E["🔍 Semantic Memory"]
    D -->|Events| F["📚 Episodic Memory"]
    D -->|Skills| G["⚙️ Procedural Memory"]
    D -->|Active| H["💭 Pending Memory"]
    
    E --> I["💾 Graph Database"]
    F --> I
    G --> I
    H --> I
    
    I --> J["🔗 Relationship Mapping"]
    I --> K["📊 Semantic Indexing"]
    I --> L["⏰ Temporal Ordering"]
    
    J --> M["🧬 Evolution Engine"]
    K --> M
    L --> M
    
    M --> N["🎯 Smart Retrieval"]
    M --> O["📈 Quality Enhancement"]
    M --> P["🔄 Continuous Learning"]
    
    N --> Q["📤 Contextual Results"]
    O --> Q
    P --> Q
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style I fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style M fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Q fill:#e8f5e8,stroke:#388e3c,stroke-width:2px

Memory Types

SmartMemory has five core memory types (semantic, episodic, procedural, pending, zettelkasten), extended types for specialized use cases (reasoning, opinion, observation, decision, plan, code), and structured types for schema-mapped data (tool_call, plan_task, conversation_turn, hook_capture). See Memory Types for the full reference.

Every memory item carries provenance metadata — origin tracks where it came from (e.g., user:cli, evolver:opinion_synthesis, structured:decision), confidence tracks certainty (0.0-1.0), and derived_from links to parent items for lineage tracking.

Memory Dynamics

Items aren't static. SmartMemory tracks an activation score per item that rises on retrieval, decays over time, and feeds a retrieval-layer composite that decides what surfaces on a query. Cold items compress progressively through a five-tier ladder; analytical questions pull in graph neighbors via bounded spreading activation and Personalized PageRank. Session pins let callers force-include specific items for a conversational turn.

The full model — activation, decay, tier compression, surfacing router, spreading, PPR, pins — is covered in Memory Dynamics. API reference in api/surfacing. Task-oriented configuration in guides/tuning-surfacing.

The Core Memory Types

1. Semantic Memory

What it stores: Facts, concepts, and general knowledge that are independent of personal experience.

# Examples of semantic memory
memory.ingest("Python is a programming language")
memory.ingest("The capital of France is Paris")
memory.ingest("Machine learning is a subset of AI")

Characteristics:

Timeless factual information
Shared knowledge across users
Structured relationships between concepts
High connectivity with other facts

2. Episodic Memory

What it stores: Personal experiences and events with temporal and contextual information.

# Examples of episodic memory
memory.ingest("I attended the AI conference in San Francisco last week")
memory.ingest("Had lunch with Sarah at the Italian restaurant yesterday")
memory.ingest("Completed my first Python project in 2020")

Characteristics:

Time-bound experiences
Personal and contextual
Rich in emotional and sensory details
Connected to specific locations and people

3. Procedural Memory

What it stores: Skills, procedures, and how-to knowledge.

# Examples of procedural memory
memory.ingest("To deploy to AWS: 1) Build image 2) Push to ECR 3) Update ECS")
memory.ingest("Git workflow: branch → commit → push → PR → merge")
memory.ingest("Morning routine: exercise → shower → coffee → emails")

Characteristics:

Step-by-step instructions
Action sequences and workflows
Skill-based knowledge
Executable procedures

4. Pending Memory

What it stores: Temporary information that's currently being processed or actively used.

# Examples of pending memory
memory.ingest("Currently debugging the authentication issue")
memory.ingest("Meeting with team at 3 PM today")
memory.ingest("Need to review PR #123 before EOD")

Characteristics:

Temporary and context-dependent
High priority for immediate access
Frequently updated or replaced
Limited capacity by design

5. Zettelkasten Memory

What it stores: Atomic, interconnected notes with automatic cross-linking and knowledge graph formation.

# Examples of zettelkasten memory
memory.ingest("Attention mechanisms allow models to focus on relevant input parts")
memory.ingest("Neural networks learn through backpropagation")

Characteristics:

One idea per note (atomic)
Automatic entity extraction and linking
Bidirectional references
Emergent knowledge structure

Extended Memory Types

Beyond the five core types, SmartMemory supports extended memory types:

Reasoning: Chain-of-thought traces capturing the why behind decisions. See Reasoning Traces.
Opinion: Beliefs with confidence scores that strengthen or weaken over time. See Opinions & Observations.
Observation: Synthesized entity summaries from scattered facts. See Opinions & Observations.
Decision: First-class decisions with confidence tracking, provenance chains, and lifecycle management. See Decision Memory.

Memory Type Interactions

graph TD
    subgraph "Memory Types"
        S1["🔍 Semantic Memory<br/>Facts & Concepts"]
        E1["📚 Episodic Memory<br/>Personal Events"]
        P1["⚙️ Procedural Memory<br/>Skills & Procedures"]
        W1["💭 Pending Memory<br/>Active Tasks"]
    end
    
    S1 --> INT1["Cross-Memory Relationships"]
    E1 --> INT1
    P1 --> INT1
    W1 --> INT1
    
    INT1 --> REL1["🔗 Provides Context"]
    INT1 --> REL2["🎯 Applied In Experiences"]
    INT1 --> REL3["📚 References Knowledge"]
    INT1 --> REL4["⚙️ Uses Skills"]
    
    REL1 --> EV["Evolution Patterns"]
    REL2 --> EV
    REL3 --> EV
    REL4 --> EV
    
    EV --> EV1["🧬 Consolidation"]
    EV --> EV2["🔗 Link Formation"]
    EV --> EV3["📊 Quality Assessment"]
    
    style S1 fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style E1 fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style P1 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style W1 fill:#e8f5e8,stroke:#388e3c,stroke-width:2px

Intelligent Processing Pipeline

1. Ingestion Flow (11 Stages)

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

Input → Classification → Extraction → Storage → Linking → 
Vector → Enrichment → Grounding → Evolution → Clustering → Versioning

Stage	Description
1. Input Adaptation	Convert str/dict/MemoryItem to standard format
2. Classification	Determine memory type (semantic, episodic, procedural, pending)
3. Extraction	Extract entities & relations (LLM → SpaCy → GLiNER fallback)
4. Storage	Create memory node + entity nodes in FalkorDB
5. Linking	Connect to related existing memories
6. Vector Storage	Generate embeddings, store in HNSW index
7. Enrichment	Add Wikipedia summaries, categories, metadata
8. Grounding	Create GROUNDED_IN edges to Wikipedia nodes
9. Evolution	Promote pending → episodic/procedural if thresholds met
10. Clustering	SemHash + embedding deduplication of entities
11. Versioning	Create bi-temporal version record

Extraction (Fallback Chain)

SmartMemory uses multiple extractors with automatic fallback:

LLM → GLiNER → SpaCy

LLM Extractor: Highest accuracy; uses a configurable LLM resolved at runtime via the model router (get_default_model())
GLiNER Extractor: Fast local CPU inference, privacy-preserving
SpaCy Extractor: NER + dependency parsing with regex fallback

Grounding (Wikipedia)

Establishes provenance by linking entities to Wikipedia:

Creates shared Wikipedia nodes (is_global=True)
Creates GROUNDED_IN edges from entities to Wikipedia
Enables source verification and fact checking

Clustering

Deduplicates entities using multi-level resolution:

SemHash: Fast deterministic dedup (0.95 threshold)
KMeans: Embedding clustering (~128 items per cluster)
LLM: Semantic clustering (Joe ↔ Joseph, ML ↔ machine learning)
Merge: Graph node consolidation

Versioning (Bi-Temporal)

Tracks all changes with two time dimensions:

Valid time: When the fact was true in the real world
Transaction time: When the fact was recorded in the system
Enables time-travel queries and version comparison

2. Entity and Relationship Extraction

SmartMemory automatically identifies and extracts structured information:

# Input
memory.add("John Smith works at Google as a software engineer")

# Extracted entities
entities = [
    {"name": "John Smith", "type": "PERSON"},
    {"name": "Google", "type": "ORGANIZATION"},
    {"name": "software engineer", "type": "JOB_TITLE"}
]

# Extracted relationships
relationships = [
    {"source": "John Smith", "target": "Google", "type": "WORKS_AT"},
    {"source": "John Smith", "target": "software engineer", "type": "HAS_ROLE"}
]

3. Automatic Linking

SmartMemory creates intelligent connections between memories:

Semantic similarity: Memories with similar meaning
Entity overlap: Memories sharing common entities
Temporal proximity: Memories from similar time periods
Contextual relevance: Memories from similar contexts

Evolution Algorithms

SmartMemory continuously improves itself through evolution algorithms:

1. Maximal Connectivity Evolver

Creates dense, high-quality connections between related memories.

# Before evolution
Memory A: "Python programming"
Memory B: "Data science projects"
# No connection

# After evolution
Memory A ←→ Memory B (USED_FOR relationship)

Semantic Similarity: Meaning-based comparison using embeddings
Content Similarity: Text-based overlap and patterns
Temporal Similarity: Time-based relationships
Metadata Similarity: Structural and categorical similarities

Weighted Scoring

total_similarity = (
    semantic_similarity * 0.4 +
    content_similarity * 0.3 +
    temporal_similarity * 0.2 +
    metadata_similarity * 0.1
)

Graph-Based Storage

SmartMemory uses graph databases to model complex relationships:

Node Types

Memory Nodes: Individual memories with content and metadata
Entity Nodes: Extracted entities (dual-node pattern for reuse)
Wikipedia Nodes: Global grounding nodes (shared across users)
Version Nodes: Bi-temporal version records

Relationship Types

CONTAINS: Memory contains entity
GROUNDED_IN: Entity grounded to Wikipedia
HAS_VERSION: Memory has version history
RELATED_TO: General semantic relationships
PRECEDES/FOLLOWS: Temporal sequences
CAUSED_BY/CAUSES: Causal relationships
PART_OF/HAS_PART: Compositional relationships

Graph Queries

# Find all memories related to "Python"
related_memories = memory.get_neighbors("python_concept_id")

# Get linked memories (filter the returned triples by edge type as needed)
sequence = memory.get_links("event_id", memory_type="episodic")

# Find linked memories of another type
causes = memory.get_links("outcome_id", memory_type="semantic")

Background Processing

SmartMemory supports asynchronous processing for better performance:

Fast Ingestion

# Store immediately, process in background
memory.ingest("Important information that needs immediate storage")

Processing Queue

Priority-based: Important memories processed first
Batch processing: Efficient bulk operations
Retry logic: Handles temporary failures
Health monitoring: Tracks processing status

Ontology Management

SmartMemory supports structured knowledge organization:

Ontology Components

Entity Types: Definitions of entity categories
Relationship Types: Allowed relationship patterns
Validation Rules: Constraints and consistency checks
Inheritance Hierarchies: Type hierarchies and specialization

Hybrid Approach

Freeform extraction: Automatic, flexible entity discovery
Ontology-guided: Structured, validated knowledge organization
Seamless migration: Evolution from freeform to structured

Search and Retrieval

SmartMemory provides multiple search strategies:

Search Types

Semantic Search: Meaning-based retrieval using embeddings
Graph Search: Relationship-based traversal
Hybrid Search: Combined semantic and graph approaches
Filtered Search: Type-specific or metadata-filtered results

Search Context

# Context-aware search
results = memory.search(
    query="machine learning",
    memory_type="semantic",
    top_k=10
)

# Note: User/tenant filtering is handled automatically by ScopeProvider
# in multi-tenant deployments. Time-range filtering can be done post-search.

Component Architecture

SmartMemory follows a modular, component-based architecture:

Core Components

CRUD: Create, Read, Update, Delete operations
Search: Multi-strategy search (vector + graph + text fallbacks)
Linking: Relationship discovery and management
Enrichment: Wikipedia integration and metadata enhancement
Grounding: Provenance linking to external knowledge
Evolution: Memory promotion (pending → episodic/procedural)
Clustering: Entity deduplication (SemHash + KMeans + LLM)
Challenging: Contradiction detection (LLM → Graph → Embedding → Heuristic cascade)
Versioning: Bi-temporal tracking with time-travel queries
Monitoring: Performance and health tracking

Benefits

Modularity: Easy to extend and customize
Testability: Components can be tested in isolation
Flexibility: Mix and match components as needed
Maintainability: Clear separation of concerns

Integration Patterns

Tool-Based Integration

SmartMemory provides tools for agentic workflows:

# MCP tools for LLM agents
tools = [
    "memory_add",
    "memory_search", 
    "memory_get",
    "memory_update",
    "memory_delete"
]

Horizontal scaling: Multiple worker processes
Vertical scaling: Optimized algorithms and data structures
Caching: Intelligent caching strategies
Indexing: Efficient search indexes

Optimization

Lazy loading: Load data only when needed
Batch operations: Process multiple items efficiently
Connection pooling: Reuse database connections
Memory management: Efficient memory usage patterns

Best Practices

Choose appropriate memory types for your data
Enable background processing for better performance
Use structured data when possible for better extraction
Monitor evolution algorithms to ensure quality
Configure similarity weights for your use case
Implement proper error handling for robustness
Use caching for frequently accessed data

Next Steps

Memory Types - Detailed guide to each memory type
Ingestion Flow - Deep dive into the processing pipeline
Evolution Algorithms - Understanding memory optimization
Similarity Framework - Advanced similarity concepts

Core Concepts

On this page