# eniline/agent_memory architecture

> Architecture diagram of the GitHub repository eniline/agent_memory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eniline/agent_memory
- Repository: https://github.com/eniline/agent_memory

## Overview

This is a long-term-memory conversational agent: it extracts dated facts from conversation sessions, embeds and indexes them, retrieves relevant memories for each question, and generates a concise answer. The evaluation workflow runs agents over QA sets, then uses an LLM judge and metrics; documented experiment branches compare baselines, model-effect features, and memory-writing granularities. The graph follows documented and indexed references; several experiment and evaluation implementations were not excerpted, so their internal links are limited to documented relationships.

Main entry points: [`agent/controller.py`](https://github.com/eniline/agent_memory/blob/main/agent/controller.py) (Memory agent), [`eval/llm_client.py`](https://github.com/eniline/agent_memory/blob/main/eval/llm_client.py) (LLM client), [`memory/retriever.py`](https://github.com/eniline/agent_memory/blob/main/memory/retriever.py) (Memory retrieval), [`experiments/model_effect/controller.py`](https://github.com/eniline/agent_memory/blob/main/experiments/model_effect/controller.py) (Model-effect agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent workflow"]
  node_agent_controller["Memory agent<br/>[controller.py]"]
  node_llm_client["LLM client<br/>[llm_client.py]"]
  node_answer["Generated answer<br/>[controller.py]"]
end

subgraph group_memory["Memory subsystem"]
  node_writer["Fact extraction<br/>[writer.py]"]
  node_store[("FAISS memory store<br/>[store.py]")]
  node_retriever["Memory retrieval<br/>[retriever.py]"]
  node_updater["Memory deduplication<br/>[updater.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_generation["Generation runner<br/>[run_generation.py]"]
  node_judge["LLM-as-Judge<br/>[run_judge.py]"]
  node_metrics["F1 and EM<br/>[metrics.py]"]
end

subgraph group_experiments["Experiments"]
  node_baselines["Agent baselines<br/>[baselines.py]"]
  node_model_effect["Model-effect agent<br/>[controller.py]"]
  node_reflector["Memory reflection<br/>[reflector.py]"]
  node_granularity["Write-granularity agents<br/>[per_session.py]"]
  node_segmenter["Topic segmentation<br/>[segmenter.py]"]
end

node_conversation["Conversation sessions"]
node_questions(("QA questions"))
node_embedding_model["Embedding model"]
node_ollama{{"Ollama generation"}}
node_embedding_service{{"Sentence embeddings"}}
node_deepseek{{"DeepSeek Judge API"}}

node_generation -->|"loads agent"| node_agent_controller
node_generation -->|"loads sessions"| node_conversation
node_generation -->|"runs questions"| node_questions
node_agent_controller -->|"extracts facts"| node_writer
node_writer -->|"requests extraction"| node_llm_client
node_llm_client -->|"calls generation"| node_ollama
node_agent_controller -->|"encodes facts"| node_embedding_model
node_embedding_model -->|"uses model"| node_embedding_service
node_agent_controller -->|"stores vectors"| node_store
node_agent_controller -->|"initializes retriever"| node_retriever
node_retriever -->|"encodes query"| node_embedding_model
node_retriever -->|"searches memories"| node_store
node_agent_controller -->|"retrieves memories"| node_retriever
node_agent_controller -->|"generates answer"| node_llm_client
node_llm_client -->|"returns response"| node_answer
node_agent_controller -->|"returns answer"| node_answer
node_generation -->|"evaluates results"| node_judge
node_judge -->|"requests judgments"| node_llm_client
node_llm_client -->|"calls judge API"| node_deepseek
node_judge -->|"computes metrics"| node_metrics
node_baselines -->|"uses client"| node_llm_client
node_model_effect -.->|"optionally reflects"| node_reflector
node_model_effect -->|"extracts facts"| node_writer
node_model_effect -->|"stores memories"| node_store
node_model_effect -->|"retrieves memories"| node_retriever
node_model_effect -->|"deduplicates memories"| node_updater
node_reflector -->|"requests reflection"| node_llm_client
node_granularity -->|"extracts by segment"| node_writer
node_granularity -->|"stores facts"| node_store
node_granularity -->|"retrieves memories"| node_retriever
node_granularity -->|"deduplicates memories"| node_updater
node_granularity -.->|"optionally segments topics"| node_segmenter

click node_generation "https://github.com/eniline/agent_memory/blob/main/eval/run_generation.py"
click node_agent_controller "https://github.com/eniline/agent_memory/blob/main/agent/controller.py"
click node_writer "https://github.com/eniline/agent_memory/blob/main/memory/writer.py"
click node_store "https://github.com/eniline/agent_memory/blob/main/memory/store.py"
click node_retriever "https://github.com/eniline/agent_memory/blob/main/memory/retriever.py"
click node_updater "https://github.com/eniline/agent_memory/blob/main/memory/updater.py"
click node_llm_client "https://github.com/eniline/agent_memory/blob/main/eval/llm_client.py"
click node_answer "https://github.com/eniline/agent_memory/blob/main/agent/controller.py"
click node_judge "https://github.com/eniline/agent_memory/blob/main/eval/run_judge.py"
click node_metrics "https://github.com/eniline/agent_memory/blob/main/eval/metrics.py"
click node_baselines "https://github.com/eniline/agent_memory/blob/main/experiments/baseline/baselines.py"
click node_model_effect "https://github.com/eniline/agent_memory/blob/main/experiments/model_effect/controller.py"
click node_reflector "https://github.com/eniline/agent_memory/blob/main/experiments/model_effect/reflector.py"
click node_granularity "https://github.com/eniline/agent_memory/blob/main/experiments/write_granularity/per_session.py"
click node_segmenter "https://github.com/eniline/agent_memory/blob/main/experiments/write_granularity/segmenter.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_controller,node_llm_client,node_answer toneBlue
class node_writer,node_store,node_retriever,node_updater toneAmber
class node_generation,node_judge,node_metrics,node_deepseek toneMint
class node_baselines,node_model_effect,node_reflector,node_granularity,node_segmenter toneRose
class node_conversation,node_questions,node_embedding_model,node_ollama,node_embedding_service toneIndigo
```

## Components

### Agent workflow

- [Memory agent](https://github.com/eniline/agent_memory/blob/main/agent/controller.py): `agent/controller.py`
- [LLM client](https://github.com/eniline/agent_memory/blob/main/eval/llm_client.py): `eval/llm_client.py`
- [Generated answer](https://github.com/eniline/agent_memory/blob/main/agent/controller.py): `agent/controller.py`

### Memory subsystem

- [Fact extraction](https://github.com/eniline/agent_memory/blob/main/memory/writer.py): `memory/writer.py`
- [FAISS memory store](https://github.com/eniline/agent_memory/blob/main/memory/store.py): `memory/store.py`
- [Memory retrieval](https://github.com/eniline/agent_memory/blob/main/memory/retriever.py): `memory/retriever.py`
- [Memory deduplication](https://github.com/eniline/agent_memory/blob/main/memory/updater.py): `memory/updater.py`

### Evaluation

- [Generation runner](https://github.com/eniline/agent_memory/blob/main/eval/run_generation.py): `eval/run_generation.py`
- [LLM-as-Judge](https://github.com/eniline/agent_memory/blob/main/eval/run_judge.py): `eval/run_judge.py`
- [F1 and EM](https://github.com/eniline/agent_memory/blob/main/eval/metrics.py): `eval/metrics.py`

### Experiments

- [Agent baselines](https://github.com/eniline/agent_memory/blob/main/experiments/baseline/baselines.py): `experiments/baseline/baselines.py`
- [Model-effect agent](https://github.com/eniline/agent_memory/blob/main/experiments/model_effect/controller.py): `experiments/model_effect/controller.py`
- [Memory reflection](https://github.com/eniline/agent_memory/blob/main/experiments/model_effect/reflector.py): `experiments/model_effect/reflector.py`
- [Write-granularity agents](https://github.com/eniline/agent_memory/blob/main/experiments/write_granularity/per_session.py): `experiments/write_granularity/per_session.py`
- [Topic segmentation](https://github.com/eniline/agent_memory/blob/main/experiments/write_granularity/segmenter.py): `experiments/write_granularity/segmenter.py`

### Other components

- **Conversation sessions**
- **QA questions**
- **Embedding model**
- **Ollama generation**
- **Sentence embeddings**
- **DeepSeek Judge API**

## Connections

- Generation runner → Memory agent: loads agent (evidence: `README.md`)
- Generation runner → Conversation sessions: loads sessions (evidence: `README.md`)
- Generation runner → QA questions: runs questions (evidence: `README.md`)
- Memory agent → Fact extraction: extracts facts (evidence: `agent/controller.py`)
- Fact extraction → LLM client: requests extraction (evidence: `memory/writer.py`)
- LLM client → Ollama generation: calls generation (evidence: `eval/llm_client.py`)
- Memory agent → Embedding model: encodes facts (evidence: `agent/controller.py`)
- Embedding model → Sentence embeddings: uses model (evidence: `README.md`)
- Memory agent → FAISS memory store: stores vectors (evidence: `agent/controller.py`)
- Memory agent → Memory retrieval: initializes retriever (evidence: `agent/controller.py`)
- Memory retrieval → Embedding model: encodes query (evidence: `memory/retriever.py`)
- Memory retrieval → FAISS memory store: searches memories (evidence: `memory/retriever.py`)
- Memory agent → Memory retrieval: retrieves memories (evidence: `agent/controller.py`)
- Memory agent → LLM client: generates answer (evidence: `agent/controller.py`)
- LLM client → Generated answer: returns response (evidence: `agent/controller.py`)
- Memory agent → Generated answer: returns answer (evidence: `agent/controller.py`)
- Generation runner → LLM-as-Judge: evaluates results (evidence: `README.md`)
- LLM-as-Judge → LLM client: requests judgments (evidence: `eval/run_judge.py`)
- LLM client → DeepSeek Judge API: calls judge API (evidence: `eval/llm_client.py`)
- LLM-as-Judge → F1 and EM: computes metrics (evidence: `eval/run_judge.py`)
- Agent baselines → LLM client: uses client (evidence: `experiments/baseline/baselines.py`)
- Model-effect agent → Memory reflection: optionally reflects (evidence: `experiments/model_effect/controller.py`)
- Model-effect agent → Fact extraction: extracts facts (evidence: `experiments/model_effect/controller.py`)
- Model-effect agent → FAISS memory store: stores memories (evidence: `experiments/model_effect/controller.py`)
- Model-effect agent → Memory retrieval: retrieves memories (evidence: `experiments/model_effect/controller.py`)
- Model-effect agent → Memory deduplication: deduplicates memories (evidence: `experiments/model_effect/controller.py`)
- Memory reflection → LLM client: requests reflection (evidence: `experiments/model_effect/reflector.py`)
- Write-granularity agents → Fact extraction: extracts by segment (evidence: `experiments/write_granularity/per_session.py`)
- Write-granularity agents → FAISS memory store: stores facts (evidence: `experiments/write_granularity/per_session.py`)
- Write-granularity agents → Memory retrieval: retrieves memories (evidence: `experiments/write_granularity/per_session.py`)
- Write-granularity agents → Memory deduplication: deduplicates memories (evidence: `experiments/write_granularity/per_session.py`)
- Write-granularity agents → Topic segmentation: optionally segments topics (evidence: `README.md`)
