# microsoft/mnemis architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/mnemis
- Repository: https://github.com/microsoft/mnemis

## Overview

1. **Repository role**
   This is a research/reproduction repo for the paper *Mnemis: Dual-Route Retrieval on Hierarchical Graphs for Long-Term LLM Memory*. It is not a full end-to-end product; it mainly packages the paper narrative, the global-selection implementation, and saved evaluation artifacts.

2. **Top-level structure**
   The repo splits into three meaningful areas:
   - `global_selection/`: the only source-code module shown here
   - `results/`: benchmark outputs and generated memory contexts
   - `figures/` plus `README.md` / `Mnemis_paper.pdf`: documentation and paper assets

3. **Core architectural idea**
   Mnemis combines two retrieval routes:
   - **System-1 similarity search** over a base graph
   - **System-2 global selection** over a hierarchical graph
   The repository only exposes the latter directly; the base graph and much of the memory pipeline are described as being built on top of **Graphiti**.

4. **`global_selection` subsystem**
   This module is the algorithmic heart of the repo. It contains:
   - `global_selector.py`: the retrieval/selection logic
   - `prompts.py`: the prompt templates used by the selection step
   This suggests the global-selection route is implemented as an LLM-guided decision process rather than a purely symbolic graph traversal.

5. **Prompt-driven control boundary**
   `prompts.py` is an important architectural boundary because it separates the policy layer from the selector logic. In this design, the selector likely prepares graph context and delegates reasoning to the LLM using task-specific prompts that encode the paper’s hierarchical selection strategy.

6. **Graph-based memory model**
   The paper describes two graph layers:
   - a **base graph** for local semantic recall
   - a **hierarchical graph** for top-down abstraction and coverage-oriented selection
   That means the real system boundary is between graph construction/retrieval and downstream memory answering. The repo documents this structure, but the actual graph-building pipeline is mostly outside the visible code tree.

7. **External dependency and runtime context**
   The README states the implementation is based on **Graphiti**. Architecturally, that implies Mnemis extends an external graph-memory framework rather than implementing the full memory backend from scratch. The visible repo content is therefore best understood as an overlay: prompts and global-selection logic layered on Graphiti-managed memory structures.

8. **Evaluation artifacts**
   The `results/` directory contains saved JSON outputs for two benchmarks:
   - `locomo`
   - `lme-s` / LongMemEval-S
   Each benchmark includes both `results_*.json` and `metrics_*.json`, indicating a clear separation between generated answer/context traces and computed evaluation metrics.

9. **Data flow through the repo**
   The likely flow is:
   memory/graph construction in Graphiti → retrieval candidates from the base graph → hierarchical/global selection via `global_selection` prompts and logic → final memory context or answer generation → benchmark metrics saved under `results/`
   The repository does not appear to store a live service or database; it stores offline experiment outputs.

10. **Documentation and paper assets**
   `README.md` and `Mnemis_paper.pdf` carry the main architectural explanation, benchmarks, and case studies. The `figures/` directory contains the paper diagrams used to explain the hierarchy and results, which are useful for diagramming the system even when the codebase is minimal.

11. **What is and is not implemented here**
   Implemented in this repo: the global-selection component, prompt definitions, and reproduction artifacts.
   Not visible here: a full ingestion pipeline, persistence layer, API/server, or the complete Graphiti-based memory backend. So any architecture diagram should show those as external or upstream components, not as local modules.

12. **Best way to diagram it**
   A faithful diagram should emphasize:
   - LLM prompts as a control layer
   - global selection as a separate reasoning route
   - graph memory as the underlying data model
   - benchmark outputs as offline experiment artifacts
   - Graphiti as the external base system the repo builds upon

Main entry points: [`global_selection/global_selector.py`](https://github.com/microsoft/mnemis/blob/main/global_selection/global_selector.py) (Selector), [`README.md`](https://github.com/microsoft/mnemis/blob/main/README.md) (README), [`Mnemis_paper.pdf`](https://github.com/microsoft/mnemis/blob/main/Mnemis_paper.pdf) (Paper), [`results/locomo`](https://github.com/microsoft/mnemis/tree/main/results/locomo) (LoCoMo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Docs & paper"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_paper["Paper<br/>[Mnemis_paper.pdf]"]
  node_figures["Figures"]
end

subgraph group_core["Selection core"]
  node_selector["Selector<br/>retrieval logic<br/>[global_selector.py]"]
  node_prompts["Prompts<br/>prompt templates<br/>[prompts.py]"]
  node_system1(("System 1<br/>local similarity"))
  node_system2(("System 2<br/>global selection"))
  node_basegraph{{"Base graph<br/>memory graph"}}
  node_hgraph{{"Hier graph<br/>hierarchical graph"}}
end

subgraph group_eval["Evaluation artifacts"]
  node_locomo[("LoCoMo<br/>benchmark")]
  node_lmes[("LME-S<br/>benchmark")]
  node_locomo_results["LoCoMo results<br/>run outputs"]
  node_locomo_metrics["LoCoMo metrics<br/>eval metrics"]
  node_lmes_results["LME-S results<br/>run outputs"]
  node_lmes_metrics["LME-S metrics<br/>eval metrics"]
end

subgraph group_ext["External runtime"]
  node_graphiti["Graphiti<br/>external framework"]
end

node_readme -->|"describes"| node_selector
node_readme -.->|"builds on"| node_graphiti
node_paper -->|"defines"| node_system1
node_paper -->|"defines"| node_system2
node_figures -.->|"illustrates"| node_hgraph
node_graphiti -.->|"provides"| node_basegraph
node_graphiti -.->|"supports"| node_hgraph
node_basegraph -->|"feeds"| node_system1
node_hgraph -->|"feeds"| node_system2
node_system1 -->|"candidates"| node_selector
node_selector -->|"uses"| node_prompts
node_prompts -->|"guides"| node_system2
node_selector -.->|"produces"| node_lmes_results
node_selector -.->|"produces"| node_locomo_results
node_locomo -->|"contains"| node_locomo_results
node_locomo -->|"contains"| node_locomo_metrics
node_lmes -->|"contains"| node_lmes_results
node_lmes -->|"contains"| node_lmes_metrics
node_system2 -.->|"evaluated by"| node_locomo_metrics
node_system2 -.->|"evaluated by"| node_lmes_metrics

click node_readme "https://github.com/microsoft/mnemis/blob/main/README.md"
click node_paper "https://github.com/microsoft/mnemis/blob/main/Mnemis_paper.pdf"
click node_figures "https://github.com/microsoft/mnemis/tree/main/figures"
click node_selector "https://github.com/microsoft/mnemis/blob/main/global_selection/global_selector.py"
click node_prompts "https://github.com/microsoft/mnemis/blob/main/global_selection/prompts.py"
click node_locomo "https://github.com/microsoft/mnemis/tree/main/results/locomo"
click node_lmes "https://github.com/microsoft/mnemis/tree/main/results/lme-s"
click node_locomo_results "https://github.com/microsoft/mnemis/blob/main/results/locomo/results_graphiti_gpt-41-mini-shortco-2025-04-14-Bing_gpt-41-mini-shortco-2025-04-14-Bing_ragtopk10_gtopk20_RAG_GRAPH.json"
click node_locomo_metrics "https://github.com/microsoft/mnemis/blob/main/results/locomo/metrics_graphiti_gpt-41-mini-shortco-2025-04-14-Bing_gpt-41-mini-shortco-2025-04-14-Bing_ragtopk10_gtopk20_RAG_GRAPH.json"
click node_lmes_results "https://github.com/microsoft/mnemis/blob/main/results/lme-s/results_graphiti_gpt-41-mini-shortco-2025-04-14-Bing_gpt-41-mini-shortco-2025-04-14-Bing_ragtopk10_gtopk20_RAG_GRAPH.json"
click node_lmes_metrics "https://github.com/microsoft/mnemis/blob/main/results/lme-s/metrics_graphiti_gpt-41-mini-shortco-2025-04-14-Bing_gpt-41-mini-shortco-2025-04-14-Bing_ragtopk10_gtopk20_RAG_GRAPH.json"

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_readme,node_paper,node_figures toneBlue
class node_selector,node_prompts,node_system1,node_system2,node_basegraph,node_hgraph toneAmber
class node_locomo,node_lmes,node_locomo_results,node_locomo_metrics,node_lmes_results,node_lmes_metrics toneMint
class node_graphiti toneRose
```

## Components

### Docs & paper

Narrative, paper assets, and explanatory figures.

- [README](https://github.com/microsoft/mnemis/blob/main/README.md): docs · Repository overview and reproduction notes. · `README.md`
- [Paper](https://github.com/microsoft/mnemis/blob/main/Mnemis_paper.pdf): paper pdf · Mnemis paper and system description. · `Mnemis_paper.pdf`
- [Figures](https://github.com/microsoft/mnemis/tree/main/figures): paper figures · Diagrams and visuals used in the paper. · `figures`

### Selection core

The repository's algorithmic module for global selection.

- [Selector](https://github.com/microsoft/mnemis/blob/main/global_selection/global_selector.py): retrieval logic · Global selection logic for the hierarchical route. · `global_selection/global_selector.py`
- [Prompts](https://github.com/microsoft/mnemis/blob/main/global_selection/prompts.py): prompt templates · LLM prompts that steer the selection policy. · `global_selection/prompts.py`
- **System 1**: local similarity · Base-graph similarity retrieval route described by the paper.
- **System 2**: global selection · Coverage-oriented hierarchical retrieval route.
- **Base graph**: memory graph · Local semantic recall layer used as retrieval substrate.
- **Hier graph**: hierarchical graph · Higher-level graph used for top-down selection.

### Evaluation artifacts

Saved benchmark outputs and metrics for offline reproduction.

- [LoCoMo](https://github.com/microsoft/mnemis/tree/main/results/locomo): benchmark · Saved evaluation outputs for the LoCoMo benchmark. · `results/locomo`
- [LME-S](https://github.com/microsoft/mnemis/tree/main/results/lme-s): benchmark · Saved evaluation outputs for LongMemEval-S. · `results/lme-s`
- [LoCoMo results](https://github.com/microsoft/mnemis/blob/main/results/locomo/results_graphiti_gpt-41-mini-shortco-2025-04-14-Bing_gpt-41-mini-shortco-2025-04-14-Bing_ragtopk10_gtopk20_RAG_GRAPH.json): run outputs · Generated answer/context traces for LoCoMo. · `results/locomo/results_graphiti_gpt-41-mini-shortco-2025-04-14-Bing_gpt-41-mini-shortco-2025-04-14-Bing_ragtopk10_gtopk20_RAG_GRAPH.json`
- [LoCoMo metrics](https://github.com/microsoft/mnemis/blob/main/results/locomo/metrics_graphiti_gpt-41-mini-shortco-2025-04-14-Bing_gpt-41-mini-shortco-2025-04-14-Bing_ragtopk10_gtopk20_RAG_GRAPH.json): eval metrics · Metrics for LoCoMo runs. · `results/locomo/metrics_graphiti_gpt-41-mini-shortco-2025-04-14-Bing_gpt-41-mini-shortco-2025-04-14-Bing_ragtopk10_gtopk20_RAG_GRAPH.json`
- [LME-S results](https://github.com/microsoft/mnemis/blob/main/results/lme-s/results_graphiti_gpt-41-mini-shortco-2025-04-14-Bing_gpt-41-mini-shortco-2025-04-14-Bing_ragtopk10_gtopk20_RAG_GRAPH.json): run outputs · Generated answer/context traces for LongMemEval-S. · `results/lme-s/results_graphiti_gpt-41-mini-shortco-2025-04-14-Bing_gpt-41-mini-shortco-2025-04-14-Bing_ragtopk10_gtopk20_RAG_GRAPH.json`
- [LME-S metrics](https://github.com/microsoft/mnemis/blob/main/results/lme-s/metrics_graphiti_gpt-41-mini-shortco-2025-04-14-Bing_gpt-41-mini-shortco-2025-04-14-Bing_ragtopk10_gtopk20_RAG_GRAPH.json): eval metrics · Metrics for LongMemEval-S runs. · `results/lme-s/metrics_graphiti_gpt-41-mini-shortco-2025-04-14-Bing_gpt-41-mini-shortco-2025-04-14-Bing_ragtopk10_gtopk20_RAG_GRAPH.json`

### External runtime

Upstream graph-memory framework used by the repo.

- **Graphiti**: external framework · Upstream graph-memory framework that underpins the implementation.

## Connections

- README → Selector: describes · README documents the implemented selection component.
- README → Graphiti: builds on · Repo narrative positions Graphiti as the upstream memory framework.
- Paper → System 1: defines · Paper explains the dual-route retrieval design.
- Paper → System 2: defines · Paper explains the hierarchical global-selection route.
- Figures → Hier graph: illustrates · Figures visualize the hierarchical memory structure.
- Graphiti → Base graph: provides · External framework supplies the underlying graph-memory substrate.
- Graphiti → Hier graph: supports · Hierarchical memory layer sits on top of the framework.
- Base graph → System 1: feeds · Base graph is used for similarity-based recall.
- Hier graph → System 2: feeds · Hierarchical graph is used for global selection.
- System 1 → Selector: candidates · Local retrieval provides candidates into the selection pipeline.
- Selector → Prompts: uses · Selector delegates reasoning through task prompts.
- Prompts → System 2: guides · Prompt templates encode the selection policy.
- Selector → LME-S results: produces · Selection pipeline is reflected in saved benchmark outputs.
- Selector → LoCoMo results: produces · Selection pipeline is reflected in saved benchmark outputs.
- LoCoMo → LoCoMo results: contains · LoCoMo run traces are stored under the benchmark directory.
- LoCoMo → LoCoMo metrics: contains · LoCoMo metrics are stored under the benchmark directory.
- LME-S → LME-S results: contains · LongMemEval-S run traces are stored under the benchmark directory.
- LME-S → LME-S metrics: contains · LongMemEval-S metrics are stored under the benchmark directory.
- System 2 → LoCoMo metrics: evaluated by · Global-selection behavior is assessed via benchmark metrics.
- System 2 → LME-S metrics: evaluated by · Global-selection behavior is assessed via benchmark metrics.
