AI agent long-term memory: a practical tutorial with Cognee and Regolo

By providing autonomous coding agents with persistent institutional recall, multi-hop architectural graph traversal, and live test-driven self-healing on European sovereign infrastructure, we can eliminate repetitive codebase errors across development cycles.

---

The context amnesia trap in autonomous coding

Autonomous software engineering agents frequently exhibit severe context amnesia across independent terminal sessions, losing track of historical pull requests, continuous integration failures, and established repository standards.

When developers boot up a terminal session with Claude Code, Cursor, or an open-source agent harness, they commonly assign it a complex refactoring task on a multi-tenant API. The agent inspects the immediate file, writes an initial patch, encounters a syntax error in the continuous integration pipeline, reads the traceback, and successfully fixes the issue before merging the pull request. However, when a different developer asks the same agent harness two weeks later to add a sibling endpoint in that exact module, the model repeats the identical security mistake it resolved fourteen days earlier.

We term this fundamental limitation the Context Amnesia Trap, where contemporary large language models evaluate incoming user prompts inside completely isolated, ephemeral context windows. Once a development session terminates, the operational lessons, architectural decisions, and continuous integration triage insights vanish completely because the agent runtime lacks an episodic storage engine.

Standard Stateless Agent:
Session 1 (Day 1)  ──► Introduces CWE-89 SQL Injection ──► CI Fails #89 ──► PR #142 Merged Fix
Session 2 (Day 15) ──► Fresh Context Window ──────────► Re-introduces Same CWE-89 SQL Injection!Code language: Bash (bash)

This phenomenon does not stem from a deficiency in raw model intelligence, but rather represents an architectural omission in the surrounding agent execution harness. When software engineering teams operate in enterprise environments, code is never authored in a vacuum, but lives alongside Architectural Decision Records (ADRs), pull request reviews, regression histories, and strict data isolation policies. If an autonomous agent cannot query the historical rationale behind a repository, it remains an autocomplete engine operating with unwarranted confidence.

---

Why traditional chunk RAG fails enterprise codebases

When engineering teams attempt to resolve agent memory limitations, their initial approach almost always involves bolting on a traditional Retrieval-Augmented Generation (RAG) pipeline based on text chunking.

In these conventional pipelines, teams split Python files, markdown documentation, and pull request transcripts into arbitrary 512-token text chunks, compute dense embeddings, store the vectors in a database, and execute cosine similarity lookups during prompt assembly. This approach deteriorates rapidly because standard chunk-based retrieval treats every document fragment as an isolated lexical island, calculating mathematical proximity between keywords rather than structural relationships between software engineering concepts.

What happens when a developer requests an agent to implement a user search endpoint with strict tenant isolation?

A traditional vector search scans the database and retrieves an outdated utility function containing an unparameterized database query simply because its lexical similarity scored high.

The vector database has no mechanism to recognize that ADR-001 mandated session-level tenant extraction, that ADR-003 superseded all dynamic string queries across the repository, or that PR-142 resolved vulnerability CWE-89 after CI Run #89 broke staging.

❌ Naive Chunk RAG:
Query: "Search Users" ──► Cosine Lookup ──► Retrieves Outdated 2024 Snippet ──► Generates Vulnerable SQL

✅ Cognee Cognitive Graph:
Query: "Search Users" ──► Graph Walk ──► ADR-001 (Tenants) ──► ADR-003 (Parameterized) ──► Secure AST PatchCode language: Bash (bash)

Chunk-based retrieval mechanisms completely lack causality, making them incapable of traversing directional dependency trails from an incident to a fix and onward to an architectural policy. To construct autonomous agents capable of sustained multi-session software maintenance, we must replace isolated text chunks with a connected topological knowledge graph that preserves historical relationships.

---

The cognitive memory architecture: graphs, vectors, and sovereign inference

The architectural framework presented in this repository merges Cognee, an open-source knowledge graph and vector indexing engine, with Regolo API, an enterprise European sovereign AI cloud operating under strict Zero Data Retention guarantees.

Instead of treating codebase context as flat unstructured text, our memory layer organizes repository history into five distinct entity categories:

• Architectural Decision Records (ADRs): binding architectural rules governing repository structure, such as ADR-001 for tenant isolation and ADR-003 for parameterized SQLAlchemy statements.
• Pull Requests (PRs): historical repository modifications containing reviewed code diffs, author comments, and contextual discussion metadata that illustrate the rationale behind previous codebase revisions.
• CI Failures: Specific pipeline errors, process exit codes, and execution tracebacks recorded during previous continuous integration build runs across various testing environments.
• Coding Conventions: standardized repository rules such as mandatory asynchronous route declarations, strict typing constraints, and Pydantic schema validation models across all endpoint definitions.
• Resolved Vulnerabilities: common Weakness Enumeration (CWE) security records documenting previous vulnerability patches, remediation strategies, and compliance verification checkpoints across the codebase.

These entity nodes are interconnected through typed directional edges including TRIGGERED_BY, FIXES_CI_FAILURE, IMPLEMENTS_DECISION, ENFORCES_CONVENTION, and VERIFIED_BY to preserve full multi-hop causality throughout memory queries.

When an agent receives an engineering task, it executes a multi-hop graph traversal that systematically navigates connected nodes rather than relying on shallow keyword matching:

1. In the first traversal hop, the target search endpoint requires secure tenant handling to ensure multi-tenant isolation across all active database queries.
2. Next, the graph resolves ADR-001 to identify the mandatory session token utility required for multi-tenant context extraction from cryptographically verified headers.
3. The graph then traverses related security nodes and uncovers ADR-003, which strictly forbids dynamic string formatting in database handlers.
4. Finally, the graph examines PR-142 to inspect the precedent patch that successfully satisfied both architectural constraints during previous development iterations.

Under the hood, graph relationships are maintained in memory via NetworkX and backed by PostgreSQL with pgvector, with dense vector representations calculated using Qwen3-Embedding-8B producing 4096-dimensional vectors that are subsequently refined through Qwen3-Reranker-4B.

Every inference call and embedding generation executes on Regolo infrastructure located entirely within the European Union, guaranteeing that all prompt payloads, code structures, and generated completions are processed exclusively in volatile memory under Regolo’s Zero Data Retention (ZDR) policy.

Because no proprietary code is written to server-side disks or retained for model training, enterprises operating under strict GDPR compliance and intellectual property constraints can deploy autonomous agents with total data sovereignty.

---

Dynamic semantic routing with Brick Complexity Pro

Hardcoding specific large language models in environment configuration files creates a rigid and brittle architecture that struggles to adapt to varying engineering challenges.

In conventional setups, developers assign static environment variables where one model handles extraction, another handles code synthesis, and a third handles reasoning, forcing manual pipeline updates whenever task difficulty shifts between minor documentation edits and complex multi-file refactoring. To eliminate configuration drift and optimize compute allocation, our project implements dynamic semantic routing powered by Regolo’s Brick Complexity Pro (brick-complexity-pro).

Agent Task Payload
       │
       ▼
┌────────────────────────────────────────-┐
│  Brick Semantic Router (Score 1.0-10.0) │
└──────┬──────────────────┬──────────────┬┘
       │ < 4.0            │ 4.0 - 7.4    │ >= 7.5
       ▼                  ▼              ▼
┌──────────────┐  ┌───────────────┐  ┌───────────────┐
│ gpt-oss-20b  │  │qwen3-coder-   │  │ glm-5.2       │
│ (Fast Entity │  │next (Syntax & │  │ (Frontier     │
│  Extraction) │  │  AST Coding)  │  │  Reasoning)   │
└──────────────┘  └───────────────┘  └───────────────┘Code language: Bash (bash)

When an agent receives an engineering objective, brick-complexity-pro evaluates the context window, prompt density, and task difficulty, dynamically assigning a complexity score on a scale from 1.0 to 10.0:

• Economic Tier (Score < 4.0): Routed to gpt-oss-20b, delivering an ultra-fast average latency of approximately 0.28 seconds for entity extraction, JSON schema generation, and graph edge validation.
• Specialized Coding Tier (Score 4.0 – 7.4): Routed to qwen3-coder-next, utilizing a 262,144-token context window to synthesize AST-compliant Python code, FastAPI endpoints, and SQLAlchemy queries.
• Frontier Reasoning Tier (Score ≥ 7.5): Routed to qwen3.5-122b for deep multi-hop causal reasoning, architectural conflict resolution, and security verification, with a mandatory max_tokens allocation of at least 800 tokens to ensure the reasoning process does not exhaust the generation buffer before producing final text.
• Interactive Dialogue: Routed to Llama-3.3-70B-Instruct for natural, context-aware conversational interactions with developers throughout interactive terminal sessions and status reviews.

Because the meta-router dynamically evaluates each sub-task in real time, the repository .env file requires only MODEL_BRICK_ROUTER=brick-complexity-pro, allowing the agent loop to autonomously allocate compute resources without manual intervention.

---

The 5-stage ReAct self-healing cycle

True agent autonomy requires an active verification loop, because generating software patches without executing automated tests is fundamentally equivalent to guessing.

The core execution engine in core/agent_loop.py executes an active ReAct (Reasoning + Acting) cycle that connects the Cognee memory graph directly to file system operations, static AST analysis, and isolated subprocess test runners.

┌────────────────────────────────────────────────────────────────────────┐
│                   5-Stage ReAct Self-Healing Engine                    │
├──────────────────┬──────────────────┬──────────────────┬───────────────┤
│ 1. Recall        │ 2. Inspect       │ 3. Synthesize    │ 4. Verify     │
│ Cognee Graph     │ Target Code      │ Dynamic Patch    │ Subprocess    │
│ (ADRs & History) │ (AST & Schema)   │ (Brick Routing)  │ Live Pytest   │
└────────┬─────────┴────────┬─────────┴────────┬─────────┴───────┬───────┘
         │                  │                  │                 │
         └──────────────────┴────────┬─────────┴─────────────────┘
                                     │
                     5. Codify & Persist Outcome Node
                     (Linked to ADR-001 & ADR-003)Code language: Bash (bash)

The autonomous execution loop systematically processes five sequential stages during each engineering assignment to ensure complete architectural compliance and code correctness:

1. Memory Recall (recall_memory): The incoming task objective triggers a topological search across the Cognee graph, extracting relevant ADR nodes, convention rules, and precedent pull request histories.
2. Codebase Inspection (read_file): The agent reads target source files and shared utilities, analyzing existing function definitions, import dependencies, and database schemas.
3. Patch Synthesis (write_code_patch): The combined prompt context is processed through Regolo’s brick-complexity-pro, generating compliant Python code that adheres to all recalled architectural constraints.
4. Live Subprocess Verification (run_pytest): The engine spawns an isolated pytest subprocess against the repository test suite, capturing standard output, process return codes, and exact traceback strings.
5. Memory Codification (record_session_outcome): If all tests pass with 100% green status, a new SessionOutcome node is codified into the graph and linked to the corresponding ADRs, whereas if tests fail, the engine captures the traceback and triggers an immediate self-healing cycle.

---

Prerequisites and environment setup

Before deploying the framework on your development machine, verify that your environment satisfies these baseline operational prerequisites:

• Operating System: Linux, macOS, or Windows via WSL2 environments
• Python: Version 3.10 or higher (the codebase is fully verified across Python 3.10 through 3.14)
• Docker and Docker Compose: Optional for running local PostgreSQL/pgvector and Cognee containers, as the framework operates in standalone local mode if Docker is absent
• Regolo API Key: An active OpenAI-compatible API key provisioned through the official portal at dashboard.regolo.ai

1. Clone the repository and initialize the virtual environment

Clone the repository from GitHub and establish an isolated virtual environment on your local system:

git clone https://github.com/regolo-ai/cognee-agent-memory.git
cd cognee-agent-memory
python3 -m venv .venv
source .venv/bin/activateCode language: Bash (bash)

(On Windows PowerShell systems, activate the virtual environment using .venv\Scripts\Activate.ps1)

2. Install project dependencies

Install all required Python packages including Rich, Cognee, NetworkX, and the pytest automation harness:

pip install -r requirements.txtCode language: Bash (bash)

3. Configure environment variables

Duplicate the template environment configuration file to establish your local runtime settings:

cp .env.example .envCode language: Bash (bash)

Open .env in your preferred editor to configure your Regolo API credentials and confirm the dynamic router settings:

# Regolo params
REGOLO_API_KEY=your_regolo_api_key_here
REGOLO_BASE_URL=https://api.regolo.ai/v1

# Brick Semantic Router
MODEL_BRICK_ROUTER=brick-complexity-pro

# Embeddings and Reranker
MODEL_EMBEDDING=Qwen3-Embedding-8B
MODEL_RERANKER=Qwen3-Reranker-4B

# Memory Policies
MAX_GRAPH_HOPS=3
SIMILARITY_THRESHOLD=0.75Code language: Bash (bash)

---

Step-by-step tutorial: running the CLI and terminal UI

Our framework provides two operational interfaces: an interactive Terminal User Interface (TUI) rendered in Regolo Sovereign Green (#00FF66), and a comprehensive suite of headless CLI flags designed for continuous integration workflows.

We can launch the interactive terminal interface at any time by executing the provided shell script:

./run.shCode language: Bash (bash)

Alternatively, we can invoke the Python application directly from the command line:

python3 main.pyCode language: Bash (bash)

┌───────────────────────────────────────────────────────────┐
│         REGOLO + COGNEE • COGNITIVE MEMORY ENGINE         │
├───────────────────────────────────────────────────────────┤
│ [1] Setup Environment & Diagnostic Validation             │
│ [2] Manage Docker Services (PostgreSQL & Cognee)          │
│ [3] Run ReAct Self-Healing Agent Loop (Live Pytest)       │
│ [4] Multi-Session Timeline Demo (Day 1 -> Day 15)         │
│ [5] Head-to-Head A/B Benchmark (Naive RAG vs Cognee)      │
│ [6] Scan, Index & Recall Custom Codebase Path             │
│ [7] Launch 2D Knowledge Graph Web Visualizer              │
│ [8] Generate Claude Code & OpenClaw MCP Plugins           │
│ [0] Exit                                                  │
└───────────────────────────────────────────────────────────┘Code language: Bash (bash)

---

1. Environment verification and diagnostics

For interactive terminal execution, select menu option [1] within the Rich interface, or execute the following automated diagnostic command directly in your shell environment:

python3 main.py --setupCode language: Bash (bash)

The diagnostic utility performs automated healthchecks across local dependencies and validates our API key against Regolo’s sovereign cloud infrastructure.

---

2. Background Docker infrastructure management

For interactive terminal execution, select menu option [2] within the Rich interface, or execute the corresponding background management commands directly from your shell environment:

# Start background services
python3 main.py --services start

# Inspect service health and dynamic port allocations
python3 main.py --services status

# Stop background services
python3 main.py --services stopCode language: Bash (bash)

The service manager incorporates automated port conflict discovery, ensuring that if ports 5432 or 8800 are bound by existing host applications, the manager increments to the next available system port.

---

3. Running the autonomous ReAct self-healing loop

For interactive terminal execution, select menu option [3] within the Rich interface, or execute the headless ReAct self-healing demonstration directly from your shell environment:

python3 main.py --react-demoCode language: Bash (bash)

During execution, our team can observe the full five-stage autonomous engineering cycle operating in real time:

1. First, the agent executes recall_memory against the Cognee engine and retrieves ADR-001 and ADR-003 to establish the necessary architectural boundaries.
2. Next, the agent inspects sample_repo/src/api/users.py and sample_repo/src/core/context.py to analyze existing database models, helper functions, and endpoint schemas before generating code.
3. Following code inspection, brick-complexity-pro evaluates prompt difficulty and routes code synthesis to the specialized qwen3-coder-next model on Regolo.
4. Once the code patch is written, an isolated pytest sample_repo/tests/test_users.py subprocess executes against the repository test suite to verify full compliance.
5. Because all test assertions pass with one hundred percent green status, the verified outcome node is codified permanently into the knowledge graph.

---

4. Simulating cross-week learning with the multi-session timeline

For interactive terminal execution, select menu option [4] within the Rich interface, or execute the multi-session timeline demonstration directly from your shell environment:

python3 main.py --timeline-demoCode language: Bash (bash)

================================================================================
MULTI-SESSION CONTINUOUS LEARNING TIMELINE
================================================================================
Day 1 (Session 1): Memoryless Agent
└── Concatenates raw f-strings in SQL
└── Outcome: CI Run #89 Fails (SQLSyntaxError + CWE-89 Vulnerability)

Day 2 (Session 2): Institutional Codification
└── PR #142 merged with fix
└── ADR-003 codified: Mandatory Parameterized Queries
└── Graph Edge: (PR-142) ──FIXES──► (CI-FAIL-89) ──CAUSED_BY──► (ADR-003)

Day 15 (Session 3): Architectural Recall
└── Agent receives a new feature request touching the search module
├── Naive Chunk RAG Agent: Retrieves raw chunk ──► Repeats Day 1 SQL Injection
└── Cognee Memory Agent: Traverses ADR-003 ─────► 100% Green Build on First Try!
================================================================================Code language: Bash (bash)

---

5. Executing the head-to-head A/B benchmark

For interactive terminal execution, select menu option [5] within the Rich interface, or execute the comparative benchmark directly from your shell environment:

python3 main.py --demoCode language: Bash (bash)

The benchmark runner executes both agents concurrently, auditing their generated code against AST policies, security rules, and real test suites to measure performance deltas.

Evaluation Metric	Naive Chunk RAG Agent	Cognee Memory Agent (agent_loop.py)	Measured Delta
ADR Architectural Compliance	0%	100%	+100% Policy Adherence
Static Security Score	25 / 100	100 / 100	+75 Points
Test Suite Pass Rate	❌ Failed	✅ Passed (100%)	Clean CI Build
CWE-89 (SQL Injection) Risk	❌ Vulnerable	✅ Prevented	Zero Injection
CWE-639 (IDOR) Risk	❌ Client Parameter	✅ Session Context	Isolated Context
Inference Routing Cost	Static Monolithic	Dynamic (brick-complexity-pro)	~60% Token Savings

---

6. Indexing and recalling from custom local codebases

For interactive terminal execution, select menu option [6] within the Rich interface, or execute the repository indexing and natural language recall commands directly from your shell environment:

To parse, extract entities, and construct a knowledge graph index for an external project directory:

python3 main.py --cognify /path/to/your/custom_projectCode language: Bash (bash)

To perform semantic, causal natural-language recall over the newly constructed graph:

python3 main.py --recall "How is authentication and tenant isolation structured?"Code language: Bash (bash)

To generate a structured JSON topological summary of the current graph state:

python3 main.py --graph-summaryCode language: Bash (bash)

---

7. Launching the interactive 2D knowledge graph visualizer

For interactive terminal execution, select menu option [7] within the Rich interface, or launch the web visualizer directly from your shell environment:

python3 main.py --view-graphCode language: Bash (bash)

======================================================================
⚡ REGOLO + COGNEE • KNOWLEDGE GRAPH LIVE SERVER
======================================================================
📁 Serving File:      data/knowledge_graph_visualizer.html
🌐 Local Web URL:     http://127.0.0.1:8850/
🛑 Terminate Server:  Press CTRL+C to stop
======================================================================Code language: Bash (bash)

We open http://127.0.0.1:8850/ in any standard web browser to explore the interactive visual interface.

┌────────────────────────────────────────────────────────────────────────┐
│  2D Physics Graph Visualizer (Vis.js Network)                          │
│                                                                        │
│   (ADR-001) ──[ENFORCES]──► (CONV-01)                                  │
│       ▲                                                                │
│       │ IMPLEMENTS                                                     │
│   (PR-142) ──[FIXES]──► (CI-FAIL-89) ◄──[TRIGGERED_BY]── (VULN-CWE-89) │
│       │                                                                │
│       ▼ ENFORCES                                                       │
│   (ADR-003)                                                            │
│                                                                        │
│  [Dark Mode] [Cluster Zoom] [Neighbor Isolation] [Export Graph JSON]   │
└────────────────────────────────────────────────────────────────────────┘Code language: Bash (bash)

The browser visualizer provides comprehensive exploration capabilities:

• Color-Coded Nodes: Green for ADRs, Red for CI failures, Blue for Pull Requests, Yellow for Conventions, and Purple for Security Vulnerabilities.
• 2D Physics Simulation: Real-time force-directed node repulsion, dynamic edge tension, and interactive drag-and-drop manipulation powered by the browser-accelerated Vis.js Network canvas rendering engine.
• Node Inspector Panel: Selecting any node displays its complete markdown specification, associated metadata tags, and connected relational edges.
• Interactive Exploration Tools: Filter by entity category, execute keyword searches, isolate connected neighbor clusters, and step through causal sequences.

---

Connecting long-term memory to Claude Code and OpenClaw via MCP

We do not need to rewrite our daily development workflows to benefit from cognitive graph memory, because the repository includes native connectors for the Model Context Protocol (MCP).

┌───────────────────────────────────────────────────────────────┐
│                 Developer IDE / Terminal CLI                  │
│               (Claude Code / OpenClaw Runner)                 │
└───────────────────────────────┬───────────────────────────────┘
                                │ Stdio MCP Protocol
                                ▼
┌───────────────────────────────────────────────────────────────┐
│             Cognee MCP Server (plugins/mcp_server.py)         │
├───────────────────────────────┬───────────────────────────────┤
│ • cognee_recall(query)        │ • cognee_cognify(path)        │
│ • cognee_record_pr(diff, adr) │ • cognee_graph_summary()      │
└───────────────────────────────┴───────────────────────────────┘Code language: Bash (bash)

1. Generating configuration files

For interactive terminal execution, select menu option [8] within the Rich interface to generate the required MCP integration files automatically.

The configuration for Claude Code is stored at plugins/claude_code_mcp.json:

{
  "mcpServers": {
    "regolo-cognee-memory": {
      "command": "python3",
      "args": ["plugins/mcp_server.py"],
      "env": {
        "REGOLO_API_KEY": "your_regolo_api_key_here",
        "REGOLO_BASE_URL": "https://api.regolo.ai/v1"
      }
    }
  }
}Code language: JSON / JSON with Comments (json)

For OpenClaw users, the corresponding plugin definition is maintained in plugins/openclaw_plugin.json.

2. Attaching the MCP server to Claude Code

We can register the memory server with Claude Code by executing a single registration command:

claude mcp add regolo-cognee-memory python3 /absolute/path/to/plugins/mcp_server.pyCode language: Bash (bash)

3. Establishing the memory protocol

By placing the instructions from plugins/CLAUDE.md in our target repository root, Claude Code automatically leverages three native memory tools during routine coding:

• The cognee_recall(query) tool is invoked before generating new endpoints or refactoring architectural code to retrieve relevant architectural decision records and precedent pull requests.
• The cognee_cognify(path) tool is invoked after merging substantial pull requests to re-index repository documentation and update topological entity relationships.
• The cognee_record_pr(pr_id, description, linked_adrs) tool is invoked upon pull request completion to codify verified outcomes into organizational memory.

---

Github Codes

You can download the codes on our Github repo, just download and follow the README steps. If need help you can always reach out our team on Discord 🤙

---

FAQ

How does a knowledge graph memory differ from standard vector databases?

Vector databases store isolated document chunks as numerical embeddings and retrieve them based on lexical similarity, but they have no intrinsic concept of relationships between documents. A knowledge graph stores entities such as ADRs, CI failures, and pull requests as nodes connected by typed directional relationships like TRIGGERED_BY and FIXES_CI_FAILURE, enabling agents to perform multi-hop causal reasoning across historical events.

Why is Zero Data Retention critical for enterprise agent memory?

Enterprise software repositories contain proprietary algorithms, internal security rules, and sensitive compliance policies that cannot be exposed to external retention risks. When using cloud-hosted LLM providers that retain prompt inputs for retraining or debugging, organizations risk intellectual property leakage and regulatory non-compliance, whereas Regolo processes all inference in volatile memory with zero server-side retention.

Can this framework be used without running local Docker containers?

Yes, because if Docker is not available on the host machine, the framework operates in standalone local mode, storing the graph in memory via NetworkX and persisting serialized snapshots to local JSON data stores under the data/ directory.

How does Brick Complexity Pro prevent configuration drift?

Instead of hardcoding model names for extraction, coding, and reasoning stages in environment files, tasks are evaluated dynamically on a 1.0 to 10.0 scale by brick-complexity-pro, allowing the router to autonomously assign sub-tasks to the optimal open-weight model on Regolo without requiring manual configuration updates when model lineups evolve.

What is the maximum number of graph hops recommended during recall?

The default configuration sets MAX_GRAPH_HOPS=3, because in software engineering graphs, traversing beyond three hops often introduces tangential entities with diminishing architectural relevance, whereas a three-hop traversal reliably captures the primary ADR, its parent convention, related CI incidents, and the precedent pull request fix.

---