# How the Layered Memory System (L0-L4) Works in GenericAgent: A Deep Dive into the Five-Level Architecture

> Explore GenericAgent's Layered Memory System (L0-L4). Discover how L4 auto-compresses session logs for efficient long-term recall and cost savings.

- Repository: [LJQ/GenericAgent](https://github.com/lsdefine/GenericAgent)
- Tags: deep-dive
- Published: 2026-04-16

---

**The Layered Memory System in GenericAgent organizes persistent knowledge into five distinct levels (L0-L4), where L4 automatically compresses raw session logs into searchable archives every 12 hours via a background scheduler, enabling long-term recall while minimizing token usage and storage costs.**

The GenericAgent repository implements a sophisticated **Layered Memory System (L0-L4)** to manage persistent knowledge across a hierarchical five-level stack. This architecture separates immutable behavioral constraints from dynamic session histories, optimizing for both immediate retrieval and long-term storage efficiency. While L0 through L3 handle static configurations, environment facts, and task-specific procedures, the L4 layer serves as the automated archival engine that transforms raw dialogue logs into compressed, searchable histories.

## The Five-Level Memory Hierarchy (L0-L4)

GenericAgent partitions all persistent knowledge into five layers, each designed to minimize token consumption and hallucination risks:

- **L0 – Meta Rules**: Hard-coded constants embedded directly in the source code (few KB). These contain core behavioral constraints and safety rules that never change during runtime.
- **L1 – Insight Index**: Stored in [`global_mem_insight.txt`](https://github.com/lsdefine/GenericAgent/blob/main/global_mem_insight.txt) (≤30 lines, <1 KB). This ultra-compact "pointer map" routes queries to deeper layers without loading full contexts.
- **L2 – Global Facts**: Stored in [`global_mem.txt`](https://github.com/lsdefine/GenericAgent/blob/main/global_mem.txt) (few KB to MB). Holds stable environment facts such as file paths, credentials, and configuration constants.
- **L3 – Task-Level Records**: Stored in the `memory/` folder as Markdown and Python files (unbounded). Contains reusable SOPs, scripts, or specialized data for particular tasks.
- **L4 – Session Archive**: Stored in `memory/L4_raw_sessions/` (GB-scale when archived). Contains compressed logs of completed sessions, turned into a searchable history for long-horizon recall.

The L4 layer is the focus of most archival operations—it automatically processes raw model-response logs into compact, indexed archives.

## How L4 Session Archiving Is Triggered

A background scheduler in [`reflect/scheduler.py`](https://github.com/lsdefine/GenericAgent/blob/main/reflect/scheduler.py) manages the L4 compression cycle. Every 12 hours (43,200 seconds), it invokes the archiver:

```python

# reflect/scheduler.py (excerpt)

if _time.time() - _l4_t > 43200:          # 12 h

    _l4_t = _time.time()
    import sys; sys.path.insert(0, os.path.join(_dir, '../memory/L4_raw_sessions'))
    from compress_session import batch_process
    raw_dir = os.path.join(_dir, '../temp/model_responses')
    r = batch_process(raw_dir, dry_run=False)   # real run

    print(f'[L4 cron] {r}')

```

The scheduler dynamically inserts the `L4_raw_sessions` package into the import path, loads `compress_session.batch_process`, and points it at `temp/model_responses` where the model writes raw logs.

## The Compression Pipeline: Inside compress_session.py

The [`memory/L4_raw_sessions/compress_session.py`](https://github.com/lsdefine/GenericAgent/blob/main/memory/L4_raw_sessions/compress_session.py) file implements the core L4 logic through four primary operations.

### Parsing and Compressing Raw Sessions

The `compress_session` function handles individual log files:

```python
def compress_session(src, dst_dir=None):
    """
    • Reads a `model_responses_*.txt` file.
    • Detects its format (JSON‑style or “raw” with markers).
    • Extracts timestamps to build a filename:  MMDD_HHMM‑MMDD_HHMM.txt
    • If raw, calls `_compress_raw` to strip the duplicated system‑prompt /
      assistant‑echo sections.
    • Writes the compressed text to `dst_dir` (default = L4 directory).
    """

```

The function returns the destination path and a statistics dictionary containing original size, new size, and compression ratio.

### Stripping Redundant Content

Raw model outputs often contain duplicated content. The `_compress_raw` function removes the assistant echo:

```python
def _compress_raw(text):
    """
    Raw format (B) looks like:
      === Prompt === …  
      === USER === …  
      === ASSISTANT === …   ← echo of the prompt, not needed  
      === Response === …
    The function keeps only Prompt, USER, and Response blocks,
    removing the assistant‑echo block.
    """

```

By discarding the `=== ASSISTANT ===` echo block while preserving the essential Prompt, USER, and Response sections, the system dramatically reduces file size without losing conversational context.

### Extracting History for Searchable Recall

The `extract_history` function prepares data for fast lookup:

```python
def extract_history(src, session_name=None):
    """
    Reads a compressed L4 file and pulls all `<history>` XML blocks.
    Returns a deduplicated list of "[USER]" / "[Agent]" lines.
    """

```

The extracted history is appended to [`all_histories.txt`](https://github.com/lsdefine/GenericAgent/blob/main/all_histories.txt), enabling the agent to search across all past sessions without loading individual files.

### Batch Processing and Monthly Archiving

The `batch_process` function orchestrates the complete pipeline through six phases:

1. **Scan**: Identifies all `model_responses_*.txt` files, skipping those modified within the last 2 hours
2. **Compress & Extract**: Invokes `compress_session` and `extract_history` for each file
3. **Append History**: Merges extracted histories into [`all_histories.txt`](https://github.com/lsdefine/GenericAgent/blob/main/all_histories.txt)
4. **Archive**: Packages sessions into monthly zip files (`YYYY-MM.zip`)
5. **Cleanup**: Deletes original raw files and duplicates to free space

When `dry_run=False`, the scheduler triggers this pipeline to persist changes permanently.

## Integration With Higher Memory Layers

The L4 archive maintains bidirectional relationships with upper layers:

- **L3 → L4**: When tasks complete, the agent writes SOPs and scripts to `memory/` (L3). The raw model outputs that generated these artifacts remain in `temp/model_responses/` until the L4 archiver compresses them, making the **origin** of every L3 artifact traceable through the session archive.
- **L1 Indexing**: According to [`memory_management_sop.md`](https://github.com/lsdefine/GenericAgent/blob/main/memory_management_sop.md), the L1 Insight Index must contain pointers to new L3 or L4 entries. After a successful L4 batch run, maintenance routines update [`global_mem_insight.txt`](https://github.com/lsdefine/GenericAgent/blob/main/global_mem_insight.txt) with concise key-to-session mappings.
- **L2 Facts**: Stable environment facts discovered during sessions (API endpoints, credentials) are written to [`global_mem.txt`](https://github.com/lsdefine/GenericAgent/blob/main/global_mem.txt#L2). The L4 archive stores the **conversational context** that led to these facts, providing provenance for future reasoning.

## Practical Examples: Manual L4 Operations

While the scheduler handles automatic archiving, developers can interact with L4 directly.

### Running the Archiver On Demand

Trigger the compression pipeline manually for specific directories:

```python

# Example: compress and archive all raw model responses in ./temp/model_responses

from memory.L4_raw_sessions.compress_session import batch_process

raw_folder = 'temp/model_responses'      # path relative to repository root

report = batch_process(raw_folder, dry_run=False)   # set dry_run=False to apply

print('L4 archiving finished:')
print(f"  Processed: {report['processed']}")
print(f"  New sessions added: {report['new_sessions']}")
print(f"  Raw files deleted: {report.get('deleted_raw', 0)}")

```

Setting `dry_run=False` persists the compressed archives and deletes the original raw files, identical to the scheduler's cron job.

### Retrieving Historical Sessions

Query the consolidated history file to recall previous conversations:

```python
import os

L4_DIR = os.path.join('memory', 'L4_raw_sessions')
history_path = os.path.join(L4_DIR, 'all_histories.txt')

def search_history(keyword: str):
    """Return all session blocks that contain the keyword."""
    with open(history_path, 'r', encoding='utf-8') as f:
        content = f.read()
    matches = [block for block in content.split('============================================================')
               if keyword.lower() in block.lower()]
    return matches

# Example usage:

for block in search_history('wechat'):
    print('--- SESSION START ---')
    print(block.strip())
    print('--- SESSION END ---\n')

```

The `search_history` function scans [`all_histories.txt`](https://github.com/lsdefine/GenericAgent/blob/main/all_histories.txt), returning any session blocks where the keyword appears. This provides the primary mechanism for the L4 layer to supply **long-term recall** to the agent's reasoning engine.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`memory/memory_management_sop.md`](https://github.com/lsdefine/GenericAgent/blob/main/memory/memory_management_sop.md) | Architectural specification defining all memory layers (L0-L4) and policies governing their interactions. |
| [`reflect/scheduler.py`](https://github.com/lsdefine/GenericAgent/blob/main/reflect/scheduler.py) | Background scheduler that triggers the L4 archiver every 12 hours via the `batch_process` function. |
| [`memory/L4_raw_sessions/compress_session.py`](https://github.com/lsdefine/GenericAgent/blob/main/memory/L4_raw_sessions/compress_session.py) | Core implementation containing `compress_session`, `_compress_raw`, `extract_history`, and `batch_process` functions. |
| [`memory/L4_raw_sessions/all_histories.txt`](https://github.com/lsdefine/GenericAgent/blob/main/memory/L4_raw_sessions/all_histories.txt) | Consolidated, deduplicated history file enabling fast keyword search across all archived sessions. |
| [`README.md`](https://github.com/lsdefine/GenericAgent/blob/main/README.md) | High-level overview of the five-layer memory system for new contributors. |

## Summary

- **The Layered Memory System (L0-L4)** in GenericAgent separates knowledge into five distinct tiers, from hard-coded meta rules (L0) to compressed session archives (L4).
- **L4 automation** runs every 12 hours via [`reflect/scheduler.py`](https://github.com/lsdefine/GenericAgent/blob/main/reflect/scheduler.py), invoking [`compress_session.py`](https://github.com/lsdefine/GenericAgent/blob/main/compress_session.py) to process raw logs without manual intervention.
- **Compression removes redundancy** by stripping assistant echo blocks while preserving essential Prompt, USER, and Response sections, dramatically reducing storage footprint.
- **Searchable history** is extracted into [`all_histories.txt`](https://github.com/lsdefine/GenericAgent/blob/main/all_histories.txt), enabling fast keyword-based recall across all past sessions without loading individual archive files.
- **Integration with upper layers** ensures that L3 artifacts remain traceable to their L4 origins, while L1 and L2 layers receive updated pointers and facts derived from archived sessions.

## Frequently Asked Questions

### What is the difference between L3 and L4 in GenericAgent's memory system?

L3 (Task-Level Records) stores reusable SOPs, scripts, and specialized data files in the `memory/` folder as Markdown and Python files, representing the agent's procedural knowledge. L4 (Session Archive) stores the raw conversational logs and model responses that generated those L3 artifacts, compressed and archived in `memory/L4_raw_sessions/`. While L3 contains the "what" (final procedures), L4 contains the "why" and "how" (conversational context and reasoning traces).

### How often does the L4 archiver run automatically?

The L4 archiver runs automatically every **12 hours** (43,200 seconds) via the background scheduler defined in [`reflect/scheduler.py`](https://github.com/lsdefine/GenericAgent/blob/main/reflect/scheduler.py). This cron-like mechanism checks the timestamp difference `_time.time() - _l4_t > 43200` and invokes `compress_session.batch_process` when the threshold is met, ensuring that raw model logs are regularly compressed without manual intervention.

### Can I manually trigger L4 compression for specific sessions?

Yes, you can manually invoke the L4 pipeline by importing `batch_process` from `memory.L4_raw_sessions.compress_session` and calling it with your target directory. Set `dry_run=False` to apply the compression and delete the original raw files, or `dry_run=True` to preview the changes. This allows on-demand archiving outside the 12-hour scheduler cycle, useful for debugging or immediate storage cleanup.

### How does GenericAgent prevent token overflow with the Layered Memory System?

The **Layered Memory System (L0-L4)** prevents token overflow through strict size constraints and selective retrieval. L0 (Meta Rules) and L1 (Insight Index) are kept under a few KB and 30 lines respectively, loading instantly into context. L4 archives are excluded from active context unless specifically queried via `search_history()` on the consolidated [`all_histories.txt`](https://github.com/lsdefine/GenericAgent/blob/main/all_histories.txt) file. By compressing raw logs (stripping redundant assistant echoes) and archiving older sessions into monthly zip files, the system ensures only the most relevant, compact data (L1-L3) consumes active token budget while maintaining GB-scale history in cold storage.