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

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.

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. In 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 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. The file is created automatically during agent startup in 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 (lines 13-15). When the agent learns a verified global fact, this function appends it to 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)
4. Updating the L1 index (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.

Reading Current Memory State

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

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

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 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 and memory/global_mem_insight.txt to maintain synchronization.

Summary

• L1 Insight Index (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.

• L2 Global Facts (memory/global_mem.txt) acts as the persistent knowledge store for verified environment facts, initialized in 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), 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 (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, while the L1 Insight Index is stored in memory/global_mem_insight.txt. These files are created automatically during agent initialization in 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, you should also add corresponding routing pointers to memory/global_mem_insight.txt to ensure the agent can efficiently retrieve the new facts. Alternatively, use the file_patch function from ga.py to update L2, which automatically handles the L1 synchronization for you.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}