Memory/docs/architecture.md

Memory System Architecture

Overview

The memory system architecture is designed with a layered approach, separating concerns between:

1. Storage layer
2. Memory integration layer
3. Assistant layer (LLM integration)

This modular design allows for flexibility, extensibility, and ease of maintenance.

System Layers

┌────────────────────────────────────────────────────┐
│                                                    │
│  ┌────────────────────────────────────────────┐    │
│  │           OllamaMemoryAssistant            │    │
│  │                                            │    │
│  │  - User interface for memory interaction   │    │
│  │  - LLM integration via Ollama              │    │
│  │  - Query processing with context           │    │
│  └────────────────────┬───────────────────────┘    │
│                       │                            │
│  ┌────────────────────▼───────────────────────┐    │
│  │           IntegratedMemory                 │    │
│  │                                            │    │
│  │  - Combines memory types                   │    │
│  │  - Manages context generation              │    │
│  │  - Coordinates memory operations           │    │
│  └────────────────────┬───────────────────────┘    │
│                       │                            │
│  ┌────────────────────▼───────────────────────┐    │
│  │           SimpleMemoryStore                │    │
│  │                                            │    │
│  │  - Basic storage implementation            │    │
│  │  - Persistence with JSON files             │    │
│  │  - Namespaced key-value storage            │    │
│  └────────────────────────────────────────────┘    │
│                                                    │
└────────────────────────────────────────────────────┘

Key Components

1. SimpleMemoryStore

The foundation of the system, providing basic storage capabilities:

• Responsibilities:

  • Store and retrieve data by namespace and key
  • Provide basic search functionality
  • Handle persistence to disk (optional)
  • Manage file I/O for memory files

• Key Methods:

  • put(namespace, key, value): Store data
  • get(namespace, key): Retrieve data
  • search(namespace, query): Find relevant information
  • save() and load(): Handle persistence

2. IntegratedMemory

The integration layer that combines different memory types:

• Responsibilities:

  • Provide typed access to memory (semantic, episodic, procedural)
  • Generate context for LLM queries
  • Manage memory-specific operations
  • Coordinate between memory types

• Key Methods:

  • add_fact(concept, details): Add semantic memory
  • add_procedure(name, steps): Add procedural memory
  • add_interaction(query, response): Add episodic memory
  • generate_context(query): Create LLM context from memories

3. OllamaMemoryAssistant

The application layer that interfaces with Ollama LLM:

• Responsibilities:

  • Process user queries with memory context
  • Send requests to Ollama API
  • Update memory with new interactions
  • Present responses to the user

• Key Methods:

  • process_query(query): Process a query with memory context
  • learn_fact(concept, details): Add to semantic memory
  • learn_procedure(name, steps): Add to procedural memory

Data Flow

1. Query Processing:

   User Query → OllamaMemoryAssistant → IntegratedMemory (context) → Ollama API → Response
   

2. Memory Addition:

   New Knowledge → OllamaMemoryAssistant → IntegratedMemory → SimpleMemoryStore
   

3. Persistence:

   Memory Update → SimpleMemoryStore → JSON File
   

Extensibility

The system architecture allows for several extension points:

1. Storage Backends: Replace SimpleMemoryStore with other implementations (e.g., database, vector store)
2. LLM Integration: Swap Ollama with other LLM providers
3. Memory Types: Add new memory types beyond the current three
4. Context Generation: Customize how context is generated for different query types

Configuration Options

• Persistence: Enable/disable memory persistence
• Memory Directory: Configure where memory files are stored
• Model Selection: Choose which LLM model to use via Ollama
• Base URL: Configure the Ollama API endpoint