Memory System (Hippocampus)

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• monGARS/AGENTS.md
• monGARS/core/cortex/curiosity_engine.py
• monGARS/core/hippocampus.py
• monGARS/core/persistence.py
• tests/test_hippocampus.py

The Hippocampus module serves as the conversational memory system for monGARS. It is designed as a hybrid in-memory and persistent storage solution to manage conversation history efficiently. This architecture provides fast access to recent interactions while ensuring long-term durability of the data.

The system blends an in-memory deque for rapid, short-term access with a SQL persistence layer for long-term storage and hydration. It includes mechanisms for automatic data expiration, scheduled flushing of old entries, and on-demand history retrieval, making it a critical component for maintaining context in conversations.

Sources: README.md, monGARS/core/hippocampus.py:20-21

Architecture

The Hippocampus memory system is composed of an in-memory cache for each user and a persistent database backend. This hybrid approach balances performance with data durability.

The following diagram illustrates the main components and their interactions.

Core Components

Component	Description	File
Hippocampus	The main class orchestrating memory operations. It manages in-memory caches, persistence, and data lifecycle (TTL, flushing).	monGARS/core/hippocampus.py
MemoryItem	A dataclass representing a single conversational turn (query, response, timestamp) in memory.	monGARS/core/hippocampus.py
MemoryEntry	The SQLModel schema for storing conversation history in the persistent database.	monGARS/core/hippocampus.py
PersistenceRepository	An optional, secondary repository for fetching historical data if the primary SQL hydration fails.	monGARS/core/hippocampus.py
AsyncIOScheduler	An optional scheduler for periodically running the flush_now method to prune expired entries from memory and the database.	monGARS/core/hippocampus.py

Sources: monGARS/core/hippocampus.py:34-39, monGARS/core/hippocampus.py:46-73, monGARS/AGENTS.md

Class Diagram

This diagram shows the structure of the Hippocampus class and its relationship with the MemoryItem data structure.

Database Schema

Conversation history is persisted in the MemoryEntry table. The ttl column stores the absolute expiration timestamp.

Data Flow and Lifecycle

Storing a Memory Item

When a new conversation turn occurs, the store method is called. It creates a MemoryItem, adds it to the user's in-memory deque, and persists it to the database.

This sequence diagram shows the flow for storing a new memory item.

Retrieving Conversation History

The history method retrieves recent conversation items for a user. It features a lazy-hydration mechanism: if a user's history is not in memory, it is loaded from the database first.

Memory Pruning and Flushing

Expired items are removed from memory and the database to manage resources. This happens in two ways:

1. On-the-fly Pruning: When a new item is stored or history is retrieved, the user's in-memory deque is pruned of expired items.
2. Scheduled Flushing: The flush_now method, triggered by an AsyncIOScheduler, removes all expired entries from both the in-memory cache and the persistent database.

The following flowchart describes the flush_now process.

Configuration

The Hippocampus class is configurable via its constructor. The test suite demonstrates how these parameters are used during instantiation.

Parameter	Type	Default	Description
persistence	PersistenceRepository	PersistenceRepository()	An optional secondary persistence layer.
persist_on_store	bool	False	If True, saves to the persistence repository on every store call.
session_factory	AsyncSessionFactory	None	A factory for creating SQLAlchemy async sessions. Falls back to a default.
default_ttl	timedelta	24 hours	The default time-to-live for new memory items.
flush_interval_seconds	int	300	The interval in seconds for the scheduled flush_now job.
enable_scheduler	bool	True	Toggles the background scheduler for flushing expired entries.

Sources: monGans/core/hippocampus.py:42-58, tests/test_hippocampus.py

Integration and Usage

The Hippocampus module is a core service intended to be used by other parts of the cognition engine to provide conversational context. Test fixtures show that its caches and state should be reset between test runs to ensure hermetic tests. The CuriosityEngine uses a similar pattern of loading history from a database, highlighting a common architectural approach within the project for managing historical data.

Sources: monGARS/AGENTS.md, monGARS/core/cortex/curiosity_engine.py:210-247, tests/AGENTS.md