# How Insight Index (L1) and Global Facts (L2) Memory Layers Work in GenericAgent

> Understand GenericAgent's Insight Index (L1) and Global Facts (L2) memory layers. L1 offers fast context retrieval and L2 stores verified knowledge, both synchronized for system prompts.

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

---

**GenericAgent implements a two-tier memory system where L1 (Insight Index) stores concise routing pointers for fast context retrieval and L2 (Global Facts) maintains persistent verified knowledge, with both layers automatically synchronized and injected into every system prompt.**

GenericAgent organizes knowledge through a sophisticated layered memory architecture that separates fast-access indices from stable long-term storage. The **Insight Index (L1) and Global Facts (L2) memory layers** work together to minimize token usage while ensuring the agent retains critical context across sessions. This implementation, found in the `lsdefine/GenericAgent` repository, uses simple text files synchronized through specific update routines defined in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py).

## Understanding the Layered Memory Architecture

GenericAgent's memory system operates on a hierarchy where L1 serves as a hot cache of pointers and L2 acts as the cold storage of ground truth. According to the README at lines 136-137, L1 provides "minimal memory index for fast routing and recall" while L2 contains "stable knowledge accumulated over long-term operation."

## L1 Insight Index: Fast Routing and Contextual Pointers

The **L1 Insight Index** (symbol: **LI**) functions as a lightweight routing table that prevents the agent from scanning its entire memory base on every turn.

### What L1 Stores

- Concise single-line pointers to relevant facts, skills, and SOPs
- Contextual hints generated from recent task completions
- Routing metadata that maps queries to appropriate L2 entries

### File Location and Implementation

The L1 layer persists in [`memory/global_mem_insight.txt`](https://github.com/lsdefine/GenericAgent/blob/main/memory/global_mem_insight.txt). In [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) lines 65-76, the `get_global_memory()` function reads this file on every agent turn, concatenating its contents with L2 data for injection into the system prompt.

### Update Mechanism

When the agent completes a task, `do_start_long_term_update()` (defined in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) lines 9-16) extracts verified insights and writes them to the L1 file. This routine ensures the index remains synchronized with the underlying L2 knowledge base.

## L2 Global Facts: Persistent Long-Term Knowledge

The **L2 Global Facts** layer serves as the authoritative repository for stable, session-persistent knowledge that transcends individual conversations.

### What L2 Stores

- Verified file paths and directory structures
- Credentials and configuration values
- Environment facts confirmed as "always true"
- Accumulated operational knowledge from previous tasks

### File Location and Initialization

L2 data resides in [`memory/global_mem.txt`](https://github.com/lsdefine/GenericAgent/blob/main/memory/global_mem.txt). The file is created automatically during agent startup in [`agentmain.py`](https://github.com/lsdefine/GenericAgent/blob/main/agentmain.py) lines 20-24, ensuring the persistent storage exists before the first knowledge write.

### Update Mechanism

New facts enter L2 through the `file_patch` tool implemented in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) (lines 13-15). When the agent learns a verified global fact, this function appends it to [`global_mem.txt`](https://github.com/lsdefine/GenericAgent/blob/main/global_mem.txt) and automatically triggers an update to the L1 Insight Index, maintaining consistency between layers.

## Synchronization Between L1 and L2

The memory layers operate as a cohesive unit through automatic synchronization mechanisms. When L2 receives new content via `file_patch`, the system immediately updates the L1 Insight Index to reflect the new routing pointers.

The `do_start_long_term_update()` function orchestrates this coordination by:

1. Reading current memory states via `get_global_memory()`
2. Extracting insights worth preserving from the completed task
3. Writing verified facts to L2 ([`global_mem.txt`](https://github.com/lsdefine/GenericAgent/blob/main/global_mem.txt))
4. Updating the L1 index ([`global_mem_insight.txt`](https://github.com/lsdefine/GenericAgent/blob/main/global_mem_insight.txt)) with concise pointers

This bidirectional sync ensures that the fast-access L1 layer always accurately represents the contents of the authoritative L2 store.

## Practical Code Examples

Working with GenericAgent's memory layers involves specific file operations and function calls from [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py).

### Reading Current Memory State

```python
from ga import get_global_memory

# Retrieve concatenated L1 and L2 memory for prompt injection

current_memory = get_global_memory()
print("=== Injected Memory Context ===")
print(current_memory)

```

### Appending to L2 Global Facts

```python
from ga import file_patch

# Add a verified configuration fact to L2

path = "memory/global_mem.txt"
old_content = ""  # Empty for append operations

new_fact = "\nAPI_BASE_URL = https://api.example.com/v1\n"

result = file_patch(path, old_content, new_fact)
print(f"Updated L2 and synced L1: {result}")

```

### Manually Updating L1 Insight Index

```python
from ga import file_patch

# Add a routing insight to L1 for fast retrieval

insight_path = "memory/global_mem_insight.txt"
old_insight = ""
new_insight = "\n# Insight: user prefers Chinese language output\n"

file_patch(insight_path, old_insight, new_insight)

```

### Long-Term Update Workflow

When the agent completes a task, it invokes `do_start_long_term_update()` (defined in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) lines 9-16). This method builds a prompt containing `get_global_memory()`, queries the LLM to extract verified facts, then executes `file_patch` on both [`memory/global_mem.txt`](https://github.com/lsdefine/GenericAgent/blob/main/memory/global_mem.txt#L2) and [`memory/global_mem_insight.txt`](https://github.com/lsdefine/GenericAgent/blob/main/memory/global_mem_insight.txt#L1) to maintain synchronization.

## Summary

- **L1 Insight Index** ([`memory/global_mem_insight.txt`](https://github.com/lsdefine/GenericAgent/blob/main/memory/global_mem_insight.txt)) serves as a fast-access routing layer containing concise pointers to relevant skills and facts, read on every turn via `get_global_memory()` in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py).

- **L2 Global Facts** ([`memory/global_mem.txt`](https://github.com/lsdefine/GenericAgent/blob/main/memory/global_mem.txt)) acts as the persistent knowledge store for verified environment facts, initialized in [`agentmain.py`](https://github.com/lsdefine/GenericAgent/blob/main/agentmain.py) and updated through the `file_patch` tool.

- **Automatic Synchronization** occurs when `file_patch` updates L2, immediately refreshing the L1 index, while `do_start_long_term_update()` orchestrates batch updates across both layers after task completion.

- **Prompt Injection** combines both layers into every system prompt via `get_global_memory()` (lines 65-77 in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py)), ensuring the agent retains context without excessive token consumption.

## Frequently Asked Questions

### What is the difference between L1 Insight Index and L2 Global Facts?

The **L1 Insight Index** functions as a lightweight routing table containing single-line pointers that help the agent quickly locate relevant context without scanning its entire memory. The **L2 Global Facts** layer stores the actual stable knowledge—such as file paths, credentials, and verified environment details—that persists across sessions. While L1 optimizes for retrieval speed, L2 optimizes for data integrity and long-term persistence.

### How does GenericAgent decide when to update the memory layers?

GenericAgent triggers memory updates through the `do_start_long_term_update()` function in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) (lines 9-16) after completing a task. This method reads the current memory state via `get_global_memory()`, prompts the LLM to extract verified facts from the interaction, and then writes those facts to L2 while simultaneously updating the L1 index to reflect the new routing pointers.

### Where are the memory files physically stored?

Both memory layers persist as plain text files in the `memory/` directory. The **L2 Global Facts** reside in [`memory/global_mem.txt`](https://github.com/lsdefine/GenericAgent/blob/main/memory/global_mem.txt), while the **L1 Insight Index** is stored in [`memory/global_mem_insight.txt`](https://github.com/lsdefine/GenericAgent/blob/main/memory/global_mem_insight.txt). These files are created automatically during agent initialization in [`agentmain.py`](https://github.com/lsdefine/GenericAgent/blob/main/agentmain.py) (lines 20-24) if they do not already exist.

### Can I manually edit the L1 or L2 memory files?

Yes, you can manually edit both files, though you should maintain the synchronization between layers. If you manually add entries to [`memory/global_mem.txt`](https://github.com/lsdefine/GenericAgent/blob/main/memory/global_mem.txt#L2), you should also add corresponding routing pointers to [`memory/global_mem_insight.txt`](https://github.com/lsdefine/GenericAgent/blob/main/memory/global_mem_insight.txt#L1) to ensure the agent can efficiently retrieve the new facts. Alternatively, use the `file_patch` function from [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) to update L2, which automatically handles the L1 synchronization for you.