# suanmosuanyangtechnology/memorybear architecture

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

- Interactive diagram: https://gitdiagram.com/suanmosuanyangtechnology/memorybear
- Repository: https://github.com/suanmosuanyangtechnology/memorybear

## Overview

MemoryBear is an AI memory management system that turns conversations and documents into structured, evolving knowledge and makes that knowledge available for later retrieval. Its principal workflow is API submission, memory extraction, graph-backed persistence, and hybrid search; forgetting and scheduled self-reflection maintain the memory over time. The graph preserves the documented extraction, graph storage, hybrid retrieval, forgetting, and reflection capabilities. Some internal connections are based on the README’s architecture description; unverified implementation links are shown as dashed.

Main entry points: [`api/app/controllers/service/memory_api_controller.py`](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/controllers/service/memory_api_controller.py) (Service Endpoints), [`api/app/core/memory/memory_service.py`](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/memory_service.py) (Memory Service), [`api/app/core/memory/storage_services/extraction_engine/extraction_pipeline_orchestrator.py`](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/storage_services/extraction_engine/extraction_pipeline_orchestrator.py) (Knowledge Extraction), [`api/app/core/memory/storage/provider/neo4j/graph_writer.py`](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/storage/provider/neo4j/graph_writer.py) (Graph Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Service API"]
  node_service_api["Service Endpoints"]
  node_memory_api["Memory Operations API"]
end

subgraph group_memory["Memory Lifecycle"]
  node_memory_service["Memory Service<br/>[memory_service.py]"]
  node_write_pipeline["Write Pipelines<br/>[write_pipeline.py]"]
  node_extraction["Knowledge Extraction"]
  node_llm["LLM and Embeddings<br/>[llm_client.py]"]
end

subgraph group_retrieval["Knowledge Retrieval"]
  node_graph_storage[("Graph Storage<br/>[graph_writer.py]")]
  node_search["Memory Search<br/>[content_search.py]"]
  node_rag_retrieval["Knowledge Graph Retrieval"]
  node_vector_search[("Elasticsearch Search<br/>[client.py]")]
end

subgraph group_operations["Memory Operations"]
  node_forgetting["Forgetting Engine"]
  node_reflection["Self-Reflection<br/>[self_reflexion.py]"]
  node_scheduler["Async Task Queues<br/>[scheduler.py]"]
end

node_user(("AI Integrator"))
node_neo4j[("Neo4j")]
node_elasticsearch[("Elasticsearch")]

node_user -->|"submits memory"| node_service_api
node_user -->|"manages memory"| node_memory_api
node_memory_api -->|"invokes"| node_memory_service
node_service_api -.->|"exposes memory operations"| node_memory_service
node_memory_service -.->|"dispatches writes"| node_write_pipeline
node_write_pipeline -.->|"runs extraction"| node_extraction
node_extraction -.->|"uses models"| node_llm
node_extraction -->|"writes triples"| node_graph_storage
node_graph_storage -->|"stores graph"| node_neo4j
node_service_api -->|"offers search"| node_search
node_search -.->|"uses keyword and vector search"| node_vector_search
node_vector_search -->|"keyword retrieval"| node_elasticsearch
node_service_api -.->|"offers graph retrieval"| node_rag_retrieval
node_memory_service -->|"controls forgetting"| node_forgetting
node_scheduler -->|"schedules reflection"| node_reflection
node_reflection -.->|"optimizes associations"| node_graph_storage

click node_service_api "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/controllers/service/memory_api_controller.py"
click node_memory_api "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/controllers/memory_storage_controller.py"
click node_memory_service "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/memory_service.py"
click node_write_pipeline "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/pipelines/write_pipeline.py"
click node_extraction "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/storage_services/extraction_engine/extraction_pipeline_orchestrator.py"
click node_llm "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/llm_tools/llm_client.py"
click node_graph_storage "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/storage/provider/neo4j/graph_writer.py"
click node_search "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/read_services/search_engine/content_search.py"
click node_rag_retrieval "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/mem-knowledge/src/rag/knowledge_graph/retrieval_pipeline.py"
click node_vector_search "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/storage/provider/elasticsearch/client.py"
click node_forgetting "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/storage_services/forgetting_engine/forgetting_engine.py"
click node_reflection "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/storage_services/reflection_engine/self_reflexion.py"
click node_scheduler "https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/celery_task_scheduler/scheduler.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_service_api,node_memory_api toneBlue
class node_memory_service,node_write_pipeline,node_extraction,node_llm,node_neo4j,node_elasticsearch toneAmber
class node_graph_storage,node_search,node_rag_retrieval,node_vector_search toneMint
class node_forgetting,node_reflection,node_scheduler toneRose
class node_user toneIndigo
```

## Components

### Service API

- [Service Endpoints](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/controllers/service/memory_api_controller.py): `api/app/controllers/service/memory_api_controller.py`
- [Memory Operations API](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/controllers/memory_storage_controller.py): `api/app/controllers/memory_storage_controller.py`

### Memory Lifecycle

- [Memory Service](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/memory_service.py): `api/app/core/memory/memory_service.py`
- [Write Pipelines](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/pipelines/write_pipeline.py): `api/app/core/memory/pipelines/write_pipeline.py`
- [Knowledge Extraction](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/storage_services/extraction_engine/extraction_pipeline_orchestrator.py): `api/app/core/memory/storage_services/extraction_engine/extraction_pipeline_orchestrator.py`
- [LLM and Embeddings](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/llm_tools/llm_client.py): `api/app/core/memory/llm_tools/llm_client.py`

### Knowledge Retrieval

- [Graph Storage](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/storage/provider/neo4j/graph_writer.py): `api/app/core/memory/storage/provider/neo4j/graph_writer.py`
- [Memory Search](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/read_services/search_engine/content_search.py): `api/app/core/memory/read_services/search_engine/content_search.py`
- [Knowledge Graph Retrieval](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/mem-knowledge/src/rag/knowledge_graph/retrieval_pipeline.py): `mem-knowledge/src/rag/knowledge_graph/retrieval_pipeline.py`
- [Elasticsearch Search](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/storage/provider/elasticsearch/client.py): `api/app/core/memory/storage/provider/elasticsearch/client.py`

### Memory Operations

- [Forgetting Engine](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/storage_services/forgetting_engine/forgetting_engine.py): `api/app/core/memory/storage_services/forgetting_engine/forgetting_engine.py`
- [Self-Reflection](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/core/memory/storage_services/reflection_engine/self_reflexion.py): `api/app/core/memory/storage_services/reflection_engine/self_reflexion.py`
- [Async Task Queues](https://github.com/suanmosuanyangtechnology/memorybear/blob/main/api/app/celery_task_scheduler/scheduler.py): `api/app/celery_task_scheduler/scheduler.py`

### Other components

- **AI Integrator**
- **Neo4j**
- **Elasticsearch**

## Connections

- AI Integrator → Service Endpoints: submits memory (evidence: `README.md`)
- AI Integrator → Memory Operations API: manages memory (evidence: `README.md`)
- Memory Operations API → Memory Service: invokes (evidence: `api/app/controllers/memory_storage_controller.py`)
- Service Endpoints → Memory Service: exposes memory operations
- Memory Service → Write Pipelines: dispatches writes
- Write Pipelines → Knowledge Extraction: runs extraction
- Knowledge Extraction → LLM and Embeddings: uses models
- Knowledge Extraction → Graph Storage: writes triples (evidence: `README.md`)
- Graph Storage → Neo4j: stores graph (evidence: `README.md`)
- Service Endpoints → Memory Search: offers search (evidence: `README.md`)
- Memory Search → Elasticsearch Search: uses keyword and vector search
- Elasticsearch Search → Elasticsearch: keyword retrieval (evidence: `README.md`)
- Service Endpoints → Knowledge Graph Retrieval: offers graph retrieval
- Memory Service → Forgetting Engine: controls forgetting (evidence: `README.md`)
- Async Task Queues → Self-Reflection: schedules reflection (evidence: `README.md`)
- Self-Reflection → Graph Storage: optimizes associations