How microsoft/mnemis works
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_selector.py Selector · README.md README · Mnemis_paper.pdf Paper · locomo LoCoMo
Components 16
Docs & paper
Narrative, paper assets, and explanatory figures.
Selection core
The repository's algorithmic module for global selection.
- Selector · Global selection logic for the hierarchical route.
global_selection/global_selector.py - Prompts · LLM prompts that steer the selection policy.
global_selection/prompts.py - System 1 · Base-graph similarity retrieval route described by the paper.
- System 2 · Coverage-oriented hierarchical retrieval route.
- Base graph · Local semantic recall layer used as retrieval substrate.
- Hier graph · Higher-level graph used for top-down selection.
Evaluation artifacts
Saved benchmark outputs and metrics for offline reproduction.
- LoCoMo · Saved evaluation outputs for the LoCoMo benchmark.
results/locomo - LME-S · Saved evaluation outputs for LongMemEval-S.
results/lme-s - LoCoMo results · 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 · 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 · 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 · 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 · Upstream graph-memory framework that underpins the implementation.
Connections 20
- 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.