MemoryWeave

MemoryWeave is an experimental approach to memory management for language models that uses a "contextual fabric" approach inspired by biological memory systems. Rather than traditional knowledge graph approaches with discrete nodes and edges, MemoryWeave focuses on capturing rich contextual signatures of information for improved long-context coherence in LLM conversations.

Note: This project has undergone a major architectural refactoring to a component-based design. See the Migration Guide for details on transitioning from the legacy architecture.

Table of Contents

• Key Concepts
• Architecture
• Installation
• Quick Start
• Benchmarks
• Current Limitations
• Roadmap
• Contributing

Key Concepts

MemoryWeave implements several biologically-inspired memory management principles:

• Contextual Fabric: Memory traces capture rich contextual signatures rather than isolated facts
• Activation-Based Retrieval: Memory retrieval uses dynamic activation patterns similar to biological systems
• Episodic Structure: Memories maintain temporal relationships and episodic anchoring
• Non-Structured Memory: Works with raw LLM outputs without requiring structured formats
• ART-Inspired Clustering: Optional memory categorization based on Adaptive Resonance Theory

More about the contextual fabric approach

Traditional LLM memory systems often rely on vector databases with discrete entries, losing much of the rich contextual information that helps humans navigate memories effectively. MemoryWeave attempts to address this by:

1. Contextual Encoding: Memories include surrounding context and metadata
2. Activation Dynamics: Recently or frequently accessed memories have higher activation levels
3. Temporal Organization: Memories maintain their relationship to other events in time
4. Associative Retrieval: Memories can be retrieved through multiple pathways beyond simple similarity
5. Dynamic Categorization: Memories self-organize into categories using ART-inspired clustering

This allows for more nuanced and effective memory retrieval during conversations, especially over long contexts or multiple sessions.

Architecture

MemoryWeave uses a component-based architecture with several modular pieces that can be configured for different use cases:

Core Components

1. Memory Management

   • MemoryManager: Coordinates memory operations and component interactions
   • MemoryStore: Stores embeddings, content, and metadata
   • VectorStore: Handles vector similarity search and indexing
   • ActivationManager: Manages memory activation levels

2. Retrieval Strategies

   • SimilarityRetrievalStrategy: Pure vector similarity-based retrieval
   • TemporalRetrievalStrategy: Time and recency-based retrieval
   • HybridRetrievalStrategy: Combines similarity and temporal retrieval
   • TwoStageRetrievalStrategy: Advanced multi-stage retrieval process

3. Query Processing

   • QueryAnalyzer: Analyzes and classifies query types
   • QueryAdapter: Adapts retrieval parameters based on query
   • PersonalAttributeManager: Extracts and manages personal attributes

4. Post-Processing

   • SemanticCoherenceProcessor: Ensures retrieved memories are coherent
   • KeywordBoostProcessor: Enhances keyword-relevant memories
   • AdaptiveKProcessor: Dynamically adjusts number of results

5. Pipeline System

   • PipelineBuilder: Constructs configurable processing pipelines
   • ComponentRegistry: Manages component registration and access

Component Architecture Diagram

flowchart TD
    LLM["**LLM Framework:**<br>Hugging Face, OpenAI, LangChain"] --> Adapter
    Adapter["**Adapter Layer**<br>HuggingFaceAdapter, etc."] --> Retriever
    
    subgraph Components[Component Architecture]
        Retriever[Retriever] --> MemMgr[MemoryManager]
        MemMgr --> Components
        
        subgraph Components[Component Registry]
            MemStore[MemoryStore]
            VecStore[VectorStore]
            ActMgr[ActivationManager]
            QAnalyzer[QueryAnalyzer]
            QAdapter[QueryAdapter]
            RetStrats[Retrieval Strategies]
            PostProcs[Post Processors]
            PipeBuilder[Pipeline Builder]
        end
    end
    
    MemMgr --> Pipeline[Configured Pipeline]
    Pipeline --> Results[Retrieved Memories]
    Results --> Adapter
    
    classDef primary fill:#d0e0ff,stroke:#3080ff,stroke-width:2px
    classDef secondary fill:#e0f0e0,stroke:#30a030,stroke-width:2px
    
    class MemMgr,Retriever,Pipeline primary
    class Components,LLM,Adapter,Results secondary

Loading

flowchart TD
    subgraph MemoryWeave[Component Architecture]
        MemMgr[MemoryManager]
        Retriever[Retriever]
        Pipeline[Pipeline]
        
        subgraph Storage[Storage Components]
            MemStore[MemoryStore]
            VecStore[VectorStore]
            ActMgr[ActivationManager]
        end
        
        subgraph QueryProcessing[Query Processing]
            QAnalyzer[QueryAnalyzer]
            QAdapter[QueryAdapter]
        end
        
        subgraph RetrievalStrategies[Retrieval Strategies]
            SimStrat[SimilarityStrategy]
            TempStrat[TemporalStrategy]
            HybridStrat[HybridStrategy]
            TwoStageStrat[TwoStageStrategy]
        end
        
        subgraph PostProcessing[Post Processors]
            SemCoh[SemanticCoherence]
            KeyBoost[KeywordBoost]
            AdaptiveK[AdaptiveK]
        end
    end
    
    User[User Query] --> Retriever
    Retriever --> MemMgr
    Retriever --> QAnalyzer
    QAnalyzer --> QAdapter
    QAdapter --> Pipeline
    Pipeline --> RetrievalStrategies
    RetrievalStrategies --> Storage
    RetrievalStrategies --> PostProcessing
    Pipeline --> Results[Retrieved Memories]
    
    classDef primary fill:#d0e0ff,stroke:#3080ff,stroke-width:2px
    classDef secondary fill:#e0f0e0,stroke:#30a030,stroke-width:2px
    classDef external fill:#f0e0d0,stroke:#a07030,stroke-width:2px
    
    class MemMgr,Retriever,Pipeline primary
    class Storage,QueryProcessing,RetrievalStrategies,PostProcessing secondary
    class User,Results external

Loading

Memory retrieval mechanism

flowchart TD
    Query[User Query] --> QueryEmbed[Encode Query]
    QueryEmbed --> RetrievalStrategy{Retrieval<br>Strategy}
    
    RetrievalStrategy -->|Similarity| SimilarityRetrieval[Similarity-Based<br>Retrieval]
    RetrievalStrategy -->|Temporal| TemporalRetrieval[Recency-Based<br>Retrieval]
    RetrievalStrategy -->|Hybrid| HybridRetrieval[Hybrid<br>Retrieval]
    
    SimilarityRetrieval --> ConfidenceFilter[Confidence<br>Thresholding]
    TemporalRetrieval --> ActivationBoost[Activation<br>Boosting]
    HybridRetrieval --> KeywordBoost[Keyword<br>Boosting]
    
    ConfidenceFilter --> CoherenceCheck{Semantic<br>Coherence Check}
    ActivationBoost --> AdaptiveK[Adaptive K<br>Selection]
    KeywordBoost --> PersonalAttributes[Personal Attribute<br>Enhancement]
    
    CoherenceCheck -->|Yes| CoherentMemories[Coherent<br>Memories]
    CoherenceCheck -->|No| BestMemory[Best Single<br>Memory]
    
    AdaptiveK --> FinalMemories[Final Retrieved<br>Memories]
    PersonalAttributes --> FinalMemories
    CoherentMemories --> FinalMemories
    BestMemory --> FinalMemories
    
    FinalMemories --> PromptAugmentation[Prompt<br>Augmentation]
    PromptAugmentation --> LLMGeneration[LLM<br>Generation]
    
    classDef primary fill:#d0e0ff,stroke:#3080ff,stroke-width:2px
    classDef secondary fill:#e0f0e0,stroke:#30a030,stroke-width:2px
    classDef decision fill:#ffe0d0,stroke:#ff8030,stroke-width:2px
    
    class Query,QueryEmbed,FinalMemories,PromptAugmentation,LLMGeneration primary
    class SimilarityRetrieval,TemporalRetrieval,HybridRetrieval,ConfidenceFilter,ActivationBoost,KeywordBoost,CoherentMemories,BestMemory,AdaptiveK,PersonalAttributes secondary
    class RetrievalStrategy,CoherenceCheck decision

Loading

flowchart TD
    subgraph ART[ART-Inspired Clustering]
        Input[New Memory] --> Vigilance{Vigilance<br>Check}
        Vigilance -->|Match| UpdateCategory[Update Existing<br>Category]
        Vigilance -->|No Match| CreateCategory[Create New<br>Category]
        UpdateCategory --> Consolidation{Consolidation<br>Check}
        CreateCategory --> Consolidation
        Consolidation -->|Needed| MergeCategories[Merge Similar<br>Categories]
        Consolidation -->|Not Needed| Done[Done]
        MergeCategories --> Done
    end
    
    subgraph Retrieval[Category-Based Retrieval]
        QueryInput[Query] --> CategoryMatch[Find Matching<br>Categories]
        CategoryMatch --> MemoryRetrieval[Retrieve Memories<br>from Categories]
        MemoryRetrieval --> Ranking[Rank by<br>Relevance]
        Ranking --> TopResults[Return Top<br>Results]
    end
    
    classDef primary fill:#d0e0ff,stroke:#3080ff,stroke-width:2px
    classDef secondary fill:#e0f0e0,stroke:#30a030,stroke-width:2px
    classDef decision fill:#ffe0d0,stroke:#ff8030,stroke-width:2px
    
    class Input,QueryInput,TopResults primary
    class UpdateCategory,CreateCategory,CategoryMatch,MemoryRetrieval,Ranking,MergeCategories secondary
    class Vigilance,Consolidation decision

Loading

Installation

MemoryWeave is available as a Python package:

# Using UV (recommended)
uv pip install memoryweave

# Using pip
pip install memoryweave

For development install:

# Clone the repository
git clone https://github.com/yourusername/memoryweave.git
cd memoryweave

# Install in development mode
uv pip install -e .

# Install development dependencies
uv pip install -g dev

Quick Start

Here's a simple example of using MemoryWeave with the new component architecture:

from memoryweave.components import Retriever
from memoryweave.components.memory_manager import MemoryManager
from sentence_transformers import SentenceTransformer

# Initialize embedding model
embedding_model = SentenceTransformer("all-MiniLM-L6-v2")

# Create memory manager
memory_manager = MemoryManager()

# Create retriever
retriever = Retriever(memory=memory_manager, embedding_model=embedding_model)

# Configure retriever (optional)
retriever.configure_query_type_adaptation(enable=True)
retriever.configure_two_stage_retrieval(enable=True)
retriever.initialize_components()

# Add some memories
texts = [
    "My favorite color is blue.",
    "I visited Paris last summer.",
    "Python is a programming language created by Guido van Rossum."
]

for text in texts:
    embedding = embedding_model.encode(text)
    memory_manager.add_memory(embedding, text)

# Retrieve memories based on a query
query = "What programming languages do I know?"
results = retriever.retrieve(query, top_k=3)

# Process results
for result in results:
    print(f"Score: {result['relevance_score']:.4f} - {result['content']}")

See the examples directory for more detailed examples and the Migration Guide for transitioning from the legacy architecture.

Benchmarks

MemoryWeave includes comprehensive benchmarking tools to evaluate and compare different retrieval approaches, with special focus on the contextual fabric architecture.

Contextual Fabric Benchmark

The most important benchmark compares the contextual fabric architecture with traditional retrieval methods:

# Run the complete benchmark suite with multiple memory sizes
./run_contextual_fabric_benchmark.sh

# Run with a specific memory size
uv run python -m benchmarks.contextual_fabric_benchmark --memories 100

This benchmark tests how well the contextual fabric architecture handles:

• Conversation context understanding
• Temporal reference resolution
• Associative memory linking
• Activation patterns
• Episodic memory retrieval

Other Benchmarks

# Run baseline comparison (compare against BM25 and vector search)
uv run python run_baseline_comparison.py

# Run synthetic benchmark (evaluates different configurations)
uv run python run_synthetic_benchmark.py

# Run semantic benchmark (tests performance on real-world queries)
uv run python run_semantic_benchmark.py

# Run custom benchmark script
uv run python -m benchmarks.memory_retrieval_benchmark

# Visualize benchmark results
python examples/visualize_results.py synthetic_benchmark_results.json

Current benchmark results show significant improvements when using the contextual fabric approach:

Memory Size	Hybrid BM25+Vector	Contextual Fabric	Improvement
20 memories	0.136 F1	0.290 F1	+0.154 F1
100 memories	0.056 F1	0.217 F1	+0.161 F1
500 memories	0.033 F1	0.075 F1	+0.042 F1

For detailed information on running and interpreting benchmarks, see the Benchmark Guide.

Current Limitations

While MemoryWeave has undergone significant architectural improvements, there are still some limitations:

• Limited testing with large-scale models and large memory stores
• No persistence layer for long-term storage
• Query analyzer needs improvements for certain query types
• ✅ Performance with large memory sets is now optimized through ANN implementation
• Vector retrieval performance in benchmarks lags behind BM25 for some query types
• Hybrid retrieval still needs tuning to combine BM25 and vector advantages

Roadmap

See the ROADMAP.md file for detailed information on planned developments. Current priorities include:

• Fix and improve query analyzer accuracy
• Add persistence layer for long-term memory storage
• ✅ Optimize performance for large memory sets (implemented ANN search)
• Improve hybrid retrieval to combine BM25 and vector search advantages
• Expand benchmarking datasets for more diverse query types
• Implement visualization improvements for benchmark results
• Enhance vector retrieval precision while maintaining high recall

Check the feature matrix for the current implementation status of various features.

Contributing

Contributions are welcome! Please check our documentation first to understand the project's architecture and current state.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Developed with AI Assistance

This project is developed with assistance from AI tools, particularly Claude, to accelerate development, improve code quality, and automate testing. We believe in transparency about AI usage in our development process while maintaining high standards for all contributions.

Development

This project uses uv for package management:

# Install in development mode
uv pip install -e .

# Install development dependencies
uv pip install -g dev

# Run tests
uv run python -m pytest

# Run just unit tests
uv run python -m pytest -m unit

# Run type checking and linting
uv run mypy memoryweave/
uv run ruff check memoryweave/

# Format code
uv run ruff format memoryweave/

Documentation

For more detailed information, check out these additional resources:

• Migration Guide: How to migrate from legacy to component architecture
• Feature Matrix: Current implementation status of features
• Implementation Constraints: Known limitations and constraints
• Refactoring Progress: Summary of architectural refactoring progress
• Plan for Improvement: Detailed plan for addressing current issues